Templating overview#

Mockoon implements Handlebars, Faker.js v7.6.0, and a set of custom helpers to create dynamic responses. This templating system is supported in the response's body, headers, file content, and file path. You will find below a global overview of how and where you can use helpers. You can also check the available helpers on specific documentation pages.

Helpers#

Handlebars syntax#

All the helpers must be used according to Handlebars' syntax, for example: {{helperName param1 param2}}. Some helpers accepting options objects can be used with Handlebars' object params: {{faker 'date.month' abbr=false}}.

Please note that a space always follows the helper name and separates each and all params like in oneOf *space* (array *space* 'item1' *space* 'item2'). Also, parenthesis serves to prioritize a helper over another but not to symbolize a function call. Helpers do not require parenthesis in order to work.

All Handlebars helpers are available (if, each, etc.). For more information, please have a look at Handlebars' documentation.

Special characters escaping#

Handlebars will escape special characters (& < > " ' ` =) by default. If you want to avoid this behavior, you can use the triple curly braces syntax:{{{helperName}}}.

Available helpers#

Besides Handlebars built-in helpers, Mockoon offers many of them:

• custom helpers
• request helpers
• response helpers
• Faker.js library helpers

Usages#

Body and file content templating#

Templating will work in the body editor without consideration for the Content-Type that has been defined. It will also work with files content for a limited set of MIME types (application/json, text/html, text/css, text/csv, application/javascript, application/typescript, text/plain, application/xhtml+xml, application/xml).

Here is an example of what you can do with this templating system:

Copy
{
  "userId": "{{urlParam 'id'}}",
  "name": "{{queryParam 'name' 'John'}}",
  "lang": "{{{header 'Accept-Language' 'en'}}}",
  "elementTitle": "{{body 'elements.0.title' 'default'}}",
  "ip": "{{ip}}",
  "method": "{{method}}",
  "hostname": "{{hostname}}",
  "friends": [
    {{#repeat 2}}
    { 
      "id": {{@index}}, 
      "name": "{{faker 'name.firstName'}} {{faker 'name.lastName'}}" 
    }
    {{/repeat}}
  ], 
  "oneItem": "{{oneOf (array 'item1' 'item2' 'item3')}}", 
  "someItemsAsString": "{{someOf (array 'item1' 'item2' 'item3') 1 2}}", 
  "someItemsAsArray": {{{someOf (array 'item1' 'item2' 'item3') 1 2 true}}}, 
  "userName": 
    {{#switch (urlParam 'id')}}
      {{#case '1'}}"John"{{/case}}
      {{#case '2'}}"Jack"{{/case}}
      {{#default}}"Peter"{{/default}}
    {{/switch}}
}

The above template produces the following body with this request:

Copy
GET /user/123456?name=john
Accept-Language: fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7

{
  "element": [
    {"title": "My title"}
  ]
}

Response:

Copy
{
  "userId": "5",
  "name": "john",
  "lang": "fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7",
  "elementTitle": "My title",
  "ip": "::1",
  "method": "GET",
  "hostname": "localhost",
  "friends": [
    {
      "id": 0,
      "name": "Stephen Bradbury"
    },
    {
      "id": 1,
      "name": "Warren Caffey"
    }
  ],
  "oneItem": "item1",
  "someItemsAsString": "item2",
  "someItemsAsArray": ["item2", "item3"],
  "userName": "John"
}

This system is flexible enough to generate a lot of different contents like CSV files:

Copy
firstname,lastname,countryCode
{{#repeat 10}}
  {{faker 'name.firstName'}},{{faker 'name.lastName'}},{{faker
    'address.countryCode'
  }}
{{/repeat}}

Response:

Copy
firstname,lastname,countryCode
Max,Magby,AZ
Stan,Muldoon,HM
Drew,Rebelo,CY
Cory,Neal,BG
Grace,Whitson,CY
Haydee,Backer,ET
Erik,Friedrich,MX
Stephen,Paquette,PH
Neida,Durrett,PN
Vaughn,Neal,MO

Base64 encoding#

By using the base64 helper, you can encode parts or entirety of the response by enclosing the content in a block helper.
Inline helper:

Copy
{{base64 'test'}}
{{base64 (body 'path.to.property')}}

Block helper:

Copy
{{# base64}}
firstname,lastname,countryCode
{{# repeat 10 }}
{{ faker 'name.firstName' }},{{ faker 'name.lastName' }},{{ faker 'address.countryCode' }}
{{/ repeat}}
{{/ base64}}

Disable body and file templating#

Templating can be disabled for the body and file content in each route response separately. Thus, no helper will be interpreted by the templating engine.

First, open the Route response settings:

Then, disable the templating by checking the box:

File input templating#

Templating is also supported in the file input field. It allows to dynamically serve files depending on the request parameters, like urlParam or any other helper. Example:

If you have a set of files named ./file1.json and ./file2.json, a route param can be declared (/myroute/:id) and retrieved with the urlParam helper in the file input:

c:/.../file{{urlParam 'id'}}.json.

If you call this route with /myroute/1, ./file1.json will be sent.

Headers and rule values#

Templating helpers can also be used in the headers values both in route headers and environment headers:

Finally, templating helpers can be used in the response rule values to create dynamic rules: