Templates
Treezor uses the Twig 3.x templating engine.
Like other files, templates should be base64 encoded.
Twig Basics
A template is a file that contains both structure (sometime also styling) and instructions to inject content within. Such as: "display this variable or something else if the variable is unavailable", "iterate on this array", etc.
Information – Limitations of Treezor Twig implementation
- Layouts and Blocks are unavailable
- Variables are limited to those Treezor provide
- CSS styling must be inlined (
<a style="color:orange;">my link</a>
or within a<style type="text/css"></style>
in the page's<head>
)
Emails templates
Your Email templates must produce HTML, an additional template producing TXT is also required. This TXT alternative is dedicated to clients that don't support HTML such as screen readers for the visually impaired.
Example
html
<html>
<h1>
Confirm your account
</h1>
<p>
Welcome, you are one step away from activating your account!
</p>
<a href="{{ confirmation_link }}">
Validate my account
</a>
</html>
Reading – More information on how to format templates
Checking supported endpoints
Not all Treezor endpoints support templates. To check out which endpoints can be templated, you can use the following request.
bash
curl -X GET {baseUrl}/customization/templates \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json'
Returns the complete list of customizable templates.
json
{
"templates":[
"email.user.onboarding_confirmation_html",
"email.user.onboarding_confirmation_text",
"wallet.address_details",
"wallet.statement",
"email.user.password_forgot_html",
"email.user.password_forgot_text",
"payout.proof_of_payout"
]
}
Listing available variables
To retrieve the list of variables available within a template, you can use the following request.
bash
curl -X GET {baseUrl}/customization/templates/{templateName} \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json'
Returns the details about the template, including a list of accessible variables (variables
).
json
{
"name": "payout.proof_of_payout",
"description": "Proof of Payout",
"mimeType": "text/html",
"variables": {
"wallet": {
"name": "wallet",
"type": "model",
"description": "Wallet model",
"children": [],
"parentName": null
},
"user": {
"name": "user",
"type": "model",
"description": "User model",
"children": [],
"parentName": null
},
"payout": {
"name": "payout",
"type": "model",
"description": "Payout model",
"children": [],
"parentName": null
},
"beneficiarie": {
"name": "beneficiarie",
"type": "model",
"description": "Beneficiary model",
"children": [],
"parentName": null
}
}
}
If you attempt to use a non-existent variable, an error is returned.
Uploading a template
All templates must be uploaded to the following endpoint PUT {baseUrl}/customization/templates/{templateName}/template
, where the endpointName
URL parameter corresponds to the endpoint to which you want to apply this template.
Your base64 encoded template should not contain line break (\n
)
Example
bash
curl -X PUT {baseUrl}/customization/templates/{templateName}/template \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
-d '{
"template":"ewogInRvdG8iOiAiQSBtYWduaWZpY2VudCB0ZW1wbGF0ZSAhIiAsCiAiZm9vIjoiYmFyIgp9"
}'
Caution – Replacing a Template
- Takes effect immediately.
- Cannot be undone.
Testing a template
To test a template with dummy values, you can use the following request.
bash
curl -X GET {baseUrl}/customization/templates/{templateName}/example \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json'
Returns an object containing a populated version of your template in the template
attribute.
json
{
"template":"PGh0bWw+Cjxib2R5Pgo8aDE+V2VsY29tZTwvaDE+CjxwPlBsZWFzZSA8Yj5jdXJyZW50IHVzZXIgPC9iPmNsaWNrIG9uIHRoZSBsaW5rIHRvIHZhbGlkYXRlIHlvdXIgYWNjb3VudDI6IDxhIGhyZWY9Imh0dHA6Ly9nb29nbGUuZnIiPmhlcmU8L2E+PC9wPgo8L2JvZHk+CjwvaHRtbD4="
}
Accessing a template
To retrieve a template that you have already uploaded, you can use the following request.
bash
curl -X GET {baseUrl}/customization/templates/{templateName}/template \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json'
Returns an object containing your template in the template
attribute.
json
{
"template":"ewogInRvdG8iOiAiUmVuZGVyIG5ldyB0ZW1wbGF0aW5nICEiIAp9"
}
Deleting a template
If you want to remove a template altogether, you can use the following request. The endpoint will immediately revert the indicated template to Treezor's default template.
bash
curl -X DELETE {baseUrl}/customization/templates/{templateName} \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json'
Using a template
To enable your template in a response, add the following header X-TrzConnect-Custom-Template
with a value of 1
.
bash
curl -X GET {baseUrl}/v1/users \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
-H 'X-TrzConnect-Custom-Template: 1' \ # <--- this header enables your template for this response only
# [...] parameters hidden for clarity
Errors
If something goes wrong while uploading a template, you can expect an Error object. Its message
attribute will contain useful debugging details.
Examples of errors
The twig template cannot be compiled
json
{
"errors": [
{
"type": "invalid_request",
"code": "input_validation_error",
"message": "Your template syntax is an invalid twig syntax : \"Unexpected character \"'\" in \"5eeb7991d1cd4\" at line 18.\"",
"docUrl": "https://developers.treezor.co"
}
]
}
A variable used is not available
json
{
"errors": [
{
"type": "invalid_request",
"code": "input_validation_error",
"message": "Your template is invalid : \"Variable \"my_variable\" does not exist in \"5eeb7a689e62c\" at line 12.\"",
"docUrl": "https://developers.treezor.co"
}
]
}