Use doT tempate language

Compose flow-node templates

API Builder's Compose flow-node allows you to transform the structure of your data within an orchestrated flow. It uses doTa powerful template engine similar to Mustache or Handlebars. The Compose flow-node (@axway/api-builder-plugin-fn-dot) comes installed with all new API Builder projects. Additional information about the usage of the doT plugin can be found in the plugin's README, and information about the doT template language can be found here.

The Compose flow-node has two methods: Format string and Format object. The Format string method will run the template engine and return the result as a string. The Format object will run the template engine and parse the result as a JSON object. Both functions require two parameters: data and template.

Parameter: data 

The data parameter refers to content which is provided to the template when it is evaluated at runtime. It is the selector or JSON object that you want to pass to the doT template engine for formatting. The data can be a selector or a JSON object. A JSON object can be a JSON string, null, Boolean, array, or IIRC. In API Builder flows, the $ is a JSON path selector that selects data from the runtime context. You can pass the whole runtime context into the doT template engine or you can use the selector to choose and pass specific data elements. For example, you can use $.params.username to return a string or $.username to return an array of usernames. At design time, it is useful to have an understanding of the data that you are querying and an understanding of what the JSON path selector will return.

Parameter: template

A doT template is a string which contains a mixture of static and dynamic content. Together with the template, the data parameter is fed into the template engine at runtime. The data parameter is referred to as "it" within the template.

Dynamic content is evaluated inside double curly brackets {{}}. In this example, "My name is {{=it}}", the string "My name is" is static content and "{{=it}}" is calculated dynamically based on the data parameter passed into the template at runtime.

The curly brackets {{}} can be used in many ways, based on how you want to dynamically generate the resulting object or string. The most common one is {{= }}. This is the "interpolation delimiter", in other words, the code inserted within the curly brackets will be stringified and included in the output data. This is a list of all the delimiters:

Delimiter Description

{{ }}

Evaluation

{{= }}

Interpolation

{{! }}

Interpolation with encoding

{{# }}

Compile-time evaluation/includes and partials

{{## #}}

Compile-time defines

{{? }}

Conditionals

{{~ }}

Array iteration

Simple examples of data, templates, JSON path, and interpolation

Data Template Output
  {{="Hello"}}, Joe Hello, Joe

"Greetings"

{{=it}}, Joe Greetings, Joe
{ "greeting": "Good day" } {{=it.greeting}}, Joe Good day, Joe
[ 1, 2, 3, 4 ] {{=it.includes(5)}} false

Format string example

Here you can see how data and templates are used together in the flow editor for outputting a string. The "Format string" method has been selected. As with any values, data can be input into the doT flow-node as hard-coded object value, or as a selector. In this case, the selector $.params is used. The $.params selector refers to an object containing parameters that were included in the request. In this example, imagine that $.params looks like the following object when the flow is invoked:

$.params
Template
Output
{ "username": "Joe" }
My name is {{=it.username}} My name is Joe

With the template value of "My name is {{=it.username}}.", the flow-node will take the username property from the object passed in as data and evaluate the string as "My name is Joe Bloggs."

Format object example

This example shows how to build a JSON object dynamically using the Format object method of the doT flow-node. Similar to the previous example, the interpolation delimiter {{= }} is used to insert dynamic data. In this template, a JSON object is formatted where the keys are static and the values are dynamically provided.

Data Template Output
{
"username": "Joe",
"favoriteFoods": [ "apple", "orange" ]
}

{
"name": "{{=it.username}}",
"likes": "{{=it.favoriteFoods}}"
}

{
"name": "Joe",
"likes": "apple orange"
}

doT Examples

Interpolation

Data Template Output
"foobar"
"{{= it.match(/foo/).toString().toUpperCase() }}"
"FOO"

Evaluation with HTML encoding

Data Template Output
"You & I"

{{!it}} like API Builder!

You & I like API Builder!

Compose a new JSON object

Data Template Output
{
"username": "Joe",
"favoriteFoods": [ "apples", "oranges" ]
}

{
"name": "{{=it.username}}",
"likes": {{=JSON.stringify(it.favoriteFoods)}}
}

{
"name": "Joe",
"likes": [ "apples", "oranges" ]
}

Compile-time definitions

Data Template Output

{
"name":"Joe",
"auth": true
}

{{##def.snippet1:
{{=it.name}} {{?it.auth}} - you are authorized{{?}}
#}}

Hello, {{#def.snippet1}}

Hello, Joe - you are authorized        

Compile-time definitions with parameters

Data Template Output

{
"name":"Joe",
"auth": true
}

{{##def.block1:param:
<user {{?param.auth}}authorized{{?}}>{{=param.name}}</user>
#}}
{{#def.block1 :it }}

<user authorized>Joe</user>

Array manipulation

Data Template Output
{
"username": "Joe",
"favoriteFoods": [ "apples", "oranges" ]
}

{
"name": "{{=it.username}}",
"likes": "{{=it.favoriteFoods.join(' and ')}}"
}

{
"name": "Joe",
"likes": "apples and oranges"
}

Conditionals

Data Template Output
{
"username": "Joe"
}

My name is {{=it.username}}{{? it.favoriteFoods }} and I like {{=it.favoriteFoods.join(' and ')}}{{?}}.

My name is Joe.

{
"username": "Joe",
"favoriteFoods": [ "apple", "orange" ]
}
My name is {{=it.username}} {{? it.favoriteFoods }} and I like {{=it.favoriteFoods.join(' and ')}}{{?}}.
My name is Joe and I like apples and oranges.

Conditional if/else

Data Template Output

{
"username": "Sam"
}

{{? it.username === "Joe" }}
Hello Joe!
{{??}}
I don't know you
{{?}}
I don't know you

Array loops

Data Template Output
["apple", "banana", "orange"]

[
{{~ it :value:i}}
"{{=value}}-{{=i}}"
{{? i < it.length - 1}}, {{?}}
{{~}}
]

[ "apple-0" , "banana-1" , "orange-2" ]

JavaScript function with no parameter

Data Template Output
{}
{{##def.myfunc = function() {
return Date.now();
}
#}}
{timestamp: {{#def.myfunc()}}}
{timestamp: 1535531752947}

JavaScript function with a string parameter

Data Template Output
{ name: "Joe" }

{{##def.myfunc = function(str) {
return str;
}
#}}

{user: "{{#def.myfunc( "\{\{=it.name\}\}" )}}"}

{user: "Joe"}

JSON stringify

Data Template Output
{
"username": "Joe",
"favoriteFoods": [ "apple", "orange" ]
}

{ 
"name": {{=JSON.stringify(it.username)}}, 
"likes": {{=JSON.stringify(it.favoriteFoods)}} 
}

{
"name": "Joe",
"likes": "apple orange"
}

Related Links