Mockoon templating helpers#


In addition to Handlebars' built-in helpers, Mockoon offers the following helpers:

Block helpersData buckets
repeatdata
switchdataRaw

repeat#

Repeat the block content a random number of times if two arguments are provided, or a fixed amount of time if only one argument is provided. Set the comma parameter to false (default to true) to prevent the insertion of new lines and commas by the helper.

Parameters/argumentsTypeDescription
[0]numberMinimum items
1numberMaximum items
[comma=true]booleanAdd trailing comma

Examples

Copy
{{#repeat 5 10 comma=true}}test{{/repeat}} <!-- result: test, test, test, test, test -->

switch#

Select some content depending on a variable. Behaves like a regular switch.

Arguments (ordered)TypeDescription
0anyValue against which the switch matches the cases

Examples

Copy
{{#switch (urlParam 'id')}} {{#case '1'}}"John"{{/case}} {{#case '2'}}"Jack"{{/case}} {{#default}}"Peter"{{/default}} {{/switch}}

data#

Get the stringified value at a given path from a data bucket selected by ID or name. This helper is designed to retrieve data to be served in a response. To reuse the retrieved data with other helpers (each, if, etc.), use the dataRaw helper below.

  • The path takes the following form key.0.key.5.key and is based on the object-path library. Properties containing dots are supported by escaping the dots: key.key\.with\.dot.
    Please note that a value can be retrieved at the path if the data bucket contains valid JSON.
  • Full objects or arrays can be retrieved by the helper and will be stringified.
  • The full data bucket content can be fetched when the path is omitted ({{data 'ID'}}).
Arguments (ordered)TypeDescription
0stringID or name of the daa bucket
1stringPath to the data bucket property

Examples

Copy
{{data 'abcd'}} {{data 'abcd' 'path.to.property'}} {{data 'abcd' 'deep.property\.with\.dot'}}

dataRaw#

Get the raw value (array, object, etc.) at a given path from a data bucket selected by ID or name. This "raw" helper is designed to work with other helpers (each, if, etc.). To directly use the retrieved data in the response, use data buckets direct linking or the data helper above.

  • The path takes the following form key.0.key.5.key and is based on the object-path library. Properties containing dots are supported by escaping the dots: key.key\.with\.dot.
    Please note that a value can be retrieved at the path if the data bucket contains valid JSON.
  • Primitives and data structures can be retrieved by the helper and reused in other helpers (see example below).
  • The full data bucket content (array, object, etc.) can be fetched when the path is omitted ({{dataRaw 'ID'}}).
Arguments (ordered)TypeDescription
0stringID or name of the daa bucket
1stringPath to the data bucket property

Examples

Copy
{{dataRaw 'abcd'}} {{dataRaw 'abcd' 'path.to.property'}} {{dataRaw 'abcd' 'deep.property\.with\.dot'}} {{#each (dataRaw 'path.to.array.property')}} value {{/each}} {{#if (dataRaw 'path.to.boolean.property')}} value {{/if}}

array#

Create an array from the given items. This helper is mostly used with the following helpers: oneOf, someOf.

Arguments (ordered)TypeDescription
0..nanyValue used to populate the array

Examples

Copy
{{array 'item1' 'item2' 'item3'}}

oneOf#

Select a random item in the array passed in parameters. oneOf will return the actual value in the array. Set the stringify parameter to true (default to false) to get a JSON stringified result.

Arguments (ordered)TypeDescription
0any[]Array of values
[1 = false]booleanStringify the result

Examples

Copy
{{oneOf (array 'item1' 'item2' 'item3')}} result: item2

someOf#

Return a random number of items from the array passed in parameters, concatenated as a string. Use it with triple curly braces to get a JSON representation.

Arguments (ordered)TypeDescription
0any[]Array of values
1numberMinimum number of items
2numberMaximum number of items
[3 = false]booleanGet result as an array

Examples

Copy
{{someOf (array 'item1' 'item2' 'item3') 1 2}} result: item1,item2 <!-- Use triple curly braces to avoid character escaping --> {{{someOf (array 'item1' 'item2' 'item3') x y true}}} result: item1,item2

join#

Return a new string by concatenating all the elements in an array.

Arguments (ordered)TypeDescription
0[]Array of values
1stringSeparator

Examples

Copy
{{join (array 'item1' 'item2' 'item3') '#'}} result: item1#item2#item3

slice#

Return a copy of a portion of an array from start to end indexes (not included).

Arguments (ordered)TypeDescription
0[]Array of values
1numberStart index
2numberEnd index

Examples

Copy
{{slice (array 'item1' 'item2' 'item3') 0 2}} result: ['item1', 'item2']

len#

Return an array or string length.

Arguments (ordered)TypeDescription
0[] | stringArray or string

Examples

Copy
{{len (array 'item1' 'item2' 'item3')}} result: 3 {{len 'hello'}} result: 5

filter#

Return a filtered array. This helper can be used with data buckets, use the dataRaw for that.

Arguments (ordered)TypeDescription
0any[]Input array
1..nprimitive or object or arrayOR conditions level
  • The first argument is the array to be filtered.
  • Each argument starting from index 1 is a condition filter (array 1 2 3) 1 3 5 6 .....
    • Condition can be primitives (string, number), objects or arrays with sub-conditions.
    • When the condition is an object, then all keys and values work as an AND.
    • Conditions support infinite nesting of conditions using arrays.
    • The first level of filer arguments works as OR conditions filter (array 1 2 3) 1 3 equals fo [1,2,3].filter(x => x === 3 || x === 1).
    • The second level of conditions works as AND sub-conditions list.
    • The third level of conditions works as OR sub-conditions list.
    • Nesting of conditions matches the rule OR (the first level of the arguments) -> AND -> OR -> AND -> ...
    • For a better understanding of how to build AND queries with objects please check the object helper documentation.

Structure

Copy
<!-- filter query base OR structure --> {{ filter (array 1 2 3 ... ) c1 c2 c3 ... }} result: c1 OR c2 OR c3 <!-- filter query base AND structure (the AND conditions described as sub-conditions) --> {{ filter (array x y z) (array c1 c2 c3) }} result: items that fit to c1 AND c2 AND c3 <!-- filter query a few OR from several AND conditions --> {{ filter (array x y z) (array a1 a2 a3) (array b1 b2 b3) (array c1 c2 c3) }} result: (a1 AND a2 AND a3) OR (b1 AND b2 AND b3) OR (c1 AND c2 AND c3) <!-- filter with complex nested structure --> {{ filter (array 1 2 3) (array a1 a2 (array x1 x2) ) (array b1 b2 b3) }} results: items that fit to (a1 AND a2 AND (x1 OR x2) ) OR (b1 AND b2 AND b3)

Examples

Copy
<!-- Simple OR filter --> {{filter (array 1 2 3) 1 3}} result: 1,3 <!-- Simple OR filter --> {{filter (array 'item1' 'item2' 'item3' 'item4' 'item3') 'item1' 'item2' 'item3' }} result: item1,item2,item3,item3 <!-- Data bucket get all users with type='item1' --> {{filter (dataRaw 'Users') (object type='item1')}} <!-- Data bucket get all users with type='item1' OR type='item2' OR type='item3' --> {{filter (dataRaw 'Users') (object type='item1') (object type='item2') (object type='item3') }} <!-- Data bucket get all users with type='item1' AND category='some-category' --> {{filter (dataRaw 'Users') (object type='item1' category='some-category')}} <!-- Data bucket get all users with type='item1' OR category='some-category' --> {{filter (dataRaw 'Users') (array (object type='item1') (object category='some-category')) }} <!-- Mixed data filter --> {{filter (array 'item1' 'item2' (object type='type1') (object type='type2')) 'item1' (object type='type2') }}

object#

Return an object that can be used in other helpers.

Parameters (named)TypeDescription
[string]=anyanykey=value notation of the object properties

Examples

Copy
{{{object type='item1'}}} result: {type: 'item1'} {{{object type='item1' category='cat1'}}} result: {type: 'item1', category: 'cat1'} {{{object type=(array 1 2 3)}}} result: {type: [1,2,3]} {{{object type=(array 1 2 3)}}} result: {type: [1,2,3]} {{{object type=(filter (array 1 2 3) 1 3)}}} result: {type: [1,3]}

add#

Add the numbers passed as parameters to each others. Unrecognized strings passed as arguments will be ignored.

Arguments (ordered)TypeDescription
0..nany[]Value of the operandes (can process numbers and strings)

Examples

Copy
{{add 1 1}} result: '2' {{add '1' '1'}} result: '2' {{add '1' 'foo' 1}} result: '2'

subtract#

Subtract the numbers passed as parameters to the first parameter. Unrecognized strings passed as arguments will be ignored.

Arguments (ordered)TypeDescription
0..nany[]Value of the operandes (can process numbers and strings)

Examples

Copy
{{subtract 2 1}} result: '1' {{subtract '2' '1'}} result: '1' {{subtract '2' 'foo' 1}} result: '1'

multiply#

Multiply the numbers passed as parameters to each others. Unrecognized strings passed as arguments will be ignored.

Arguments (ordered)TypeDescription
0..nany[]Value of the operandes (can process numbers and strings)

Examples

Copy
{{multiply 2 3}} result: '6' {{multiply '2' '3'}} result: '6' {{multiply '2' 'foo' 3}} result: '6'

divide#

Divide the first parameter by the other numbers passed as parameters. Unrecognized strings passed as arguments will be ignored.

Arguments (ordered)TypeDescription
0..nany[]Value of the operandes (can process numbers and strings)

Examples

Copy
{{divide 4 2}} result: '2' {{divide '4' '2'}} result: '2' {{divide '4' 'foo' 2}} result: '2'

modulo#

Compute the modulo of the first parameter by the second.

Arguments (ordered)TypeDescription
0numberFirst value (can process numbers and strings)
1numberSecond value (can process numbers and strings)

Examples

Copy
{{modulo 5 4}} result: '1' {{modulo '5' '4'}} result: '1' {{modulo '5' 'foo' 4}} result: '1'

ceil#

Ceil the value of the number passed as parameter.

Arguments (ordered)TypeDescription
0numberValue to ceil (can process numbers and strings)

Examples

Copy
{{ceil 1.5}} result: '2' {{ceil '1.5'}} result: '2'

floor#

Floor the value of the number passed as parameter.

Arguments (ordered)TypeDescription
0numberValue to floor (can process numbers and strings)

Examples

Copy
{{floor 2.5}} result: '2' {{floor '2.5'}} result: '2'

eq#

Verify if two numbers or strings are equal. Returns a boolean.
Returns false if type of the value not equals.

Arguments (ordered)TypeDescription
0string | numberFirst number or string
1string | numberSecond number or string

Examples

Copy
{{#if (eq 55 55) }} true {{/if}} Result: true {{#if (eq 55 '55') }} true {{else}} false {{/if}} Result: false {{#if (eq "x1" "x1") }} true {{/if}} Result: true

gt#

Verify if the first number is greater than the second number. Returns a boolean.

Arguments (ordered)TypeDescription
0numberFirst number
1numberSecond number

Examples

Copy
{{#if (gt 56 55)}} true {{/if}} Result: true

gte#

Verify if the first number is greater than or equal to the second number. Returns a boolean.

Arguments (ordered)TypeDescription
0numberFirst number
1numberSecond number

Examples

Copy
{{#if (gte 55 55)}} true {{/if}} Result: true

lt#

Verify if the first number is lower than the second number. Returns a boolean.

Arguments (ordered)TypeDescription
0numberFirst number
1numberSecond number

Examples

Copy
{{#if (lt 55 56)}} true {{/if}} Result: true

lte#

Verify if the first number is lower than or equal to the second number. Returns a boolean.

Arguments (ordered)TypeDescription
0numberFirst number
1numberSecond number

Examples

Copy
{{#if (lte 55 55)}} true {{/if}} Result: true

toFixed#

Format a number using fixed-point notation.

Arguments (ordered)TypeDescription
0numberA number
1numberNumber of digits

Examples

Copy
{{toFixed 1.11111 2}} Result: 1.11

round#

Return the value of a number rounded to the nearest integer.

Arguments (ordered)TypeDescription
0numberA number to round

Examples

Copy
{{round 0.499}} Result: 0

newline#

Add a newline \n.

Examples

Copy
{{newline}}

base64#

Encode the parameter as base64. This can be used as an inline helper or block helper (see examples below).

Arguments (ordered)TypeDescription
[0]anyValue to encode (optional when used as a block helper)

Examples

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

base64Decode#

Decode a base64 string. This can be used as an inline helper or block helper (see examples below).

Arguments (ordered)TypeDescription
[0]stringBase64 string to decode (optional when used as a block helper)

Examples

Copy
{{base64Decode 'YWJjZA=='}} {{#base64Decode}} {{body 'base64content'}} {{/base64Decode}}

objectId#

Create a valid ObjectId. It can generates the ObjectId based on the specified time (in seconds) or from a 12 byte string that will act as a seed. Syntax is based on bson-objectid package.

Arguments (ordered)TypeDescription
0string | numberSeed

Examples

Copy
{{objectId 1414093117}} {{objectId '54495ad94c934721ede76d90'}}

setVar#

Set a variable to be used later in the template. The value can be the result of another helper. To use it elsewhere in the template, refer to the variable with its name prefixed with an @: {{@varname}}. The variable can also be used as a helper parameter: {{#repeat @varname}}...{{/repeat}}. Variables declared in a block helper will be scoped to the block and unavailable outside.

Arguments (ordered)TypeDescription
0stringVariable name
1anyVariable value

Examples

Copy
{{setVar 'varname' 'value'}} {{setVar 'varname' (body 'id')}} usage: {{@varname}} {{#repeat @varname}}...{{/repeat}} declare a variable in a block helper: {{#repeat 5}} {{setVar 'random' (oneOf (array '1' '2' '3'))}} {{@random}} {{/repeat}} {{setVar 'myArray' (array '1' '2' '3')}} {{#each @myArray}} {{setVar 'eachIndex' @index}} {{@eachIndex}} {{/repeat}}

getVar#

Dynamically get a variable set with setVar.

Arguments (ordered)TypeDescription
0stringVariable name

Examples

Copy
{{setVar 'varname' 'value'}} {{getVar 'varname'}} {{getVar (concat 'var' 'name')}} {{getVar (body 'property')}}

includes#

Search whether a string can be found in another string and returns the appropriate boolean.

Arguments (ordered)TypeDescription
0anyData to search into
1anyData to search

Examples

Copy
{{includes 'Some data' 'data'}} result: true

substr#

Return a portion of a string starting at the specified index and extending for a given number of characters afterwards.

Arguments (ordered)TypeDescription
0anyStarting index
[1 = max length]anyLength

Examples

Copy
{{substr 'Some data' 5 4}} result: 'data'

lowercase#

Return the first string parameter lowercased.

Arguments (ordered)TypeDescription
0stringString to lowercase

Examples

Copy
{{lowercase 'ABCD'}} result: 'abcd'

uppercase#

Return the first string parameter uppercased.

Arguments (ordered)TypeDescription
0stringString to uppercase

Examples

Copy
{{uppercase 'abcd'}} result: 'ABCD'

split#

Split a string and return an array containing the multiples substrings. This helper can be used within handlebars' iterative helpers such as each. (Default separator is " ")

Arguments (ordered)TypeDescription
0stringData to split
1stringSeparator

Examples

Copy
{{#each (split '1 2 3 4')}} item{{this}}, {{/each}} result: item1,item2,item3,item4 {{#each (split 'This is my string.')}} {{this}}, {{/each}} result: This,is,my,string,

stringify#

Return objects and arrays as a formatted JSON string indented with two spaces.

Arguments (ordered)TypeDescription
0anyObject or array

Examples

Considering an entering body:

Copy
{ "prop1": "123", "prop2": { "data": "test" } }
Copy
{{{stringify (bodyRaw 'prop2')}}}
Copy
{ "data": "test" }

concat#

Concatenate multiple strings/numbers together. This helper can concatenate results from other helpers, or be used as a parameter of another helper (see examples below).

Arguments (ordered)TypeDescription
0..nanyValues to concatenate

Examples

Copy
{{concat 'value1' 2 'value3'}} {{concat @index (body 'id') 'value3'}} {{#repeat (concat 1 2 3)}}...{{/repeat}}

indexOf#

Return the index of the searched 'data' inside the string. A last parameter (number) can be passed to start the search at a specific index.

Arguments (ordered)TypeDescription
0anyData to search into
1anyData to search
[2 = 0]numberSearch starting index

Examples

Copy
{{indexOf 'Some data' 'data' 0}} result: 5

parseInt#

Parse a number from a string.

Arguments (ordered)TypeDescription
0stringString to parse

padStart#

Pads a string with a given string (repeated, if needed) until the resulting string reaches the given length. The padding is applied from the start of the string.

Arguments (ordered)TypeDescription
0stringString to pad
1numberpad length
[2 = ' ']stringPadding character(s) (default to blank space)
Copy
{{padStart '5' 5 '0'}} result: 00005

padEnd#

Pads a string with a given string (repeated, if needed) until the resulting string reaches the given length. The padding is applied from the end of the string.

Arguments (ordered)TypeDescription
0stringString to pad
1numberpad length
[2 = ' ']stringPadding character(s) (default to blank space)

Examples

Copy
{{padEnd '5' 5 '0'}} result: 50000

now#

Display the current time in the chosen format. Format syntax is based on date-fns package (v2) and is optional (default to ISO string).

Arguments (ordered)TypeDescription
0stringDate format

Examples

Copy
{{now 'YYYY-MM-DD'}}

dateTimeShift#

Shift a date by adding the number of years, months, etc. passed as parameters. The date and format parameters are optional. The helper will return the current date and time as an ISO string if omitted (yyyy-MM-ddTHH:mm:ss.SSSxxx).

Parameters (named)TypeDescription
datestringDate to shift
[format = 'yyyy-MM-ddTHH:mm:ss.SSSxxx']stringFormat of the shifted date
[years = 0]numberYears to shift
[months = 0]numberMonths to shift
[days = 0]numberDays to shift
[hours = 0]numberHours to shift
[minutes = 0]numberMinutes to shift
[seconds = 0]numberSeconds to shift

Examples

Copy
{{dateTimeShift date='2021-01-01' format='yyyy-MM-dd HH:mm:ss' years=1 months=1 days=1 hours=1 minutes=1 seconds=1 }}

date#

Return a random formatted date (using date-fns package format) between a minimum and a maximum. Uses faker 'date.between' to generate the random date.

Arguments (ordered)TypeDescription
0stringStarting date
1stringEnding date
2stringDate format

Examples

Copy
{{date '2020-11-20' '2020-11-25' "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"}}

time#

Return a random formatted time (using date-fns package format) between a minimum and a maximum. Uses faker 'date.between' to generate the random time.

Arguments (ordered)TypeDescription
0numberStarting time
1numberEnding time
2stringTime format

Examples

Copy
{{time '09:00' '10:00' 'HH:mm'}}

dateFormat#

Return a formatted date (using date-fns package format).

Arguments (ordered)TypeDescription
0string | DateDate to format
1stringOutput format

Examples

Copy
{{dateFormat '2021-01-01' 'yyyy'}} {{dateFormat (faker 'date.recent') 'yyyy'}}

int#

Return a random integer. Alias of faker 'datatype.number.

Arguments (ordered)TypeDescription
0numberMinimum
1numberMaximum

Examples

Copy
{{int 0 100}}

float#

Return a random float. Alias of faker 'datatype.number with precision = 10.

Arguments (ordered)TypeDescription
0numberMinimum
1numberMaximum

Examples

Copy
{{float 0 100}}

boolean#

Return a random boolean. Alias of faker 'datatype.boolean'.

Examples

Copy
{{boolean}}

title#

Return a random title. Alias of faker 'name.title'.

Examples:

Copy
{{title}}

firstName#

Return a random first name. Alias of faker 'name.firstName'.

Examples:

Copy
{{firstName}}

lastName#

Return a random last name. Alias of faker 'name.lastName'.

Examples:

Copy
{{lastName}}

company#

Return a random company name. Alias of faker 'company.companyName'.

Examples:

Copy
{{company}}

domain#

Return a random domain name. Alias of faker 'internet.domainName'.

Examples:

Copy
{{domain}}

tld#

Return a random top level domain. Alias of faker 'internet.domainSuffix'.

Examples:

Copy
{{tld}}

email#

Return a random email address. Alias of faker 'internet.email'.

Examples:

Copy
{{email}}

street#

Return a random address. Alias of faker 'address.streetAddress'.

Examples:

Copy
{{street}}

city#

Return a random city name. Alias of faker 'address.city'.

Examples:

Copy
{{city}}

country#

Return a random country name. Alias of faker 'address.country'.

Examples:

Copy
{{country}}

countryCode#

Return a random country code. Alias of faker 'address.countryCode'.

Examples:

Copy
{{countryCode}}

zipcode#

Return a random zip code. Alias of faker 'address.zipCode'.

Examples:

Copy
{{zipcode}}

postcode#

Return a random zip code. Alias of faker 'address.zipCode'.

Examples:

Copy
{{postcode}}

lat#

Return a random latitude. Alias of faker 'address.latitude'.

Examples:

Copy
{{lat}}

long#

Return a random longitude. Alias of faker 'address.longitude'.

Examples:

Copy
{{long}}

phone#

Return a random phone number. Alias of faker 'phone.phoneNumber'.

Examples:

Copy
{{phone}}

color#

Return a random color. Alias of faker 'commerce.color'.

Examples:

Copy
{{color}}

hexColor#

Return a random hexadecimal color code.

Examples:

Copy
{{hexColor}}

guid#

Return a random GUID. Alias of faker 'datatype.uuid'.

Examples:

Copy
{{guid}}

ipv4#

Return a random IP v4. Alias of faker 'internet.ip'.

Examples:

Copy
{{ipv4}}

ipv6#

Return a random IP v6. Alias of faker 'internet.ipv6'.

Examples:

Copy
{{ipv6}}

lorem#

Return random lorem ipsum text. Alias of faker 'lorem.sentence'.

Arguments (ordered)TypeDescription
0numberNumber of words

Examples:

Copy
{{lorem 50}}