Helpers are predefined functions that can be called from inside Handlebars templates. Helpers have names, parameters, and return values. For example, the template {{add 5 var1}} calls the add helper on an integer (5) and a variable called var1. If var1 is set to 7, then the template evaluates to 12.
Helpers fall into one of the following categories:
Helpers cannot be used in the Functions editor.
The following helpers from the Handlebars library are available. See the Handlebars documentation ↗ to learn about each helper:
The following core helpers are available within queries and widgets:
The toString helper converts any given value to a string using the JavaScript String() ↗function.
{{toString 'hello'}} renders to "hello"{{toString 1}} renders to "1"{{toString variable}} where context is { variable: ["hello", "world"] } renders to "hello,world"{{toString variable}} where context is { variable: [1, 2, 3] } renders to "1,2,3"{{toString variable}} where context is { variable: {"hello": "world"} } renders to "[Object Object]"The toNumber helper converts any given value to a number with the JavaScript Number() ↗function. If the value cannot be converted to a number, it will return NaN.
{{toNumber 1}} renders to 1{{toNumber '2'}} renders to 2{{toNumber 'hello'}} renders to NaN{{toNumber variable}} where context is { variable: [1, 2, 3] } renders to NaN{{toNumber variable}} where context is { variable: {"hello": "world"} } renders to NaNThe concat helper takes an arbitrary number of arguments and concatenates them together by first converting each argument into a string with the JavaScript String() function.
{{concat 1 2}} renders to "12"{{concat 'hello' 'world' 2}} renders to "helloworld2"{{concat array1 array2}} where context is { array1: ["hello", "world"], array2: ["again", "and again"] } renders to "helloworldagainand again"{{concat 1 2 3 variable}} where context is { variable: {"hello": "world"} } renders to "123[Object Object]"The substring helper takes an input string (value) and a start and end (optional), then passes it to the JavaScript substring() function. This enables you to get a substring of your input string.
{{substring 'foo' 0 1}} renders to "f"{{substring 'foo' 0 6}} renders to "foo"{{substring 'foo' 1}} renders to "oo"The contains helper takes an array or string (value) and a value to search for (searchValue) and returns true if the value is in the array, and false otherwise. It does this by calling value.indexOf(searchvalue) !== -1.
{{contains variable 3}} where context is { variable: [1, 2, 3] } renders to true{{contains variable "hello"}} where context is { variable: "hello world" } renders to trueThe jsonParse helper takes a JSON string as input, and parses it using JavaScript’s JSON.parse ↗ function.
{{jsonParse '\"foo\"'}} renders to "foo"{{jsonParse varA}} where context is "[\"hello\",\"world\"]" renders to ["hello", "world"]{{jsonParse varA}} where context is "{\"varA\":{\"hello\":\"world\",\"foo\":[\"bar\",\"baz\"]}}" renders to { varA: {"hello": "world", "foo": ["bar", "baz"]} }{{jsonParse 123}} throws an error in the console saying "jsonParse: Error: value must be a string"{{jsonParse varA}} where context is "[\"hello\"," throws an error in the console saying "jsonParse: SyntaxError: Unable to parse JSON string"The jsonStringify helper takes any object as input, and returns that object converted to JSON (as passed to JavaScript’s JSON.stringify ↗ function).
{{jsonStringify 'foo'}} renders to "foo" (the double-quotes are included in the rendered text){{jsonStringify varA}} where context is { varA: {"hello": "world", "foo": ["bar", "baz"]} } renders to {"hello":"world","foo":["bar","baz"]} (again, the double-quotes are in the rendered text)The add helper adds two numbers.
{{add 20 5}} renders to 25{{add 10 'abc'}} throws an error in the console saying "value must be a number"The subtract helper subtracts the second number from the first number.
{{subtract 20 5}} renders to 15{{subtract 10 'abc'}} throws an error in the console saying "value must be a number"The multiply helper multiplies two numbers.
{{multiply 20 5}} renders to 100{{multiply 10 'abc'}} throws an error in the console saying "value must be a number"The divide helper divides the first number by the second number.
{{divide 20 5}} renders to 4{{divide 10 'abc'}} throws an error in the console saying "value must be a number"The max helper finds the maximum from any given numbers or array of numbers.
{{max variable}} where context is { variable: [1, 2, 3] } renders to 3{{max variable 12 15}} where context is { variable: [1, 2, 3] } renders to 15{{max 'hello' 123}} throws an error in the console saying "value must be a number or a number array"{{max variable}} where context is { variable: ["hello", "world"] } throws an error in the console saying "value must be a number or a number array"The min helper finds the minimum from any given numbers or an array of numbers.
{{min variable}} where context is { variable: [1, 2, 3] } renders to 1{{min variable 6 10}} where context is { variable: [1, 2, 3] } renders to 1{{min 'hello' 123}} throws an error in the console saying "value must be a number or a number array"{{min variable }} where context is { variable: ["hello", "world"] } throws an error in the console saying "value must be a number or a number array"The eq helper compares two numbers or strings and checks to see if they are equal
Using eq with two numbers
{{eq 1 1}} renders to trueUsing eq on values that are not numbers or strings, or are different types
{{eq [1, 2] 5}} throws an error in the console saying "type mismatch"Using eq inside an if block
{{#if (eq name 'Steven')}}
Your name is Steven.
{{else}}
Your name is not Steven.
{{/if}}
where context is { name: "Steven" } renders to "Your name is Steven."
The ne helper compares two numbers or strings and checks to see if they are different
{{ne 1 1}} renders to false{{ne [1, 2] 5}} throws an error in the console saying "type mismatch"The lt helper compares two numbers or strings and checks if the first one is less than the second one.
{{lt 1 2}} renders to true{{lt [1, 2] 5}} throws an error in the console saying "type mismatch"The le helper compares two numbers or strings and checks if the first one is less than or equal to the second one.
{{le 1 1}} renders to true{{le [1, 2] 5}} throws an error in the console saying "type mismatch"The gt helper compares two numbers or strings and checks if the first one is greater than the second one.
{{gt 2 1}} renders to true{{gt [1, 2] 5}} throws an error in the console saying "type mismatch"The ge helper compares two numbers or strings and checks if first one is greater than or equal to the second one.
{{ge 1 1}} renders to true{{ge [1, 2] 5}} throws an error in the console saying "type mismatch"The encodeURI helper encodes any given string with the JavaScript encodeURI() ↗ function.
{{encodeURI 'hello world?'}} renders to "hello%20world?"{{encodeURI variable}} where context is { variable: [1, 2, 3] } throws an error in the console saying "value must be a string"The encodeURIComponent helper encodes any given string with the JavaScript encodeURIComponent() ↗ function.
{{encodeURIComponent 'hello world?'}} renders to "hello%20world%3F"{{encodeURIComponent variable}} where context is { variable: [1, 2, 3] } throws an error in the console saying "value must be a string"The getSelectedDisplayValue helper gets the selectedDisplayValue from displayValues given values and selectedValue.
{{getSelectedDisplayValue values displayValues selectedValue}} where context is { values: [1, 2, 3], displayValues: ["a", "b", "c"], selectedValue: 2 } returns ["b"]{{getSelectedDisplayValue values displayValues selectedValue}} where context is { values: "hello", displayValues: ["a", "b", "c"], selectedValue: 2 } throws an error in the console saying "values must be an array"{{getSelectedDisplayValue values displayValues selectedValue}} where context is { values: [1,2,3], displayValues: ["a", "b", "c"], selectedValue: 4 } throws an error in the console saying "selectedValue '4' is not in values"The getSelectedDisplayValues helper gets the selectedDisplayValues from displayValues given values and selectedValues.
{{getSelectedDisplayValues values displayValues selectedValues}} where context is { values: [1, 2, 3], displayValues: ["a", "b", "c"], selectedValues: [2, 3] } returns ["b", "c"]{{getSelectedDisplayValues values displayValues selectedValues}} where context is { values: "hello", displayValues: ["a", "b", "c"], selectedValues: 2 } throws an error in the console saying "values must be an array"{{getSelectedDisplayValues values displayValues selectedValues}} where context is { values: [1,2,3], displayValues: ["a", "b", "c"], selectedValues: [4] } throws an error in the console saying "selectedValue '4' is not in values"The lookup helper uses a variant of the built-in Handlebars lookup ↗ and may be used as described in the Handlebars documentation. In addition, Slate’s lookup variant can describe long chains of properties as in the example below.
{{lookup a "b" "c"}} where the context is { a: { b: { c: "test" } } } will return "test"The and helper performs an AND (&&) logical comparison on the supplied Boolean arguments. It requires at least two arguments.
{{and var1 var2}} where context is { var1: "true", var2: "false" } renders to "false"The or helper performs an OR (||) logical comparison on the supplied Boolean arguments. It requires at least two arguments.
{{or var1 var2}} where context is { var1: "true", var2: "false" } renders to "true"The not helper performs a NOT (!) logical comparison on the supplied Boolean argument. It can only be applied to one single argument.
{{not var}} where context is `{ var : "true" } renders to "false"The following widget helpers are available within widgets:
The formatNumber helper format any given number to a string using the Numeral.js ↗ library. Note that the value must be a number and the format must be a string.
{{formatNumber 1400 '0,0'}} renders to "1,400"
{{formatNumber 'abc' '0,0'}} throws an error in the console saying "value must be a number"{{formatNumber 1400 variable}} where context is { variable: ["hello": "world"] } throws an error in the console saying "format must be a string"The formatDate helper format any given date to a string using the Moment.js ↗ library. Note that the value must be a date and the format must be a string.
{{formatDate '2014-1-2' 'MM/DD/YYYY'}} renders to "01/02/2014"
{{formatDate 1237705200000 'YYYY-MM-DD'}} renders "2009-03-22"
{{formatDate 'some string' 'YYYY-MM-DD'}} throws an error in the console saying "value must be a valid date"{{formatDate '2014-1-2' variable}} where context is { variable: ["hello": "world"] } throws an error in the console saying "format must be a string"The following helper is available within HttpJson Foundry queries.
The joinParams helper takes an array of parameters and joins single quoted parameters with ,.
"SELECT * FROM `table1` WHERE name IN ({{joinParams names}})"
{ names: ["Bill", "John J.", "Sam's", "Jay"] }
renders to
"SELECT * FROM `table1` WHERE name IN ('Bill', 'John J.', 'Sam\'s', 'Jay')"
"SELECT * FROM table1 WHERE name IN ({{joinParams name}});"
{ name: "Bill" }
throws an error saying "parameters must be an array in joinParams helper"The following SQL helpers are available within SQL queries. Note that while HttpJson Foundry queries use Spark SQL syntax, these helpers should not be used in those queries.
The alias helper takes an alias column or table name. The column and table helpers check values against the information schema. However, temporary column or table names are not in the schema. The alias helper provides a way for the user to register temporary column or table names. It throws an error when the name is not a constant value.
Using alias to register an alias column name
"SELECT id as {{alias 'alias_column_name'}} FROM table1 ORDER BY {{column aliasColumnName}};"
where context is { aliasColumnName: "alias_column_name" } renders to
"SELECT id as alias_column_name FROM table1 ORDER BY alias_column_name;"
Using alias to register an alias case sensitive column name
"SELECT id as "{{alias 'Alias Column Name'}}" FROM table1 ORDER BY "{{column aliasColumnName}}";"
where context is { aliasColumnName: "Alias Column Name" } renders to
"SELECT id as "Alias Column Name" FROM table1 ORDER BY "Alias Column Name";"
Using alias to register an alias table name
"SELECT id as "{{alias 'Alias Column Name'}}" FROM table1 ORDER BY "{{column aliasColumnName}}";"
where context is { aliasColumnName: "Alias Column Name" } renders to
"SELECT id as "Alias Column Name" FROM table1 ORDER BY "Alias Column Name";"
Using alias with non-constant value:
"SELECT id as {{alias aliasColumnName}} FROM table1 ORDER BY {{table aliasColumnName}};"
where context is { aliasColumnName: "alias_column_name" } throws an error saying "Only constant parameters are not allowed..."
The schema helper takes a schema name and a list of whitelist names. It checks to make sure the schema name is in the list of whitelist names and checks the schema name against the data source’s information table. It throws an error when a schema name does not exist in the list of whitelist names or the information table.
"SELECT * FROM {{schema schemaName 'schema1' 'schema2'}}.table1;"
{ schemaName: "schema1" } renders to
"SELECT * FROM schema1.table1;"
"SELECT * FROM {{schema schemaName 'schema1' 'schema2'}}.table1;"
{ schemaName: "schemaNameNotInList" } renders to
"SELECT FROM schemaNameNotInList.table1"
"SELECT * FROM {{schema schemaName 'schema1' 'schema2' templatizedName}}.table1;"
{ schemaName: "schema1", templatizedName: "anotherSchemaName" } renders to
"SELECT * FROM schema1.table1;"
"SELECT * FROM {{schema schemaName 'invalidSchema1'}}.table1;"
{ schemaName: "invalidSchema1" } renders to
"SELECT * FROM invalidSchema1.table1;"
The table helper takes a table name and a list of whitelist names. It checks to make sure the table name is in the list of whitelist names and checks the table name against the data source’s information table. It throws an error when a table name does not exist in the list of whitelist names or the information table.
"SELECT * FROM {{table tableName 'table1' 'table2'}};"
{ tableName: "table1" } renders to
"SELECT * FROM table1;"
"SELECT * FROM {{table tableName 'table1' 'table2'}};"
{ tableName: "tableNameNotInList" } renders to
"SELECT * FROM tableNameNotInList;"
"SELECT * FROM {{table tableName 'table1' 'table2' templatizedName}};"
{ tableName: "table1", templatizedName: "anotherTableName" } renders to
"SELECT * FROM table1;"
"SELECT * FROM {{table tableName 'invalidTable1'}};"
{ tableName: "invalidTable1" } renders to
"SELECT * FROM invalidTable1;"
The column helper takes a column name, or a list of column names, and checks it against the data source’s information table. It throws an error when a column name does not exist in the information table.
"SELECT {{column columnName}} FROM table1;"
{ columnName: "column1" } renders to
"SELECT column1 FROM table1;"
"SELECT "{{column columnName}}" FROM table1;"
{ columnName: "Column 1" } renders to "SELECT "Column 1" FROM table1;""SELECT {{column columnNames}} FROM table1;"
{ columnNames: ["column1", "column2"] } renders to
"SELECT column1, column2 FROM table1;"
"SELECT {{column columnName}} FROM table1;"
{ columnName: "invalidColumn1" } renders to
"SELECT invalidColumn1 FROM table1;"
The param helper takes a parameter or a list of parameters. In regular mode, it stores the parameters in a list and returns a question mark. In preview mode, it returns the parameters. Note: preview mode is used for previewing the rendered query and for debugging.
"SELECT * FROM table1 WHERE id = {{param parameter1}};"
{ parameter1: 1234 } renders to
"SELECT * FROM table1 WHERE id = ?;"
[1234]"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"
{ parameter1: ["some", "text"] } renders to
"SELECT * FROM table1 WHERE text IN (?, ?);"
["some", "text"]"SELECT * FROM table1 WHERE text = {{param (toString parameter1)}};"
{ parameter1: 1234 } renders to
"SELECT * FROM table1 WHERE text = ?;"
["1234"]"SELECT * FROM table1 WHERE text = {{param (toNumber parameter1)}};"
{ parameter1: "1234" } renders to
"SELECT * FROM table1 WHERE text = ?;"
[1234]"SELECT * FROM table1 WHERE text LIKE {{param (concat '%' parameter1 '%')}};"
{ parameter1: "some text" } renders to
"SELECT * FROM table1 WHERE text = ?;" with the list of parameters `["%some text%"]`
"SELECT * FROM table1 WHERE id = {{param parameter1}};"
{ parameter1: 1234 } renders to
"SELECT * FROM table1 WHERE id = 1234;"
"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"
{ parameter1: ["some", "text"] } renders to
"SELECT * FROM table1 WHERE text IN ('some', 'text');"
"SELECT * FROM table1 WHERE id = {{param parameter1}};"
{ } throws an error saying "Error: parameter value cannot be null in param helper""SELECT * FROM table1 WHERE text IN ({{param parameter1}});"
{ parameter: ["some", null] } throws an error saying "Error: parameter array cannot have null value in param helper".