Handlebar helpers（Handlebars 辅助函数(Helper)）¶

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:

Built-in helpers - from the Handlebars library
Core helpers - available within queries and widgets
Widget helpers - accessible only in widgets
Foundry helpers - accessible only in Foundry queries
SQL helpers - accessible only in SQL queries

:::callout{theme="neutral"} Helpers cannot be used in the Functions editor. :::

Built-in helpers¶

The following helpers from the Handlebars library are available. See the Handlebars documentation ↗ to learn about each helper:

Core helpers¶

The following core helpers are available within queries and widgets:

toString
toNumber
concat
substring
contains
jsonParse
jsonStringify
add
subtract
multiply
divide
max
min
eq
ne
lt
le
gt
ge
encodeURI
encodeURIComponent
getSelectedDisplayValue
getSelectedDisplayValues
lookup
and
or
not

toString¶

The toString helper converts any given value to a string using the JavaScript String() ↗function.

Examples¶

Using toString on a String
{{toString 'hello'}} renders to "hello"
Using toString on a Number
{{toString 1}} renders to "1"
Using toString on a String Array
{{toString variable}} where context is { variable: ["hello", "world"] } renders to "hello,world"
Using toString on a Number Array
{{toString variable}} where context is { variable: [1, 2, 3] } renders to "1,2,3"
Using toString on an Object
{{toString variable}} where context is { variable: {"hello": "world"} } renders to "[Object Object]"

toNumber¶

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.

Examples¶

Using toNumber on a Number
{{toNumber 1}} renders to 1
Using toNumber on a String that represents a Number
{{toNumber '2'}} renders to 2
Using toNumber on a String that does not represent a Number
{{toNumber 'hello'}} renders to NaN
Using toNumber on an Array
{{toNumber variable}} where context is { variable: [1, 2, 3] } renders to NaN
Using toNumber on an Object
{{toNumber variable}} where context is { variable: {"hello": "world"} } renders to NaN

concat¶

The 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.

Examples¶

Using concat on two numbers
{{concat 1 2}} renders to "12"
Using concat on two strings and a number
{{concat 'hello' 'world' 2}} renders to "helloworld2"
Using concat on two string arrays
{{concat array1 array2}} where context is { array1: ["hello", "world"], array2: ["again", "and again"] } renders to "helloworldagainand again"
Using concat on three numbers and an object
{{concat 1 2 3 variable}} where context is { variable: {"hello": "world"} } renders to "123[Object Object]"

substring¶

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.

Examples¶

Using substring on a string
{{substring 'foo' 0 1}} renders to "f"
If you use an input string that is shorter than the end, it will return the input string
{{substring 'foo' 0 6}} renders to "foo"
If you do not provide an end index
{{substring 'foo' 1}} renders to "oo"

contains¶

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.

Examples¶

Using contains on an array
{{contains variable 3}} where context is { variable: [1, 2, 3] } renders to true
Using contains on a string
{{contains variable "hello"}} where context is { variable: "hello world" } renders to true

jsonParse¶

The jsonParse helper takes a JSON string as input, and parses it using JavaScript’s JSON.parse ↗ function.

Examples¶

Using jsonParse on a JSON stringified string
{{jsonParse '\"foo\"'}} renders to "foo"
Using jsonParse on a JSON stringified array
{{jsonParse varA}} where context is "[\"hello\",\"world\"]" renders to ["hello", "world"]
Using jsonParse on a JSON stringified object
{{jsonParse varA}} where context is "{\"varA\":{\"hello\":\"world\",\"foo\":[\"bar\",\"baz\"]}}" renders to { varA: {"hello": "world", "foo": ["bar", "baz"]} }
Using jsonParse on a number
{{jsonParse 123}} throws an error in the console saying "jsonParse: Error: value must be a string"
Using jsonParse on an invalid JSON string
{{jsonParse varA}} where context is "[\"hello\"," throws an error in the console saying "jsonParse: SyntaxError: Unable to parse JSON string"

jsonStringify¶

The jsonStringify helper takes any object as input, and returns that object converted to JSON (as passed to JavaScript’s JSON.stringify ↗ function).

Examples¶

Using jsonStringify on a string
{{jsonStringify 'foo'}} renders to "foo" (the double-quotes are included in the rendered text)
Using jsonStringify on an object {{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)

add¶

The add helper adds two numbers.

Examples¶

Using add with two numbers
{{add 20 5}} renders to 25
Using add on a value that is not a number
{{add 10 'abc'}} throws an error in the console saying "value must be a number"

subtract¶

The subtract helper subtracts the second number from the first number.

Examples¶

Using subtract with two numbers
{{subtract 20 5}} renders to 15
Using subtract on a value that is not a number
{{subtract 10 'abc'}} throws an error in the console saying "value must be a number"

multiply¶

The multiply helper multiplies two numbers.

Examples¶

Using multiply with two numbers
{{multiply 20 5}} renders to 100
Using multiply on a value that is not a number
{{multiply 10 'abc'}} throws an error in the console saying "value must be a number"

divide¶

The divide helper divides the first number by the second number.

Examples¶

Using divide with two numbers
{{divide 20 5}} renders to 4
Using divide on a value that is not a number
{{divide 10 'abc'}} throws an error in the console saying "value must be a number"

max¶

The max helper finds the maximum from any given numbers or array of numbers.

Examples¶

Using max with an array of numbers
{{max variable}} where context is { variable: [1, 2, 3] } renders to 3
Using max with an array of numbers and two numbers
{{max variable 12 15}} where context is { variable: [1, 2, 3] } renders to 15
Using max with a string
{{max 'hello' 123}} throws an error in the console saying "value must be a number or a number array"
Using max with an invalid 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"

min¶

The min helper finds the minimum from any given numbers or an array of numbers.

Examples¶

Using min with an array of numbers
{{min variable}} where context is { variable: [1, 2, 3] } renders to 1
Using min with an array of numbers and two numbers
{{min variable 6 10}} where context is { variable: [1, 2, 3] } renders to 1
Using min with a string
{{min 'hello' 123}} throws an error in the console saying "value must be a number or a number array"
Using min with an invalid 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"

eq¶

The eq helper compares two numbers or strings and checks to see if they are equal

Examples¶

Using eq with two numbers
{{eq 1 1}} renders to true
Using 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."

ne¶

The ne helper compares two numbers or strings and checks to see if they are different

Examples¶

Using ne with two numbers
{{ne 1 1}} renders to false
Using ne on values that are not numbers or strings, or are different types
{{ne [1, 2] 5}} throws an error in the console saying "type mismatch"

lt¶

The lt helper compares two numbers or strings and checks if the first one is less than the second one.

Examples¶

Using lt with two numbers
{{lt 1 2}} renders to true
Using lt on values that are not numbers or strings, or are different types
{{lt [1, 2] 5}} throws an error in the console saying "type mismatch"

le¶

The le helper compares two numbers or strings and checks if the first one is less than or equal to the second one.

Examples¶

Using le with two numbers
{{le 1 1}} renders to true
Using le on values that are not numbers or strings, or are different types
{{le [1, 2] 5}} throws an error in the console saying "type mismatch"

gt¶

The gt helper compares two numbers or strings and checks if the first one is greater than the second one.

Examples¶

Using gt with two numbers
{{gt 2 1}} renders to true
Using gt on values that are not numbers or strings, or are different types
{{gt [1, 2] 5}} throws an error in the console saying "type mismatch"

ge¶

The ge helper compares two numbers or strings and checks if first one is greater than or equal to the second one.

Examples¶

Using ge with two numbers
{{ge 1 1}} renders to true
Using ge on values that are not numbers or strings, or are different types
{{ge [1, 2] 5}} throws an error in the console saying "type mismatch"

encodeURI¶

The encodeURI helper encodes any given string with the JavaScript encodeURI() ↗ function.

Examples¶

Using encodeURI on a string
{{encodeURI 'hello world?'}} renders to "hello%20world?"
Using encodeURI on a value that is not a string
{{encodeURI variable}} where context is { variable: [1, 2, 3] } throws an error in the console saying "value must be a string"

encodeURIComponent¶

The encodeURIComponent helper encodes any given string with the JavaScript encodeURIComponent() ↗ function.

Examples¶

Using encodeURIComponent on a string
{{encodeURIComponent 'hello world?'}} renders to "hello%20world%3F"
Using encodeURI on a value that is not a string
{{encodeURIComponent variable}} where context is { variable: [1, 2, 3] } throws an error in the console saying "value must be a string"

getSelectedDisplayValue¶

The getSelectedDisplayValue helper gets the selectedDisplayValue from displayValues given values and selectedValue.

Examples¶

Using getSelectedDisplayValue with values, displayValues and selectedValue
{{getSelectedDisplayValue values displayValues selectedValue}} where context is { values: [1, 2, 3], displayValues: ["a", "b", "c"], selectedValue: 2 } returns ["b"]
Using getSelectedDisplayValue when values or displayValues is not an array
{{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"
Using getSelectedDisplayValue when selectedValue is not in values
{{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"

getSelectedDisplayValues¶

The getSelectedDisplayValues helper gets the selectedDisplayValues from displayValues given values and selectedValues.

Examples¶

Using getSelectedDisplayValues with values, displayValues and selectedValues
{{getSelectedDisplayValues values displayValues selectedValues}} where context is { values: [1, 2, 3], displayValues: ["a", "b", "c"], selectedValues: [2, 3] } returns ["b", "c"]
Using getSelectedDisplayValues when values, displayValues or selectedValues is not an array
{{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"
Using getSelectedDisplayValues when some selectedValue is not in values
{{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"

lookup¶

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.

Example¶

{{lookup a "b" "c"}} where the context is { a: { b: { c: "test" } } } will return "test"

and¶

The and helper performs an AND (&&) logical comparison on the supplied Boolean arguments. It requires at least two arguments.

Example¶

{{and var1 var2}} where context is { var1: "true", var2: "false" } renders to "false"

or¶

The or helper performs an OR (||) logical comparison on the supplied Boolean arguments. It requires at least two arguments.

Example¶

{{or var1 var2}} where context is { var1: "true", var2: "false" } renders to "true"

not¶

The not helper performs a NOT (!) logical comparison on the supplied Boolean argument. It can only be applied to one single argument.

Example¶

{{not var}} where context is `{ var : "true" } renders to "false"

The following widget helpers are available within widgets:

formatNumber
formatDate

formatNumber¶

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.

Examples¶

Using formatNumber on a number
{{formatNumber 1400 '0,0'}} renders to "1,400"
- For more examples of formatting a number, check the Numeral.js library.
Using formatNumber on a value that is not a number
{{formatNumber 'abc' '0,0'}} throws an error in the console saying "value must be a number"
Using formatNumber with an invalid format (format that is not a string)
{{formatNumber 1400 variable}} where context is { variable: ["hello": "world"] } throws an error in the console saying "format must be a string"

formatDate¶

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.

Examples¶

Using formatDate on a string
{{formatDate '2014-1-2' 'MM/DD/YYYY'}} renders to "01/02/2014"
- For more examples of formatting a date, see check the Moment.js library.
Using formatDate on a number
{{formatDate 1237705200000 'YYYY-MM-DD'}} renders "2009-03-22"
- For more examples of formatting a date, see the Moment.js library.
Using formatDate on a value that is an invalid date string
{{formatDate 'some string' 'YYYY-MM-DD'}} throws an error in the console saying "value must be a valid date"
Using formatDate with an invalid format (format that is not a string)
{{formatDate '2014-1-2' variable}} where context is { variable: ["hello": "world"] } throws an error in the console saying "format must be a string"

Foundry helpers¶

The following helper is available within HttpJson Foundry queries.

joinParams

joinParams¶

The joinParams helper takes an array of parameters and joins single quoted parameters with ,.

Examples¶

Using joinParams with an array of strings

"SELECT * FROM `table1` WHERE name IN ({{joinParams names}})"

where context is { names: ["Bill", "John J.", "Sam's", "Jay"] } renders to

"SELECT * FROM `table1` WHERE name IN ('Bill', 'John J.', 'Sam\'s', 'Jay')"

Using joinParams with a string
```
"SELECT * FROM table1 WHERE name IN ({{joinParams name}});"
```
where context is { name: "Bill" } throws an error saying "parameters must be an array in joinParams helper"

SQL helpers¶

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.

alias
schema
table
column
param

alias¶

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.

Examples¶

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..."

schema¶

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.

Examples¶

Using schema with a valid schema name

"SELECT * FROM {{schema schemaName 'schema1' 'schema2'}}.table1;"

where context is { schemaName: "schema1" } renders to

"SELECT * FROM schema1.table1;"

Using schema with a schema name that’s not in the list of whitelist names
```
"SELECT * FROM {{schema schemaName 'schema1' 'schema2'}}.table1;"
```
where context is { schemaName: "schemaNameNotInList" } renders to
```
"SELECT FROM schemaNameNotInList.table1"
```
and an error will be thrown on execute saying "schema name must be in the list of the whitelist names."
Using schema with a schema name with a reference in the list of whitelist names
```
"SELECT * FROM {{schema schemaName 'schema1' 'schema2' templatizedName}}.table1;"
```
where context is { schemaName: "schema1", templatizedName: "anotherSchemaName" } renders to
```
"SELECT * FROM schema1.table1;"
```
and an error will be thrown on execute saying "References ['templatizedName'] cannot be dynamic for security reasons."
Using schema with an invalid schema name
```
"SELECT * FROM {{schema schemaName 'invalidSchema1'}}.table1;" 
```
where context is { schemaName: "invalidSchema1" } renders to
```
"SELECT * FROM invalidSchema1.table1;"
```
and an error will be thrown on execute saying "Invalid schema name 'invalidSchema1.'"

table¶

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.

Examples¶

Using table with a valid table name
```
"SELECT * FROM {{table tableName 'table1' 'table2'}};"
```
where context is { tableName: "table1" } renders to
```
"SELECT * FROM table1;"
```
Using table with a table name that’s not in the list of whitelist names
```
"SELECT * FROM {{table tableName 'table1' 'table2'}};"
```
where context is { tableName: "tableNameNotInList" } renders to
```
"SELECT * FROM tableNameNotInList;"
```
and an error will be thrown on execute saying "table name must be in the list of the whitelist names."
Using table with a table name with a reference in the list of whitelist names
```
"SELECT * FROM {{table tableName 'table1' 'table2' templatizedName}};"
```
where context is { tableName: "table1", templatizedName: "anotherTableName" } renders to
```
"SELECT * FROM table1;"
```
and an error will be thrown on execute saying "References ['templatizedName'] cannot be dynamic for security reasons."
Using table with an invalid table name
```
"SELECT * FROM {{table tableName 'invalidTable1'}};"
```
where context is { tableName: "invalidTable1" } renders to
```
"SELECT * FROM invalidTable1;"
```
and an error will be thrown on execute saying "Invalid table name 'invalidTable1'."

column¶

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.

Examples¶

Using column with a valid column name
```
"SELECT {{column columnName}} FROM table1;"
```
where context is { columnName: "column1" } renders to
```
"SELECT column1 FROM table1;"
```
Using column with a valid case sensitive column name
```
"SELECT "{{column columnName}}" FROM table1;"
```
where context is { columnName: "Column 1" } renders to "SELECT "Column 1" FROM table1;"
Using column with a list of valid column names
```
"SELECT {{column columnNames}} FROM table1;"
```
where context is { columnNames: ["column1", "column2"] } renders to
```
"SELECT column1, column2 FROM table1;"
```
Using column with an invalid column name
```
"SELECT {{column columnName}} FROM table1;"
```
where context is { columnName: "invalidColumn1" } renders to
```
"SELECT invalidColumn1 FROM table1;"
```
and an error will be thrown saying "Invalid column name 'invalidColumn1'."

param¶

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.

Examples¶

Using param with a number in regular mode
```
"SELECT * FROM table1 WHERE id = {{param parameter1}};"
```
where context is { parameter1: 1234 } renders to
```
"SELECT * FROM table1 WHERE id = ?;"
```
with the list of parameters [1234]
Using param with a list of strings in regular mode
```
"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"
```
where context is { parameter1: ["some", "text"] } renders to
```
"SELECT * FROM table1 WHERE text IN (?, ?);"
```
with the list of parameters ["some", "text"]
Using param with a number using toString helper in regular mode
```
"SELECT * FROM table1 WHERE text = {{param (toString parameter1)}};"
```
where context is { parameter1: 1234 } renders to
```
"SELECT * FROM table1 WHERE text = ?;"
```
with the list of parameters ["1234"]
Using param with a string using toNumber helper in regular mode
```
"SELECT * FROM table1 WHERE text = {{param (toNumber parameter1)}};"
```
where context is { parameter1: "1234" } renders to
```
"SELECT * FROM table1 WHERE text = ?;"
```
with the list of parameters [1234]

Using param with LIKE operation using concat helper in regular mode

"SELECT * FROM table1 WHERE text LIKE {{param (concat '%' parameter1 '%')}};"

where context is { parameter1: "some text" } renders to

"SELECT * FROM table1 WHERE text = ?;" with the list of parameters `["%some text%"]`

Using param with a number in preview mode

"SELECT * FROM table1 WHERE id = {{param parameter1}};"

where context is { parameter1: 1234 } renders to

"SELECT * FROM table1 WHERE id = 1234;"

Using param with a list of strings in preview mode

"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"

where context is { parameter1: ["some", "text"] } renders to

"SELECT * FROM table1 WHERE text IN ('some', 'text');"

Using param with an undefined parameter
```
"SELECT * FROM table1 WHERE id = {{param parameter1}};"
```
where context is { } throws an error saying "Error: parameter value cannot be null in param helper"
Using param with an array containing null
```
"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"
```
where context is { parameter: ["some", null] } throws an error saying "Error: parameter array cannot have null value in param helper".

中文翻译¶

Handlebars 辅助函数(Helper)¶

辅助函数(Helper)是预定义的函数，可以从 Handlebars 模板内部调用。辅助函数具有名称、参数和返回值。例如，模板 {{add 5 var1}} 对整数(5)和一个名为 var1 的变量调用 add 辅助函数。如果 var1 设置为 7，则模板计算结果为 12。

辅助函数分为以下几类：

内置辅助函数(Built-in helpers) - 来自 Handlebars 库
核心辅助函数(Core helpers) - 可在查询(Query)和小部件(Widget)中使用
小部件辅助函数(Widget helpers) - 仅在小部件中可访问
Foundry 辅助函数(Foundry helpers) - 仅在 Foundry 查询中可访问
SQL 辅助函数(SQL helpers) - 仅在 SQL 查询中可访问

:::callout{theme="neutral"} 辅助函数不能在函数(Functions) 编辑器中使用。 :::

内置辅助函数(Built-in helpers)¶

以下来自 Handlebars 库的辅助函数可用。请参阅 Handlebars 文档 ↗ 了解每个辅助函数的详细信息：

核心辅助函数(Core helpers)¶

以下核心辅助函数可在查询(Query)和小部件(Widget)中使用：

toString
toNumber
concat
substring
contains
jsonParse
jsonStringify
add
subtract
multiply
divide
max
min
eq
ne
lt
le
gt
ge
encodeURI
encodeURIComponent
getSelectedDisplayValue
getSelectedDisplayValues
lookup
and
or
not

toString¶

toString 辅助函数使用 JavaScript String() ↗ 函数将任何给定值转换为字符串。

示例¶

对字符串使用 toString
{{toString 'hello'}} 渲染为 "hello"
对数字使用 toString
{{toString 1}} 渲染为 "1"
对字符串数组使用 toString
{{toString variable}} 其中上下文为 { variable: ["hello", "world"] } 渲染为 "hello,world"
对数字数组使用 toString
{{toString variable}} 其中上下文为 { variable: [1, 2, 3] } 渲染为 "1,2,3"
对对象使用 toString
{{toString variable}} 其中上下文为 { variable: {"hello": "world"} } 渲染为 "[Object Object]"

toNumber¶

toNumber 辅助函数使用 JavaScript Number() ↗ 函数将任何给定值转换为数字。如果该值无法转换为数字，则返回 NaN。

示例¶

对数字使用 toNumber
{{toNumber 1}} 渲染为 1
对表示数字的字符串使用 toNumber
{{toNumber '2'}} 渲染为 2
对不表示数字的字符串使用 toNumber
{{toNumber 'hello'}} 渲染为 NaN
对数组使用 toNumber
{{toNumber variable}} 其中上下文为 { variable: [1, 2, 3] } 渲染为 NaN
对对象使用 toNumber
{{toNumber variable}} 其中上下文为 { variable: {"hello": "world"} } 渲染为 NaN

concat¶

concat 辅助函数接受任意数量的参数，首先使用 JavaScript String() 函数将每个参数转换为字符串，然后将它们连接在一起。

示例¶

对两个数字使用 concat
{{concat 1 2}} 渲染为 "12"
对两个字符串和一个数字使用 concat
{{concat 'hello' 'world' 2}} 渲染为 "helloworld2"
对两个字符串数组使用 concat
{{concat array1 array2}} 其中上下文为 { array1: ["hello", "world"], array2: ["again", "and again"] } 渲染为 "helloworldagainand again"
对三个数字和一个对象使用 concat
{{concat 1 2 3 variable}} 其中上下文为 { variable: {"hello": "world"} } 渲染为 "123[Object Object]"

substring¶

substring 辅助函数接受一个输入字符串(value)以及起始和结束位置(可选)，然后将其传递给 JavaScript substring() 函数。这使您可以获取输入字符串的子字符串。

示例¶

对字符串使用 substring
{{substring 'foo' 0 1}} 渲染为 "f"
如果输入字符串短于结束位置，则返回输入字符串
{{substring 'foo' 0 6}} 渲染为 "foo"
如果不提供结束索引
{{substring 'foo' 1}} 渲染为 "oo"

contains¶

contains 辅助函数接受一个数组或字符串(value)和一个要搜索的值(searchValue)，如果该值在数组中则返回 true，否则返回 false。它通过调用 value.indexOf(searchvalue) !== -1 来实现。

示例¶

对数组使用 contains
{{contains variable 3}} 其中上下文为 { variable: [1, 2, 3] } 渲染为 true
对字符串使用 contains
{{contains variable "hello"}} 其中上下文为 { variable: "hello world" } 渲染为 true

jsonParse¶

jsonParse 辅助函数接受一个 JSON 字符串作为输入，并使用 JavaScript 的 JSON.parse ↗ 函数进行解析。

示例¶

对 JSON 字符串化的字符串使用 jsonParse
{{jsonParse '\"foo\"'}} 渲染为 "foo"
对 JSON 字符串化的数组使用 jsonParse
{{jsonParse varA}} 其中上下文为 "[\"hello\",\"world\"]" 渲染为 ["hello", "world"]
对 JSON 字符串化的对象使用 jsonParse
{{jsonParse varA}} 其中上下文为 "{\"varA\":{\"hello\":\"world\",\"foo\":[\"bar\",\"baz\"]}}" 渲染为 { varA: {"hello": "world", "foo": ["bar", "baz"]} }
对数字使用 jsonParse
{{jsonParse 123}} 在控制台中抛出错误 "jsonParse: Error: value must be a string"
对无效的 JSON 字符串使用 jsonParse
{{jsonParse varA}} 其中上下文为 "[\"hello\"," 在控制台中抛出错误 "jsonParse: SyntaxError: Unable to parse JSON string"

jsonStringify¶

jsonStringify 辅助函数接受任何对象作为输入，并返回该对象转换为 JSON 的结果(传递给 JavaScript 的 JSON.stringify ↗ 函数)。

示例¶

对字符串使用 jsonStringify
{{jsonStringify 'foo'}} 渲染为 "foo" (双引号包含在渲染文本中)
对对象使用 jsonStringify {{jsonStringify varA}} 其中上下文为 { varA: {"hello": "world", "foo": ["bar", "baz"]} } 渲染为 {"hello":"world","foo":["bar","baz"]} (同样，双引号包含在渲染文本中)

add¶

add 辅助函数将两个数字相加。

示例¶

对两个数字使用 add
{{add 20 5}} 渲染为 25
对非数字值使用 add
{{add 10 'abc'}} 在控制台中抛出错误 "value must be a number"

subtract¶

subtract 辅助函数从第一个数字中减去第二个数字。

示例¶

对两个数字使用 subtract
{{subtract 20 5}} 渲染为 15
对非数字值使用 subtract
{{subtract 10 'abc'}} 在控制台中抛出错误 "value must be a number"

multiply¶

multiply 辅助函数将两个数字相乘。

示例¶

对两个数字使用 multiply
{{multiply 20 5}} 渲染为 100
对非数字值使用 multiply
{{multiply 10 'abc'}} 在控制台中抛出错误 "value must be a number"

divide¶

divide 辅助函数将第一个数字除以第二个数字。

示例¶

对两个数字使用 divide
{{divide 20 5}} 渲染为 4
对非数字值使用 divide
{{divide 10 'abc'}} 在控制台中抛出错误 "value must be a number"

max¶

max 辅助函数从任意给定的数字或数字数组中找出最大值。

示例¶

对数字数组使用 max
{{max variable}} 其中上下文为 { variable: [1, 2, 3] } 渲染为 3
对数字数组和两个数字使用 max
{{max variable 12 15}} 其中上下文为 { variable: [1, 2, 3] } 渲染为 15
对字符串使用 max
{{max 'hello' 123}} 在控制台中抛出错误 "value must be a number or a number array"
对无效数组使用 max
{{max variable}} 其中上下文为 { variable: ["hello", "world"] } 在控制台中抛出错误 "value must be a number or a number array"

min¶

min 辅助函数从任意给定的数字或数字数组中找出最小值。

示例¶

对数字数组使用 min
{{min variable}} 其中上下文为 { variable: [1, 2, 3] } 渲染为 1
对数字数组和两个数字使用 min
{{min variable 6 10}} 其中上下文为 { variable: [1, 2, 3] } 渲染为 1
对字符串使用 min
{{min 'hello' 123}} 在控制台中抛出错误 "value must be a number or a number array"
对无效数组使用 min
{{min variable }} 其中上下文为 { variable: ["hello", "world"] } 在控制台中抛出错误 "value must be a number or a number array"

eq¶

eq 辅助函数比较两个数字或字符串，检查它们是否相等。

示例¶

对两个数字使用 eq
{{eq 1 1}} 渲染为 true
对非数字或字符串的值，或不同类型的值使用 eq
{{eq [1, 2] 5}} 在控制台中抛出错误 "type mismatch"
在 if 块内使用 eq

{{#if (eq name 'Steven')}}
  Your name is Steven.
{{else}}
  Your name is not Steven.
{{/if}}

其中上下文为 { name: "Steven" } 渲染为 "Your name is Steven."

ne¶

ne 辅助函数比较两个数字或字符串，检查它们是否不同。

示例¶

对两个数字使用 ne
{{ne 1 1}} 渲染为 false
对非数字或字符串的值，或不同类型的值使用 ne
{{ne [1, 2] 5}} 在控制台中抛出错误 "type mismatch"

lt¶

lt 辅助函数比较两个数字或字符串，检查第一个是否小于第二个。

示例¶

对两个数字使用 lt
{{lt 1 2}} 渲染为 true
对非数字或字符串的值，或不同类型的值使用 lt
{{lt [1, 2] 5}} 在控制台中抛出错误 "type mismatch"

le¶

le 辅助函数比较两个数字或字符串，检查第一个是否小于或等于第二个。

示例¶

对两个数字使用 le
{{le 1 1}} 渲染为 true
对非数字或字符串的值，或不同类型的值使用 le
{{le [1, 2] 5}} 在控制台中抛出错误 "type mismatch"

gt¶

gt 辅助函数比较两个数字或字符串，检查第一个是否大于第二个。

示例¶

对两个数字使用 gt
{{gt 2 1}} 渲染为 true
对非数字或字符串的值，或不同类型的值使用 gt
{{gt [1, 2] 5}} 在控制台中抛出错误 "type mismatch"

ge¶

ge 辅助函数比较两个数字或字符串，检查第一个是否大于或等于第二个。

示例¶

对两个数字使用 ge
{{ge 1 1}} 渲染为 true
对非数字或字符串的值，或不同类型的值使用 ge
{{ge [1, 2] 5}} 在控制台中抛出错误 "type mismatch"

encodeURI¶

encodeURI 辅助函数使用 JavaScript encodeURI() ↗ 函数对任何给定字符串进行编码。

示例¶

对字符串使用 encodeURI
{{encodeURI 'hello world?'}} 渲染为 "hello%20world?"
对非字符串值使用 encodeURI
{{encodeURI variable}} 其中上下文为 { variable: [1, 2, 3] } 在控制台中抛出错误 "value must be a string"

encodeURIComponent¶

encodeURIComponent 辅助函数使用 JavaScript encodeURIComponent() ↗ 函数对任何给定字符串进行编码。

示例¶

对字符串使用 encodeURIComponent
{{encodeURIComponent 'hello world?'}} 渲染为 "hello%20world%3F"
对非字符串值使用 encodeURI
{{encodeURIComponent variable}} 其中上下文为 { variable: [1, 2, 3] } 在控制台中抛出错误 "value must be a string"

getSelectedDisplayValue¶

getSelectedDisplayValue 辅助函数根据给定的 values 和 selectedValue 从 displayValues 中获取 selectedDisplayValue。

示例¶

使用 values、displayValues 和 selectedValue 使用 getSelectedDisplayValue
{{getSelectedDisplayValue values displayValues selectedValue}} 其中上下文为 { values: [1, 2, 3], displayValues: ["a", "b", "c"], selectedValue: 2 } 返回 ["b"]
当 values 或 displayValues 不是数组时使用 getSelectedDisplayValue
{{getSelectedDisplayValue values displayValues selectedValue}} 其中上下文为 { values: "hello", displayValues: ["a", "b", "c"], selectedValue: 2 } 在控制台中抛出错误 "values must be an array"
当 selectedValue 不在 values 中时使用 getSelectedDisplayValue
{{getSelectedDisplayValue values displayValues selectedValue}} 其中上下文为 { values: [1,2,3], displayValues: ["a", "b", "c"], selectedValue: 4 } 在控制台中抛出错误 "selectedValue '4' is not in values"

getSelectedDisplayValues¶

getSelectedDisplayValues 辅助函数根据给定的 values 和 selectedValues 从 displayValues 中获取 selectedDisplayValues。

示例¶

使用 values、displayValues 和 selectedValues 使用 getSelectedDisplayValues
{{getSelectedDisplayValues values displayValues selectedValues}} 其中上下文为 { values: [1, 2, 3], displayValues: ["a", "b", "c"], selectedValues: [2, 3] } 返回 ["b", "c"]
当 values、displayValues 或 selectedValues 不是数组时使用 getSelectedDisplayValues
{{getSelectedDisplayValues values displayValues selectedValues}} 其中上下文为 { values: "hello", displayValues: ["a", "b", "c"], selectedValues: 2 } 在控制台中抛出错误 "values must be an array"
当某些 selectedValue 不在 values 中时使用 getSelectedDisplayValues
{{getSelectedDisplayValues values displayValues selectedValues}} 其中上下文为 { values: [1,2,3], displayValues: ["a", "b", "c"], selectedValues: [4] } 在控制台中抛出错误 "selectedValue '4' is not in values"

lookup¶

lookup 辅助函数使用内置 Handlebars lookup ↗ 的变体，可以按照 Handlebars 文档中的描述使用。此外，Slate 的 lookup 变体可以描述长属性链，如下例所示。

示例¶

{{lookup a "b" "c"}} 其中上下文为 { a: { b: { c: "test" } } } 将返回 "test"

and¶

and 辅助函数对提供的布尔参数执行 AND (&&) 逻辑比较。它至少需要两个参数。

示例¶

{{and var1 var2}} 其中上下文为 { var1: "true", var2: "false" } 渲染为 "false"

or¶

or 辅助函数对提供的布尔参数执行 OR (||) 逻辑比较。它至少需要两个参数。

示例¶

{{or var1 var2}} 其中上下文为 { var1: "true", var2: "false" } 渲染为 "true"

not¶

not 辅助函数对提供的布尔参数执行 NOT (!) 逻辑比较。它只能应用于单个参数。

示例¶

{{not var}} 其中上下文为 { var : "true" } 渲染为 "false"

以下小部件辅助函数可在小部件(Widget)中使用：

formatNumber
formatDate

formatNumber¶

formatNumber 辅助函数使用 Numeral.js ↗ 库将任何给定数字格式化为字符串。请注意，值必须是数字，格式必须是字符串。

示例¶

对数字使用 formatNumber
{{formatNumber 1400 '0,0'}} 渲染为 "1,400"
- 有关格式化数字的更多示例，请查看 Numeral.js 库。
对非数字值使用 formatNumber
{{formatNumber 'abc' '0,0'}} 在控制台中抛出错误 "value must be a number"
使用无效格式(非字符串格式)使用 formatNumber
{{formatNumber 1400 variable}} 其中上下文为 { variable: ["hello": "world"] } 在控制台中抛出错误 "format must be a string"

formatDate¶

formatDate 辅助函数使用 Moment.js ↗ 库将任何给定日期格式化为字符串。请注意，值必须是日期，格式必须是字符串。

示例¶

对字符串使用 formatDate
{{formatDate '2014-1-2' 'MM/DD/YYYY'}} 渲染为 "01/02/2014"
- 有关格式化日期的更多示例，请查看 Moment.js 库。
对数字使用 formatDate
{{formatDate 1237705200000 'YYYY-MM-DD'}} 渲染为 "2009-03-22"
- 有关格式化日期的更多示例，请查看 Moment.js 库。
对无效日期字符串值使用 formatDate
{{formatDate 'some string' 'YYYY-MM-DD'}} 在控制台中抛出错误 "value must be a valid date"
使用无效格式(非字符串格式)使用 formatDate
{{formatDate '2014-1-2' variable}} 其中上下文为 { variable: ["hello": "world"] } 在控制台中抛出错误 "format must be a string"

Foundry 辅助函数(Foundry helpers)¶

以下辅助函数可在 HttpJson Foundry 查询中使用。

joinParams

joinParams¶

joinParams 辅助函数接受一个参数数组，并使用 , 连接单引号参数。

示例¶

使用字符串数组使用 joinParams

"SELECT * FROM `table1` WHERE name IN ({{joinParams names}})"

其中上下文为 { names: ["Bill", "John J.", "Sam's", "Jay"] } 渲染为

"SELECT * FROM `table1` WHERE name IN ('Bill', 'John J.', 'Sam\'s', 'Jay')"

使用字符串使用 joinParams
```
"SELECT * FROM table1 WHERE name IN ({{joinParams name}});"
```
其中上下文为 { name: "Bill" } 抛出错误 "parameters must be an array in joinParams helper"

SQL 辅助函数(SQL helpers)¶

以下 SQL 辅助函数可在 SQL 查询中使用。请注意，虽然 HttpJson Foundry 查询使用 Spark SQL 语法，但这些辅助函数不应在这些查询中使用。

alias
schema
table
column
param

alias¶

alias 辅助函数接受一个别名列或表名。column 和 table 辅助函数会对照信息模式(information schema)检查值。但是，临时列名或表名不在模式中。alias 辅助函数为用户提供了一种注册临时列名或表名的方法。当名称不是常量值时，它会抛出错误。

示例¶

使用 alias 注册别名列名

"SELECT id as {{alias 'alias_column_name'}} FROM table1 ORDER BY {{column aliasColumnName}};"

其中上下文为 { aliasColumnName: "alias_column_name" } 渲染为

"SELECT id as alias_column_name FROM table1 ORDER BY alias_column_name;"

使用 alias 注册别名区分大小写的列名

"SELECT id as "{{alias 'Alias Column Name'}}" FROM table1 ORDER BY "{{column aliasColumnName}}";"

其中上下文为 { aliasColumnName: "Alias Column Name" } 渲染为

"SELECT id as "Alias Column Name" FROM table1 ORDER BY "Alias Column Name";"

使用 alias 注册别名表名

"SELECT id as "{{alias 'Alias Column Name'}}" FROM table1 ORDER BY "{{column aliasColumnName}}";"

其中上下文为 { aliasColumnName: "Alias Column Name" } 渲染为

"SELECT id as "Alias Column Name" FROM table1 ORDER BY "Alias Column Name";"

使用非常量值使用 alias：
```
"SELECT id as {{alias aliasColumnName}} FROM table1 ORDER BY {{table aliasColumnName}};"
```
其中上下文为 { aliasColumnName: "alias_column_name" } 抛出错误 "Only constant parameters are not allowed..."

schema¶

schema 辅助函数接受一个模式名称(schema name)和一个白名单名称列表。它检查模式名称是否在白名单名称列表中，并对照数据源的信息表检查模式名称。当模式名称不存在于白名单名称列表或信息表中时，它会抛出错误。

示例¶

使用有效的模式名称使用 schema

"SELECT * FROM {{schema schemaName 'schema1' 'schema2'}}.table1;"

其中上下文为 { schemaName: "schema1" } 渲染为

"SELECT * FROM schema1.table1;"

使用不在白名单名称列表中的模式名称使用 schema
```
"SELECT * FROM {{schema schemaName 'schema1' 'schema2'}}.table1;"
```
其中上下文为 { schemaName: "schemaNameNotInList" } 渲染为
```
"SELECT FROM schemaNameNotInList.table1"
```
并在执行时抛出错误 "schema name must be in the list of the whitelist names."
使用在白名单名称列表中有引用的模式名称使用 schema
```
"SELECT * FROM {{schema schemaName 'schema1' 'schema2' templatizedName}}.table1;"
```
其中上下文为 { schemaName: "schema1", templatizedName: "anotherSchemaName" } 渲染为
```
"SELECT * FROM schema1.table1;"
```
并在执行时抛出错误 "References ['templatizedName'] cannot be dynamic for security reasons."
使用无效的模式名称使用 schema
```
"SELECT * FROM {{schema schemaName 'invalidSchema1'}}.table1;" 
```
其中上下文为 { schemaName: "invalidSchema1" } 渲染为
```
"SELECT * FROM invalidSchema1.table1;"
```
并在执行时抛出错误 "Invalid schema name 'invalidSchema1.'"

table¶

table 辅助函数接受一个表名(table name)和一个白名单名称列表。它检查表名是否在白名单名称列表中，并对照数据源的信息表检查表名。当表名不存在于白名单名称列表或信息表中时，它会抛出错误。

示例¶

使用有效的表名使用 table
```
"SELECT * FROM {{table tableName 'table1' 'table2'}};"
```
其中上下文为 { tableName: "table1" } 渲染为
```
"SELECT * FROM table1;"
```
使用不在白名单名称列表中的表名使用 table
```
"SELECT * FROM {{table tableName 'table1' 'table2'}};"
```
其中上下文为 { tableName: "tableNameNotInList" } 渲染为
```
"SELECT * FROM tableNameNotInList;"
```
并在执行时抛出错误 "table name must be in the list of the whitelist names."
使用在白名单名称列表中有引用的表名使用 table
```
"SELECT * FROM {{table tableName 'table1' 'table2' templatizedName}};"
```
其中上下文为 { tableName: "table1", templatizedName: "anotherTableName" } 渲染为
```
"SELECT * FROM table1;"
```
并在执行时抛出错误 "References ['templatizedName'] cannot be dynamic for security reasons."
使用无效的表名使用 table
```
"SELECT * FROM {{table tableName 'invalidTable1'}};"
```
其中上下文为 { tableName: "invalidTable1" } 渲染为
```
"SELECT * FROM invalidTable1;"
```
并在执行时抛出错误 "Invalid table name 'invalidTable1'."

column¶

column 辅助函数接受一个列名或列名列表，并对照数据源的信息表进行检查。当列名不存在于信息表中时，它会抛出错误。

示例¶

使用有效的列名使用 column
```
"SELECT {{column columnName}} FROM table1;"
```
其中上下文为 { columnName: "column1" } 渲染为
```
"SELECT column1 FROM table1;"
```
使用有效的区分大小写的列名使用 column
```
"SELECT "{{column columnName}}" FROM table1;"
```
其中上下文为 { columnName: "Column 1" } 渲染为 "SELECT "Column 1" FROM table1;"
使用有效列名列表使用 column
```
"SELECT {{column columnNames}} FROM table1;"
```
其中上下文为 { columnNames: ["column1", "column2"] } 渲染为
```
"SELECT column1, column2 FROM table1;"
```
使用无效的列名使用 column
```
"SELECT {{column columnName}} FROM table1;"
```
其中上下文为 { columnName: "invalidColumn1" } 渲染为
```
"SELECT invalidColumn1 FROM table1;"
```
并抛出错误 "Invalid column name 'invalidColumn1'."

param¶

param 辅助函数接受一个参数或参数列表。在常规模式(regular mode)下，它将参数存储在一个列表中并返回一个问号。在预览模式(preview mode)下，它返回参数。注意：预览模式用于预览渲染后的查询和调试。

示例¶

在常规模式下对数字使用 param
```
"SELECT * FROM table1 WHERE id = {{param parameter1}};"
```
其中上下文为 { parameter1: 1234 } 渲染为
```
"SELECT * FROM table1 WHERE id = ?;"
```
参数列表为 [1234]
在常规模式下对字符串列表使用 param
```
"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"
```
其中上下文为 { parameter1: ["some", "text"] } 渲染为
```
"SELECT * FROM table1 WHERE text IN (?, ?);"
```
参数列表为 ["some", "text"]
在常规模式下使用 toString 辅助函数对数字使用 param
```
"SELECT * FROM table1 WHERE text = {{param (toString parameter1)}};"
```
其中上下文为 { parameter1: 1234 } 渲染为
```
"SELECT * FROM table1 WHERE text = ?;"
```
参数列表为 ["1234"]
在常规模式下使用 toNumber 辅助函数对字符串使用 param
```
"SELECT * FROM table1 WHERE text = {{param (toNumber parameter1)}};"
```
其中上下文为 { parameter1: "1234" } 渲染为
```
"SELECT * FROM table1 WHERE text = ?;"
```
参数列表为 [1234]

在常规模式下使用 concat 辅助函数对 LIKE 操作使用 param

"SELECT * FROM table1 WHERE text LIKE {{param (concat '%' parameter1 '%')}};"

其中上下文为 { parameter1: "some text" } 渲染为

"SELECT * FROM table1 WHERE text = ?;" 参数列表为 `["%some text%"]`

在预览模式下对数字使用 param

"SELECT * FROM table1 WHERE id = {{param parameter1}};"

其中上下文为 { parameter1: 1234 } 渲染为

"SELECT * FROM table1 WHERE id = 1234;"

在预览模式下对字符串列表使用 param

"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"

其中上下文为 { parameter1: ["some", "text"] } 渲染为

"SELECT * FROM table1 WHERE text IN ('some', 'text');"

对未定义的参数使用 param
```
"SELECT * FROM table1 WHERE id = {{param parameter1}};"
```
其中上下文为 { } 抛出错误 "Error: parameter value cannot be null in param helper"
对包含 null 的数组使用 param
```
"SELECT * FROM table1 WHERE text IN ({{param parameter1}});"
```
其中上下文为 { parameter: ["some", null] } 抛出错误 "Error: parameter array cannot have null value in param helper"

Handlebar helpers（Handlebars 辅助函数(Helper)）¶

Built-in helpers¶

Core helpers¶

toString¶

Examples¶

toNumber¶

Examples¶

concat¶

Examples¶

substring¶

Examples¶

contains¶

Examples¶

jsonParse¶

Examples¶

jsonStringify¶

Examples¶

add¶

Examples¶

subtract¶

Examples¶

multiply¶

Examples¶

divide¶

Examples¶

max¶

Examples¶

min¶

Examples¶

eq¶

Examples¶

ne¶

Examples¶

lt¶

Examples¶

le¶

Examples¶

gt¶

Examples¶

ge¶

Examples¶

encodeURI¶

Examples¶

encodeURIComponent¶

Examples¶

getSelectedDisplayValue¶

Examples¶

getSelectedDisplayValues¶

Examples¶

lookup¶

Example¶

and¶

Example¶

or¶

Example¶

not¶

Example¶

Widget helpers¶

formatNumber¶

Examples¶

formatDate¶

Examples¶

Foundry helpers¶

joinParams¶

Examples¶

SQL helpers¶

alias¶

Examples¶

schema¶

Examples¶

table¶

Examples¶

column¶

Examples¶

param¶

Examples¶

中文翻译¶

Handlebars 辅助函数(Helper)¶

内置辅助函数(Built-in helpers)¶

核心辅助函数(Core helpers)¶