Using Sanbox Text Templates

Understanding the Sanbox Text Template System

Sanbox Text Templates are used throughout Sanbox for Nodes that run SQL, the text template Conduit source, and other areas. The system is a thin addition on top of the open-source Scriban framework.

Basic Usage

Templates start with {{ and end with }} .

Inserting Input & Variables

The following template inserts input data in the middle of the sentence.

Hi! My name is {{ input }}, how are you?

In addition, for input that is a complex object, you can run JSONPath using the jPathInput template function.

Hi! My name is {{ jPathInput "$.name" }}!

If you don't need JSONPath to do anything fancy you can also write:

Hi! My name is {{ input.name }}

To inject a Workflow variable into text, use the following:

You have {{ appleCount }} apples.

To use a Workflow variable that is a complex object:

You have {{ appleData.count }} apples.

To use a Workflow variable that is a complex object, using JSONPath you can write:

You have {{ jPathVariable "appleData" "$.count" }} apples.

When using SQL nodes in Protected Template mode, you should not use member access on any object, i.e input.name and instead use the jPath functions. Otherwise, you will receive errors caused by the strict nature of Sanbox's anti SQL injection system.

HTML Rendering

The following example shows usage of a foreach loop on an array of products.

Here is our data:

[
{
"name": "Apple",
"description": "Great fruit.",
"price": 0.50
},
{
"name": "Avacado",
"description": "Full of good fats.",
"price": 1.50
},
{
"name": "Peach",
"description": "Fuzzy?",
"price": 1.00
},
{
"name": "Grapefruit",
"description": "Once upon a time there was a great Grapefruit named Kyle.",
"price": 1.00
}
]

We have the following text template later in our workflow:

{{ for product in input }}
<h2>{{ product.name }}</h2>
<p>Price: {{ product.price }}</p>
<p>{{ product.description | string.truncate 25 }}</p>
{{ end }}

The workflow takes the data, renders it, and produces HTML to be sent as a web page.

Example HTML Rendering Workflow W/ Static Data

Our API Request Node is configured to listen on https://localhost/products and our Response Node is configured to return a Content-Type header value of text/html. Opening our web browser and navigating to the workflow yields this web page:

Rendered Web Page

Built-In Helpers: HTML

html.strip

html.strip <text>

Description

Removes any HTML tags from the input string

Arguments

  • text: The input string

Returns

The input string removed with any HTML tags

Examples

input

{{ "<p>This is a paragraph</p>" | html.strip }}

output

This is a paragraph

html.escape

html.escape <text>

Description

Escapes a HTML input string (replacing & by &amp;)

Arguments

  • text: The input string

Returns

The input string removed with any HTML tags

Examples

input

{{ "<p>This is a paragraph</p>" | html.escape }}

output

&lt;p&gt;This is a paragraph&lt;/p&gt;

html.url_encode

html.url_encode <text>

Description

Converts any URL-unsafe characters in a string into percent-encoded characters.

Arguments

  • text: The input string

Returns

The input string url encoded

Examples

input

{{ "john@example.com" | html.url_encode }}

output

john%40example.com

html.url_escape

html.url_escape <text>

Description

Identifies all characters in a string that are not allowed in URLS, and replaces the characters with their escaped variants.

Arguments

  • text: The input string

Returns

The input string url escaped

Examples

input

{{ "<hello> & <scriban>" | html.url_escape }}

output

%3Chello%3E%20&%20%3Cscriban%3E

Built-In Helpers: Regex

regex.escape

regex.escape <pattern>

Description

Escapes a minimal set of characters (\, *, +, ?, |, {, [, (,), ^, $,., #, and white space) by replacing them with their escape codes. This instructs the regular expression engine to interpret these characters literally rather than as metacharacters.

Arguments

  • pattern: The input string that contains the text to convert.

Returns

A string of characters with metacharacters converted to their escaped form.

Examples

input

{{ "(abc.*)" | regex.escape }}

output

\(abc\.\*\)

regex.match

regex.match <text> <pattern> <options>?

Description

Searches an input string for a substring that matches a regular expression pattern and returns an array with the match occurrences.

Arguments

  • text: The string to search for a match.

  • pattern: The regular expression pattern to match.

  • options: A string with regex options, that can contain the following option characters (default is null): - i: Specifies case-insensitive matching. - m: Multiline mode. Changes the meaning of ^ and $ so they match at the beginning and end, respectively, of any line, and not just the beginning and end of the entire string. - s: Specifies single-line mode. Changes the meaning of the dot . so it matches every character (instead of every character except \n). - x: Eliminates unescaped white space from the pattern and enables comments marked with #.

Returns

An array that contains all the match groups. The first group contains the entire match. The other elements contain regex matched groups (..). An empty array returned means no match.

Examples

input

{{ "this is a text123" | regex.match `(\w+) a ([a-z]+\d+)` }}

output

[is a text123, is, text123]

Notice that the first element returned in the array is the entire regex match, followed by the regex group matches.

regex.replace

regex.replace <text> <pattern> <replace> <options>?

Description

In a specified input string, replaces strings that match a regular expression pattern with a specified replacement string.

Arguments

  • text: The string to search for a match.

  • pattern: The regular expression pattern to match.

  • replace: The replacement string.

  • options: A string with regex options, that can contain the following option characters (default is null): - i: Specifies case-insensitive matching. - m: Multiline mode. Changes the meaning of ^ and $ so they match at the beginning and end, respectively, of any line, and not just the beginning and end of the entire string. - s: Specifies single-line mode. Changes the meaning of the dot . so it matches every character (instead of every character except \n). - x: Eliminates unescaped white space from the pattern and enables comments marked with #.

Returns

A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If pattern is not matched in the current instance, the method returns the current instance unchanged.

Examples

input

{{ "abbbbcccd" | regex.replace "b+c+" "-Yo-" }}

output

a-Yo-d

regex.split

regex.split <text> <pattern> <options>?

Description

Splits an input string into an array of substrings at the positions defined by a regular expression match.

Arguments

  • text: The string to split.

  • pattern: The regular expression pattern to match.

  • options: A string with regex options, that can contain the following option characters (default is null): - i: Specifies case-insensitive matching. - m: Multiline mode. Changes the meaning of ^ and $ so they match at the beginning and end, respectively, of any line, and not just the beginning and end of the entire string. - s: Specifies single-line mode. Changes the meaning of the dot . so it matches every character (instead of every character except \n). - x: Eliminates unescaped white space from the pattern and enables comments marked with #.

Returns

A string array.

Examples

input

{{ "a, b , c, d" | regex.split `\s*,\s*` }}

output

[a, b, c, d

regex.unescape

regex.unescape <pattern>

Description

Converts any escaped characters in the input string.

Arguments

  • pattern: The input string containing the text to convert.

Returns

A string of characters with any escaped characters converted to their unescaped form.

Examples

input

{{ "\\(abc\\.\\*\\)" | regex.unescape }}

output

(abc.*)

Built-In Helpers: Strings

string.append

string.append <text> <with>

Description

Concatenates two strings

Arguments

  • text: The input string

  • with: The text to append

Returns

The two strings concatenated

Examples

input

{{ "Hello" | string.append " World" }}

output

Hello World

string.capitalize

string.capitalize <text>

Description

Converts the first character of the passed string to a upper case character.

Arguments

  • text: The input string

Returns

The capitalized input string

Examples

input

{{ "test" | string.capitalize }}

output

Test

string.capitalizewords

string.capitalizewords <text>

Description

Converts the first character of each word in the passed string to a upper case character.

Arguments

  • text: The input string

Returns

The capitalized input string

Examples

input

{{ "This is easy" | string.capitalizewords }}

output

This Is Easy

string.contains

string.contains <text> <value>

Description

Returns a boolean indicating whether the input string contains the specified string value.

Arguments

  • text: The input string

  • value: The string to look for

Returns

if text contains the string value

Examples

input

{{ "This is easy" | string.contains "easy" }}

output

true

string.downcase

string.downcase <text>

Description

Converts the string to lower case.

Arguments

  • text: The input string

Returns

The input string lower case

Examples

input

{{ "TeSt" | string.downcase }}

output

test

string.ends_with

string.ends_with <text> <value>

Description

Returns a boolean indicating whether the input string ends with the specified string value.

Arguments

  • text: The input string

  • value: The string to look for

Returns

if text ends with the specified string value

Examples

input

{{ "This is easy" | string.ends_with "easy" }}

output

true

string.handleize

string.handleize <text>

Description

Returns a url handle from the input string.

Arguments

  • text: The input string

Returns

A url handle

Examples

input

{{ '100% M & Ms!!!' | string.handleize }}

output

100-m-ms

string.lstrip

string.lstrip <text>

Description

Removes any whitespace characters on the left side of the input string.

Arguments

  • text: The input string

Returns

The input string without any left whitespace characters

Examples

input

{{ ' too many spaces ' | string.lstrip }}

Highlight to see the empty spaces to the right of the string output

too many spaces

string.pluralize

string.pluralize <number> <singular> <plural>

Description

Outputs the singular or plural version of a string based on the value of a number.

Arguments

  • number: The number to check

  • singular: The singular string to return if number is == 1

  • plural: The plural string to return if number is != 1

Returns

The singular or plural string based on number

Examples

input

{{ products.size }} {{products.size | string.pluralize 'product' 'products' }}

output

7 products

string.prepend

string.prepend <text> <by>

Description

Concatenates two strings by placing the by string in from of the text string

Arguments

  • text: The input string

  • by: The string to prepend to text

Returns

The two strings concatenated

Examples

input

{{ "World" | string.prepend "Hello " }}

output

Hello World

string.remove

string.remove <text> <remove>

Description

Removes all occurrences of a substring from a string.

Arguments

  • text: The input string

  • remove: The substring to remove from the text string

Returns

The input string with the all occurence of a substring removed

Examples

input

{{ "Hello, world. Goodbye, world." | string.remove "world" }}

output

Hello, . Goodbye, .

string.remove_first

string.remove_first <text> <remove>

Description

Removes the first occurrence of a substring from a string.

Arguments

  • text: The input string

  • remove: The first occurence of substring to remove from the text string

Returns

The input string with the first occurence of a substring removed

Examples

input

{{ "Hello, world. Goodbye, world." | string.remove_first "world" }}

output

Hello, . Goodbye, world.

string.replace

string.replace <text> <match> <replace>

Description

Replaces all occurrences of a string with a substring.

Arguments

  • text: The input string

  • match: The substring to find in the text string

  • replace: The substring used to replace the string matched by match in the input text

Returns

The input string replaced

Examples

input

{{ "Hello, world. Goodbye, world." | string.replace "world" "buddy" }}

output

Hello, buddy. Goodbye, buddy.

string.replace_first

string.replace_first <text> <match> <replace>

Description

Replaces the first occurrence of a string with a substring.

Arguments

  • text: The input string

  • match: The substring to find in the text string

  • replace: The substring used to replace the string matched by match in the input text

Returns

The input string replaced

Examples

input

{{ "Hello, world. Goodbye, world." | string.replace_first "world" "buddy" }}

output

Hello, buddy. Goodbye, world.

string.rstrip

string.rstrip <text>

Description

Removes any whitespace characters on the right side of the input string.

Arguments

  • text: The input string

Returns

The input string without any left whitespace characters

Examples

input

{{ ' too many spaces ' | string.rstrip }}

Highlight to see the empty spaces to the right of the string output

too many spaces

string.size

string.size <text>

Description

Returns the number of characters from the input string

Arguments

  • text: The input string

Returns

The length of the input string

Examples

input

{{ "test" | string.size }}

output

4

string.slice

string.slice <text> <start> <length: 0>?

Description

The slice returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring with the remaining characters will be returned.

Arguments

  • text: The input string

  • start: The starting index character where the slice should start from the input text string

  • length: The number of character. Default is 0, meaning that the remaining of the string will be returned.

Returns

The input string sliced

Examples

input

{{ "hello" | string.slice 0 }}
{{ "hello" | string.slice 1 }}
{{ "hello" | string.slice 1 3 }}
{{ "hello" | string.slice 1 length:3 }}

output

hello
ello
ell
ell

string.slice1

string.slice1 <text> <start> <length: 1>?

Description

The slice returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring with the first character will be returned.

Arguments

  • text: The input string

  • start: The starting index character where the slice should start from the input text string

  • length: The number of character. Default is 1, meaning that only the first character at start position will be returned.

Returns

The input string sliced

Examples

input

{{ "hello" | string.slice1 0 }}
{{ "hello" | string.slice1 1 }}
{{ "hello" | string.slice1 1 3 }}
{{ "hello" | string.slice1 1 length: 3 }}

output

h
e
ell
ell

string.split

string.split <text> <match>

Description

The split function takes on a substring as a parameter. The substring is used as a delimiter to divide a string into an array. You can output different parts of an array using array functions.

Arguments

  • text: The input string

  • match: The string used to split the input text string

Returns

An enumeration of the substrings

Examples

input

{{ for word in "Hi, how are you today?" | string.split ' ' ~}}
{{ word }}
{{ end ~}}

output

Hi,
how
are
you
today?

string.starts_with

string.starts_with <text> <value>

Description

Returns a boolean indicating whether the input string starts with the specified string value.

Arguments

  • text: The input string

  • value: The string to look for

Returns

if text starts with the specified string value

Examples

input

{{ "This is easy" | string.starts_with "This" }}

output

true

string.strip

string.strip <text>

Description

Removes any whitespace characters on the left and right side of the input string.

Arguments

  • text: The input string

Returns

The input string without any left and right whitespace characters

Examples

input

{{ ' too many spaces ' | string.strip }}

Highlight to see the empty spaces to the right of the string output

too many spaces

string.strip_newlines

string.strip_newlines <text>

Description

Removes any line breaks/newlines from a string.

Arguments

  • text: The input string

Returns

The input string without any breaks/newlines characters

Examples

input

{{ "This is a string.\r\n With \nanother \rstring" | string.strip_newlines }}

output

This is a string. With another string

string.to_int

string.to_int <text>

Description

Converts a string to an integer

Arguments

  • text: The input string

Returns

A 32 bit integer or null if conversion failed

Examples

input

{{ "123" | string.to_int + 1 }}

output

124

string.to_long

string.to_long <text>

Description

Converts a string to a long 64 bit integer

Arguments

  • text: The input string

Returns

A 64 bit integer or null if conversion failed

Examples

input

{{ "123678912345678" | string.to_long + 1 }}

output

123678912345679

string.to_float

string.to_float <text>

Description

Converts a string to a float

Arguments

  • text: The input string

Returns

A 32 bit float or null if conversion failed

Examples

input

{{ "123.4" | string.to_float + 1 }}

output

124.4

string.to_double

string.to_double <text>

Description

Converts a string to a double

Arguments

  • text: The input string

Returns

A 64 bit float or null if conversion failed

Examples

input

{{ "123.4" | string.to_double + 1 }}

output

124.4

string.truncate

string.truncate <text> <length> <ellipsis>?

Description

Truncates a string down to the number of characters passed as the first parameter. An ellipsis (...) is appended to the truncated string and is included in the character count

Arguments

  • text: The input string

  • length: The maximum length of the output string, including the length of the ellipsis

  • ellipsis: The ellipsis to append to the end of the truncated string

Returns

The truncated input string

Examples

input

{{ "The cat came back the very next day" | string.truncate 13 }}

output

The cat ca...

string.truncatewords

string.truncatewords <text> <count> <ellipsis>?

Description

Truncates a string down to the number of words passed as the first parameter. An ellipsis (...) is appended to the truncated string.

Arguments

  • text: The input string

  • count: The number of words to keep from the input text string before appending the ellipsis

  • ellipsis: The ellipsis to append to the end of the truncated string

Returns

The truncated input string

Examples

input

{{ "The cat came back the very next day" | string.truncatewords 4 }}

output

The cat came back...

string.upcase

string.upcase <text>

Description

Converts the string to uppercase

Arguments

  • text: The input string

Returns

The input string upper case

Examples

input

{{ "test" | string.upcase }}

output

TEST

string.md5

string.md5 <text>

Description

Computes the md5 hash of the input string

Arguments

  • text: The input string

Returns

The md5 hash of the input string

Examples

input

{{ "test" | string.md5 }}

output

098f6bcd4621d373cade4e832627b4f6

string.sha1

string.sha1 <text>

Description

Computes the sha1 hash of the input string

Arguments

  • text: The input string

Returns

The sha1 hash of the input string

Examples

input

{{ "test" | string.sha1 }}

output

a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

string.sha256

string.sha256 <text>

Description

Computes the sha256 hash of the input string

Arguments

  • text: The input string

Returns

The sha256 hash of the input string

Examples

input

{{ "test" | string.sha256 }}

output

9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

string.hmac_sha1

string.hmac_sha1 <text> <secretKey>

Description

Converts a string into a SHA-1 hash using a hash message authentication code (HMAC). Pass the secret key for the message as a parameter to the function.

Arguments

  • text: The input string

  • secretKey: The secret key

Returns

The SHA-1 hash of the input string using a hash message authentication code (HMAC)

Examples

input

{{ "test" | string.hmac_sha1 "secret" }}

output

1aa349585ed7ecbd3b9c486a30067e395ca4b356

string.hmac_sha256

string.hmac_sha256 <text> <secretKey>

Description

Converts a string into a SHA-256 hash using a hash message authentication code (HMAC). Pass the secret key for the message as a parameter to the function.

Arguments

  • text: The input string

  • secretKey: The secret key

Returns

The SHA-256 hash of the input string using a hash message authentication code (HMAC)

Examples

input

{{ "test" | string.hmac_sha256 "secret" }}

output

0329a06b62cd16b33eb6792be8c60b158d89a2ee3a876fce9a881ebb488c0914

string.pad_left

string.pad_left <text> <width>

Description

Pads a string with leading spaces to a specified total length.

Arguments

  • text: The input string

  • width: The number of characters in the resulting string

Returns

The input string padded

Examples

input

hello{{ "world" | string.pad_left 10 }}

output

hello world

string.pad_right

string.pad_right <text> <width>

Description

Pads a string with trailing spaces to a specified total length.

Arguments

  • text: The input string

  • width: The number of characters in the resulting string

Returns

The input string padded

Examples

input

{{ "hello" | string.pad_right 10 }}world

output

hello world

Advance Usage - Language Features

You can get a full list of language features and additional built-in functions on the Scriban GitHub Page. Scriban has many additional features such as IF statements, expressions, and more.