Various template fields in the forms designer can use Handlebars to render JSON data into HTML that you can display to your users.
This JSON data will generally be generated by a default function or, in the case of the AJAX template, by making requests to publicly available workers and End Points.
API Server Responses
Requests to the API Server take the form of a JSON Object. The response is also a JSON Object. The result will have the structure:
{
"jsonrpc": "2.0",
"id": id,
"result": result,
}
The result can be in any valid JSON format.
Remember that if you are using the .utilServerAPIServerCall helper function, a certain amount of processing will take place, so you won't necessarily see all of the nesting you might get back from your End Point.
Security Note
It's important to remember the difference between a template field's value and what it displays. All of the data you request from the API Server will be returned as the value of your field. You might only choose to display one property from the response in your template, but all of the data you requested is still there, and accessible to someone using their browser developer tools. Make sure that you only request and return the data you need!
Accessing a Simple String Result
If the API Server returns a result as a single string, the Handlebars template can access it using a single dot {{.}}.
API Server Response
{
"jsonrpc": "2.0",
"id": 82,
"result": "October 31st 2016, 12:19:11 pm"
}
Template
<p>Today's Date: {{.}}</p>
Result
Today's Date: October 31st 2016, 12:19:11 pm
Handlebars Paths
Handlebars supports nested paths, making it simple to look up properties below the current context.
API Server Response
{
"jsonrpc": "2.0",
"id": 51,
"result": {
"subject": {
"processDefinitionId": "onlineauction:2:248",
"description": "Online Auction",
"userId": "TIMG",
"processDefinitionKey": "onlineauction"
}
}
}
Template
<p>Process: {{subject.description}}</p>
Result
Process: Online Auction
Iterating over Lists #each
The #each helper is used to access multiple items within arrays and objects.
API Server Response
{
"jsonrpc": "2.0",
"id": 113,
"result": {
"multipleItemData": [{
"_ItemClass": "CSObject",
"ObjectData": {
"FIRSTNAME": "Leo",
"SECONDNAME": "Haynes"
}
}, {
"_ItemClass": "CSObject",
"ObjectData": {
"FIRSTNAME": "Tim",
"SECONDNAME": "Gulliver"
}
}],
"itemData": {
"_ItemClass": "CSObjectMultiple"
}
}
}
Template
Note the dot notation to access nested values.
{{#each multipleItemData}}
<p>{{ObjectData.FIRSTNAME}}</p>
{{/each}}
Result
Leo
Tim
Current Element {{this}}
{{this}} represents the current array element or property value. It can be used with {{#each}}.
API Server Response
{
"jsonrpc": "2.0",
"id": 69,
"result": {
"data": ["One", "Two", "Three"]
}
}
Template
{{#each data}}
<p>{{this}}</p>
{{/each}}
Result
One
Two
Three
{{@index}} and {{@key}}
{{@index}} and {{@key}} provide access to the current index or key. To access an element in an array use .[index]
API Server Response
{
"jsonrpc": "2.0",
"id": 145,
"result": {
"result": {
"name1": "value1",
"name2": "value2"
}
}
}
Template
{{#each result}}
<p>{{@index}} {{@key}} : {{this}}</p>
{{/each}}
Result
0 name1 : value1
1 name2 : value2
Shifting Context #with
The #with helper can be used to shift the context for a section of the template, which means you don't have to repeat long nested paths.
API Server Response
{
"jsonrpc": "2.0",
"id": 113,
"result": {
"multipleItemData": [{
"_ItemClass": "CSObject",
"ObjectData": {
"FIRSTNAME": "Leo",
"SECONDNAME": "Haynes"
}
}, {
"_ItemClass": "CSObject",
"ObjectData": {
"FIRSTNAME": "Tim",
"SECONDNAME": "Gulliver"
}
}],
"itemData": {
"_ItemClass": "CSObjectMultiple"
}
}
}
Template
{{#each multipleItemData}}
{{#with ObjectData}}
{{FIRSTNAME}}
{{/with}}
{{/each}}
Result
Leo
Tim
Conditionally Rendering Blocks #if, #else, #unless
The #if helper will only display a block if the result is true. #else will display a block if the #if is false. #unless inverts the test.
API Server Response
{
"jsonrpc": "2.0",
"id": 51,
"result": {
"subject": {
"processDefinitionId": "onlineauction:2:248",
"description": "Online Auction",
"proxyUserId": "Admin",
"userId": "TIMG",
"processDefinitionKey": "onlineauction"
}
}
}
Template
<p>Process: {{subject.description}}</p>
{{#if subject.proxyUserId}}
<p>Started by {{subject.proxyUserId}} on behalf of {{subject.userId}}</p>
{{else}}
<p>Started by {{subject.userId}}</p>
{{/if}}
Result
Process: Online Auction
Started by Admin on behalf of TIMG
Timestamps
Here's a nice example for handling dates and times stored as a Unix timestamp. You most commonly see these in data returned from the History worker. This example uses the formatDate helper from the Swag library.
API Server Response
{
"jsonrpc": "2.0",
"id": 29,
"result": {
"result": {
"labela": "Online Auction",
"labelb": "7703-9601-1534-2710",
"labeld": null,
"labele": null,
"labelc": null,
"created": 1513938289210,
"sealed": true,
"subject": {},
"lastupdated": 1514881805800,
"id": "41b67cc3-69e5-4eba-a87c-5137f2827f46",
"events": [{}, {}]
},
"id": "_92",
"jsonrpc": "2.0"
}
}
Template
{{formatDate result.created "%Y %B %e at %l:%M%p"}}
Result
2017 December 22 at 10:24AM
Share this page
