S
S
SheetDream
Search…
Handlebars.js Extensions
In order to "merge" your API's data into an HTML page, SheetDream utilizes a well known JavaScript library called Handlebars.js.
Handlebars.js has been around a long time, and has proven to be a great, simple templating language for HTML.
If you are new to Handlebars.js in general and want to know the basics, we highly recommend checking out their official documentation here.
In this section we'll be outlining the extensions SheetDream has added to Handlebars.js.

Function Extensions

SheetDream has built out a wealth of different function extensions to make the most of Handlebars.js. These functions allow you to further analyze the data coming from your API and alter the way that you display things to the end user.
Below, you will find a series of definitions, descriptions and usage examples for every extension SheetDream provides to Handlebars.js.

contains

Description: Returns true if searchString exists within target.
Syntax:
1
(contains target searchString)
Copied!
Parameter Name
Parameter Type
Description
target
string
The string of characters to search
searchString
string
The string you are searching for
Example Usage:
1
{{#if (contains Ingredients "peanut")}}
2
* allergy warning: this dish contains peanuts
3
{{/if}}
Copied!

eq

Description: Returns true if the two values are equal.
Syntax:
1
(eq a b)
Copied!
Parameter Name
Parameter Type
Description
a
any
The first value in the comparison
b
any
The second value in the comparison
Example Usage:
1
{{#if (eq Name "Steve Jobs")}}
2
Hello, Mr. Apple.
3
{{/if}}
Copied!

neq

Description: Returns true if the two values are not equal.
Syntax:
1
(neq s1 s2)
Copied!
Parameter Name
Parameter Type
Description
s1
any
The first value in the comparison
s2
any
The second value in the comparison
Example Usage:
1
{{#if (neq Name "Bill Gates")}}
2
I guess your name is not Bill Gates.
3
{{/if}}
Copied!

lt

Description: Returns true if n1 < n2.
Syntax:
1
(lt n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the comparison
n2
number
The second value in the comparison
Example Usage:
1
{{#if (lt Price 9.99)}}
2
Price is less than $9.99!
3
{{/if}}
Copied!

gt

Description: Returns true if n1 > n2.
Syntax:
1
(gt n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the comparison
n2
number
The second value in the comparison
Example Usage:
1
{{#if (gt Price 9.99)}}
2
Price is GREATER than $9.99!
3
{{/if}}
Copied!

lte

Description: Returns true if n1 <= n2.
Syntax:
1
(lte n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the comparison
n2
number
The second value in the comparison
Example Usage:
1
{{#if (lte Price 9.99)}}
2
Price is less than or equal to $9.99!
3
{{/if}}
Copied!

gte

Description: Returns true if n1 >= n2.
Syntax:
1
(gte n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the comparison
n2
number
The second value in the comparison
Example Usage:
1
{{#if (gte Price 9.99)}}
2
Price is GREATER than or equal to $9.99!
3
{{/if}}
Copied!

multiply

Description: Returns the result of n1 * n2.
Syntax:
1
(multiply n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the operation
n2
number
The second value in the operation
Example Usage:
1
5 * 2 = {{(multiply 5 2)}}
Copied!

divide

Description: Returns the result of n1 / n2. Attempting to divide by zero will just return 0.
Syntax:
1
(divide n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the operation
n2
number
The second value in the operation
Example Usage:
1
4 / 2 = {{(divide 4 2)}}
Copied!

add

Description: Returns the result of n1 + n2.
Syntax:
1
(add n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the operation
n2
number
The second value in the operation
Example Usage:
1
4 + 2 = {{(add 4 2)}}
Copied!

subtract

Description: Returns the result of n1 - n2.
Syntax:
1
(subtract n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the operation
n2
number
The second value in the operation
Example Usage:
1
4 + 2 = {{(subtract 4 2)}}
Copied!

markdown

Description: Converts the source string from markdown to HTML.
Syntax:
1
(markdown source)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the operation
n2
number
The second value in the operation
Example Usage:
1
{{{(markdown Description)}}}
Copied!
Special Note: take notice of the fact we're using triple curly braces for this one {{{ }}}. This is because Handlebars.js will "escape" any HTML you attempt to insert using the normal double curly brackets {{ }}. Triple curly brackets indicates to Handlebars.js that you want to inject raw HTML.

mod

Description: Returns the modulus of n1 and n2. The modulus is the remainder after you perform n1 / n2.
Syntax:
1
(mod n1 n2)
Copied!
Parameter Name
Parameter Type
Description
n1
number
The first value in the operation
n2
number
The second value in the operation
Example Usage:
1
{{#if (eq (mod 3 2) 1)}}
2
The number 3 is an odd number because dividing it by 2 gives a remainder of 1.
3
{{/if}}
Copied!

even

Description: Shorthand function that will return true if value is an even number.
Syntax:
1
(even value)
Copied!
Parameter Name
Parameter Type
Description
value
number
The first value in the operation
Example Usage:
1
<table>
2
<tbody>
3
{{#each data}}
4
{{#if (even @index)}}
5
<tr class="darker-shade">
6
{{else}}
7
<tr class="lighter-shade">
8
{{/if}}
9
<td>This table will have alternating colors per row.</td>
10
</tr>
11
{{/each}}
12
</tbody>
13
</table>
Copied!

odd

Description: Shorthand function that will return true if value is an odd number.
Syntax:
1
(odd value)
Copied!
Parameter Name
Parameter Type
Description
value
number
The first value in the operation
Example Usage:
1
<table>
2
<tbody>
3
{{#each data}}
4
{{#if (odd @index)}}
5
<tr class="darker-shade">
6
{{else}}
7
<tr class="lighter-shade">
8
{{/if}}
9
<td>This table will have alternating colors per row.</td>
10
</tr>
11
{{/each}}
12
</tbody>
13
</table>
Copied!

not

Description: Converts value to a boolean and performs a not operation. Not returns the opposite of what value contains: (not true) = false, (not false) = true.
Syntax:
1
(not value)
Copied!
Parameter Name
Parameter Type
Description
value
any
The first value in the operation
Example Usage:
1
{{#if (not Hungry)}}
2
I am not hungry.
3
{{else}}
4
I am hungry. Feed me.
5
{{/if}
Copied!

isblank

Description: Shorthand which returns true if value is an empty string ("").
Syntax:
1
(isblank value)
Copied!
Parameter Name
Parameter Type
Description
value
string
The string to check
Example Usage:
1
{{#if (isblank Description)}}
2
No description provided
3
{{else}}
4
{{{(markdown Description)}}}
5
{{/if}
Copied!

exists

Description: Shorthand which returns true if value exists (is defined and populated with data) in the current JSON context. Useful for optional column data.
Syntax:
1
(exists value)
Copied!
Parameter Name
Parameter Type
Description
value
any
The value to check
Example Usage:
1
{{#if (exists [Extra Information])}}
2
{{{(markdown [Extra Information])}}}
3
{{else}}
4
No description provided
5
{{/if}
Copied!

isempty

Description: Shorthand which returns true if value does not exist (is not defined and populated with data) in the current JSON context. Useful for optional column data. This is the opposite operation of exists and is equivalent to (not (exists value)).
Syntax:
1
(isempty value)
Copied!
Parameter Name
Parameter Type
Description
value
any
The value to check
Example Usage:
1
{{#if (isempty [Extra Information])}}
2
No description provided
3
{{else}}
4
{{{(markdown [Extra Information])}}}
5
{{/if}
Copied!

length

Description: Returns the length of the array, or the number of keys within a JSON object.
Syntax:
1
(length value)
Copied!
Parameter Name
Parameter Type
Description
value
array or object
The value to check
Example Usage:
1
{{#each data}}
2
<p>{{Name}}: {{Description}}</p>
3
{{/each}}
4
Showing {{(length data)}} results.
Copied!

range

Description: Given a number n, generates an array of [1..n].
Syntax:
1
(range n)
Copied!
Parameter Name
Parameter Type
Description
n
number
The number to generate a range array from
Example Usage:
1
{{#each (range data)}}
2
<p>Item #{{this}}:</p>
3
<p>
4
{{with @root.data[this]}}
5
{{Name}}: {{Description}}
6
{{/with}}
7
</p>
8
{{/each}}
Copied!

split

Description: Splits target string by splitString and returns an array of strings.
Syntax:
1
(split target splitString)
Copied!
Parameter Name
Parameter Type
Description
target
string
The string to split
splitString
string
The string to split by
Example Usage:
1
<ul>
2
{{#each (split Ingredients ",")}}
3
<li>{{this}}</li>
4
{{/each}}
5
</ul>
Copied!

join

Description: Joins array of strings by joinString and returns a string. Most likely to be used in conjunction with split.
Syntax:
1
(join array joinString)
Copied!
Parameter Name
Parameter Type
Description
array
string[]
Array of strings to join
joinString
string
The string to join with
Example Usage:
1
This is a list of ingredients with a comma AND a space between them, instead of
2
just a comma:
3
4
{{(join (split Ingredients ",") ", ")}}
Copied!

and

Description: Returns the result of a AND b. If both a and b evaluate to true, this returns true. Otherwise, false.
Syntax:
1
(and a b)
Copied!
Parameter Name
Parameter Type
Description
a
boolean
First expression
b
boolean
Second expression
Example Usage:
1
{{#if (and (gte Page 1) (lt Page 10))}}
2
{{Page}} is between 1 and 10.
3
{{/if}}
Copied!

or

Description: Returns the result of a OR b. If a or b evaluate to true, this returns true. If both evaluate to false, returns false.
Syntax:
1
(or a b)
Copied!
Parameter Name
Parameter Type
Description
a
boolean
First expression
b
boolean
Second expression
Example Usage:
1
{{#if (or (lte Page 10) (gte Page 100))}}
2
You are either in the beginning of the book (in the first ten pages)
3
or the end of the book (on page 100 or greater of this 110 page book).
4
{{/if}}
Copied!

string

Description: Converts value to a string. If value is a JSON object, will stringify it. Useful for debugging.
Syntax:
1
(string value)
Copied!
Parameter Name
Parameter Type
Description
value
any
The value to convert to a string
Example Usage:
1
{{#each data}}
2
(string this)
3
{{/each}}
Copied!

number

Description: Converts string value to a number.
Syntax:
1
(number value)
Copied!
Parameter Name
Parameter Type
Description
value
string
The string value to convert to a number
Example Usage:
1
{{#if (gt (number "57") 49)}}
2
This evaluates to true and you will see this text.
3
{{/if}}
Copied!

json

Description: Converts string value to a JSON object.
Syntax:
1
(json value)
Copied!
Parameter Name
Parameter Type
Description
value
string
Valid JSON in string form
Example Usage:
1
{{#with (json MyField)}}
2
MyField JSON has been parsed and here's the value of the field "InnerField": {{InnerField}}
3
{{/with}}
Copied!

pick

Description: Takes a value from an array by index.
Syntax:
1
(pick array 0)
Copied!
Parameter Name
Parameter Type
Description
array
array
The array to take an element from
index
number
The index of the element you want to take from the array

Description: Takes the first element in an array.
Syntax:
1
(head array)
Copied!

tail

Description: Takes the last element of an array.
Syntax:
1
(tail array)
Copied!

slice

Description: Takes all elements between x and y of an array. If y is not passed in, it will take every element from x to the end of the array.
Syntax:
1
(slice array x y)
Copied!