Templates API
Welcome to Trustisto Templates API documentation. You can use our Template API to create new templates for your Trust Overlays, Trust Bars, Trust Mails etc.
If you have any problem with our API, our developers are happy to help. You can drop us an e-mail at it@trustisto.com. We are happy to help you.
Dev Index
- JavaScript Documentation
- Templates Documentation (this page)
Introduction
Templates are HTML/CSS/JS components that can be used as Trustisto Overlays, Bars or even Mails.
As a developer, you are creating template with set of parameters which user can use to personalize that template for his need. For example user can change:
- text,
- font size and colors,
- images,
- background,
- etc.
You decide what can be changed by embedding parameters into HTML and embedded CSS code using handlebars {{...}}
) notation and describe all parameters in manifest.json
file.
Structure
Our Templates have strict structure:
template_folder/
- you can choose any name for your template foldermanifest.json
index.html
thumbnail.png
...other files, ex. css, js, images
zip -rj template.zip template_folder/*
adding: index.html (deflated 73%)
adding: manifest.json (deflated 81%)
adding: thumbnail.png (deflated 19%)
unzip -l template.zip
Archive: template.zip
Length Date Time Name
--------- ---------- ----- ----
3923 04-23-2021 14:41 index.html
3642 04-23-2021 14:41 manifest.json
7229 03-17-2021 11:47 thumbnail.png
--------- -------
14794 3 files
Template when deployed should be compressed into zip
file.
manifest.json
Manifest is a file that describe your template and all parameters.
{
"version": 1,
"name": "Template Name",
"categories": ["collect", "increase", "guide", "connect"],
"type": "popup",
"origin": "URL address of origin template, if this was cloned",
"description": {
"pl": "Polish description",
"en": "English description"
},
"width": 1200,
"height": 630,
"responsive": false,
"form": {
"fields": {
"name": "string",
"email": "string"
},
"options": {
"closeOnSubmit": false
}
},
"params-sections": {
"general": {
"title": {
"pl": "Ustawienia",
"en": "Settings"
},
"description": {
"pl": "Główne ustawienia overlaya",
"en": "Main overlay settings"
}
}
},
"params": {
"header": {
"type": "text",
"section": "general",
"label": "Headline", // without localization
"required": false,
"default": {
"pl": "Cześć <b>Świecie</b>",
"en": "Hello <b>World</b>"
},
"html-friendly": true
},
"headerFontSize": {
"type": "number",
"section": "general",
"label": {
"pl": "Rozmiar czcionki nagłówka",
"en": "Header font size"
},
"required": false,
"default": 24,
"min": 12,
"max": 36
},
"bgcolor": {
"type": "string",
"section": "general",
"label": {
"pl": "Kolor tła",
"en": "Background color"
},
"required": false,
"default": {
"pl": "#ffffff",
"en": "#ffffff"
}
},
"submitText": {
"type": "string",
"section": "general",
"label": {
"pl": "Wyślij",
"en": "Submit"
},
"required": false
}
}
name
- the name of the templatecategories
- category of the template, can be one or few, available categories:collect
- for collecting e-mail addressincrease
- for increasing salesguide
- for guiding visitorsconnect
- connecting with visitors
type
- template type, one ofpopup
(aka Overlay),topbar
,mail
origin
- url of base template (optional)description
- description of the template (localized)width
- optimal width of a template in pixelsheight
- optimal height of a template in pixelsresponsive
is this template responsive (default:true
)
Trust Bar only manifest fields:
mobile-height
- topbar height on mobile devicesmobile-breakpoint
- max width in pixel at witchmobile-height
will be applied at
Localization
Our template are fully localized, so you can provide text in different languages using JSON object with languages codes as a keys. If requested language is missing English localization en
is used as default, so please provide it. If you don't want to use localization, simple put you text as string value instead of localizing object.
Form
If template has a form that can be submitted you need to declare it in manifest in form
node (look at example on the right). Inside this node there are two objects fields
and options
In fields
you declare names (name=
) of the form fields alongside type which can be one of the following:
string
number
date
bool
In options
whish is optional, you can include following parameters:
closeOnSubmit
-true/false
Parameter Sections
Parameter section groups parameters to single logic set. Parameter sections are stored in params-sections
object, where keys are a sections individual IDs.
Single params-sections
has following properties:
title
- name of the section, visible in template editor (localized)description
- description of the section visible in template editor (localized)
Parameters
Parameters makes template dynamic and personal. When user choose your template he can change any of them. So make sure you add plenty of them to allow personalize your template.
You can group parameters into parameters sections. Parameters are stored in params
object, where keys are parameter names.
Single param
has following properties:
type
- type of parameter (see below)section
- parameter section IDlabel
- name of the parameter (localized)required
- parameter is required or no?true
/false
default
- default value of parameter (localized)html-friendly
- set totrue
if parameter can receive HTML code (see below)showWhen
- a way to show/hide parameter in Template Editor (see below)
Parameter type
:
"buttonHeight": {
"type": "number",
"min": 10,
"max": 50,
"section": "general",
"label": {
"pl": "Wysokość przycisku",
"en": "Button height"
},
"required": false
},
"buttonAnimation": {
"type": "select",
"section": "general",
"label": {
"pl": "Animacja przycisku",
"en": "Button animation"
},
"required": false,
"selectOptions": [
{
"value": "appear",
"labels": {
"pl": "Pojawienie się",
"en": "Button appear"
}
},
{
"value": "slide-in-left",
"labels": {
"pl": "Wjazd od lewej",
"en": "Slide-in from left"
}
}
]
}
text
: ex. "sample text"number
: ex. 1, you can add also specify:min
: min value of input (optional)max
: max value of input (optional)
color
: ex. "#000000"bool
: ex. true / falsedate
: date & timedateOptions
date optionsrelative
: can date be relative ex. 10 minutesabsolute
: can date be absolute ex. 08-08-2021 12:00:00
image
: URL to imageproduct
: product objectproductArray
: product array, you can also specify:min
: min amount of products (optional)max
: max amount of products (optional)
review
: review objectreviewArray
: review arrays, you can also specifymin
: min amount of reviews (optional)max
: max amount of reviews (optional)
cta
: allow user to choose action from- redirect to specific address
- copy text to clipboard
- open other Trust Overlay, Bar etc.
select
: allow user to select value from the listselectOptions
array of options (see example on the right)
Parameter showWhen
:
"buttonColor": {
"type": "color",
"section": "general",
"label": {
"pl": "Kolor przycisku",
"en": "Button color"
},
"required": false,
"showWhen": {
"otherParameterName": "isButtonVisible",
"comparisonType": "equals",
"otherParameterValue": "true"
}
}
You can display certain parameters in Template Editor based on other parameters value. This is helpful if you have some conditions like "show/hide button" and then you can specify "buttonColor".
comparisonType
: includes|equals|greaterOrEqual|lessOrEqual
index.html
This file is a entry point of a template.
<script src="https://js.trustisto.com/socialproof_succker.js"></script>
When creating index.html
you can use every HTML tag - but please check their support in older browsers. You can include custom Stylesheets and JavaScript.
<link rel="stylesheet" href="/mystyle.css">
<link rel="stylesheet" href="//other.domain.com/external-style.css">
We recommend to save all 3rd party resources inside template folder and load them via relative path.
For external sources please use URL without protocol //
, so you template can work properly in HTTP and HTTPS environment.
Parameters
<html>
<head>
<style>
h2 {
background-color: {{bg-color}};
}
</style>
</head>
<body>
<h2 ut:style="font-size: {{headerFontSize}}px;" data-html-friendly="true">{{header}}</h2>
<form>
<input type="text" name="name" />
<input type="email" name="email" />
<input type="submit" ut:text="{{submitText}}"/>
</form>
<script src="https://js.trustisto.com/socialproof_succker.js"></script>
</body>
</html>
In addition to static HTML and CSS you can include parameters using handlebars syntax {{parameter}}
. In render time (see below), this parameter will be replaced by proper value.
You can also use parameters in tag attribute. To skip browser validation perpend attribute name with ut:
ex. <img ut:src="{{imageURL}}" />
When value of a parameter will be known, name of the attribute would change.
You can add data-html-friendly="true"
if you'd like to allow user to insert HTML code in that element. Information in manifest about HTML content is only for template editor. This attribute is mandatory to make it work.
You can also use parameters inside embedded Stylesheet <style></style>
Control Visibility
In addition, you can also control visibility of tags using this attributes:
ut:hide-if="{{param}}"
- if an value passed as argument doesn't exist it will appenddisplay: none
style into the element.ut:delete-if="{{param}}"
- similar tout:hide-if
, but element will be just removed from DOMut:show-when="{{otherParameterName, otherParameterValue, comparisonType}}"
- to show or hide element based on some parameter value (look above in manifest section)
Loops
You can use ut:loop
argument to build dynamically HTML elements based on array parameters. Please check section about products (below).
Redirects
<a ut:data-redirect="http://myshop.com/target-website">Click me</a>
<a ut:data-redirect="{{some-param}}">Click me</a>
If you want to redirect client to specific page, and that action need to be measured use ut:data-redirect
attribute on <a>
tag. Whenever user click on that element, he will be redirected to specific page and that click will be measured as engage from overlay.
CTA
<a ut:cta="{{param}}">Click me</a>
If you want to make Call To Action element, you can use ut:data-cta=
attribute on a button or <a>
tag. Each of CTA types will trigger an engage event.
Product & ProductArray
{
"productName": "Product name",
"productPrice": "50",
"productCurrency": "USD",
"productImage": "assets/img/shoe.jpeg",
"productUrl": "http://shop.com/link-to-product"
}
<div ut:loop="{{products}}">
<a ut:data-redirect="{{products[].productUrl}}" >
<img src="{{products[].productImage}}" />
<span>{{products[].productName}}</span>
</a>
</div>
Our template can display products. There is a type
of a parameter product
and productArray
. You can use ut:loop=
to
iterate over product and display them, or just display single product.
Reviews
{
"userName": "John",
"rate": "5",
"timestamp": "",
"description": "This store is gr8!",
"permalink": "http://facebook.com/review/..."
}
Our template can also display users reviews, from Google, Facebook etc. There is a type
of a parameter review
and reviewArray
. You can use ut:loop=
to iterate over product and display them, or just display single product.
Forms
Your template can also have form!
You can have only one form inside template and it should be described in manifest.json
(see above)
- You should use
<form>
tag withoutaction
andmethod
attributes - Each input need to have
name=
attribute assigned to it - For validating please use HTML
required
attribute - you need to have default submit button
Counters
"deadline": {
"type": "date",
"section": "countdown",
"label": {
"pl": "Termin wygaśnięcia licznika",
"en": "Countdown final time"
},
"required": false,
"default": "",
"dateOptions": {
"relative": true,
"absolute": true
}
<div class="countdown" ut:data-deadline="{{deadline}}" ut:data-timePassedMessage="{{tooLate}}">
<span class="days"></span>
<span class="hours"></span>
<span class="minutes"></span>
<span class="seconds"></span>
</div>
Our template have build-in counter feature. So you can easily display dynamic counters in your template.
You can use parameters with counters, so user can decide what is the deadline absolute or relative.
When defining countdown in HTML you must add countdown
class to container and in that container you need to have containers with following class:
days
hours
minutes
seconds
Images
<img ut:src="{{imagePath}}" />
You can attach images to your template. Just add them to you template folder and use relative path.
You can also use image as parameters. Just use attribute evaluation ut:src={{imagePath}}
and you are done.
thumbnail.png
Thumbnail is a small, visual representation of the template. It can bee anything, from screenshot to dedicated artwork.
Requirement:
- format:
png
- width:
640px
- height:
480px
Rendering
This template:
<html>
<head>
<style>
h2 {
background-color: {{bg-color}};
}
</style>
</head>
<body>
<h2 ut:style="font-size: {{headerFontSize}}px;" data-html-friendly="true">{{header}}</h2>
<form>
<input type="text" name="name" />
<input type="email" name="email" />
<input type="submit" ut:text="{{submitText}}"/>
</form>
<script src="https://js.trustisto.com/socialproof_succker.js"></script>
</body>
</html>
with this request
GET /template_folder/
?id=1
&locale=en
&bg-color=white
&headerFontSize=12
&header=Hello
&submitText=Send
will render to this:
<html>
<head>
<style>
h2 {
background-color: white;
}
</style>
</head>
<body>
<h2 ut:style="font-size: 12px;" data-html-friendly="true">Hello</h2>
<form>
<input type="text" name="name" />
<input type="email" name="email" />
<input type="submit" text="Send"/>
</form>
<script src="https://js.trustisto.com/socialproof_succker.js"></script>
</body>
</html>
When we render a template, we call index.html
file via HTTP or HTTPS (secure) GET request with query params:
id
- id of the object that use this templatelocale
- selected locale ex.pl
,en
...other params defined in manifest
All parameters ex. {{title}}
will be replaced (evaluated) by value from (in order):
- query string parameters (so parameters witch user edited)
- manifest default value in selected locale
- manifest default value in english when locale of that parameter is not found
Testing
To test template you should open it via some kind of webserver and add following query parameters
id
- any textlocale
-en
for defaulttest
-1
- it will prevent form from submit forms and other external actions
All default parameters from manifest in selected locale (or from en
locale) will be loaded into template.
If you are using VisualStudio Code you can use this LiveServer extension
For checking template in proper size (width x height), please use Chrome Inspector and mobile devise simulator.
Samples
We have prepared you few sample templates:
FAQ
How to create a loading bar?
When rendering a template I see handlebars {{...}}
for very short period of time. Can we create a loading bar and show template after all parameters will be evaluated?
Answers
<body>
<div style="display: none;" ut:style="display:flex;">
<!-- content -->
</div>
<div style="display:flex;" ut:style="display:none;" >
Loading...
</div>
<script src="http://js.socialproof.local/socialproof_succker.js"></script>
</body>
Of course. The easiest way is to use built-in feature of evaluating attributes. For example ut:style
will overwrite style
when template will be rendered. So you can use it to show/hide content and loading message.