Docs

Published: Friday, December 13th, 2013 by Chris Zieba


Runtime

The viewer and templates share some common function definitions, but there are some minor differences in the usage between the viewer and template system. Each function provides example usage for both the viewer, and the template language.

capitalize()

Description

The capitalize() function returns a string with the first letter capitalized.

Syntax

capitalize(string)

Parameters

string The {string} to capitalize. If string is not a string, then it is converted to one. Leading whitespace in the string is ignored.

Examples

Viewer

You can pass in a raw string, or a collected variable. The result will be John, assuming there is a variable called first_name with the value john. You can also pass in a collected variable from a loop. The array index can be an {int} or a {variable} which contains an {int}.

// returns 'John'
<% capitalize('john') %>

// first_name is a variable which contains a string
<% capitalize(first_name) %>

// first_name is a variable which is part of a loop
<% capitalize(first_name[0]) %>

// counter is a variable which contains an {int}
<% capitalize(first_name[counter]) %>

Template

You can pass in a raw string, or a collected variable. The result will be John, assuming there is a variable called first_name with the value john. You can also pass in a collected variable from a loop. The array index can be an { int } or a { variable } which contains an { int }.

// returns 'John'
<%= capitalize('john') %>

// first_name is a variable which contains a string
<%= capitalize(master['first_name'].getAnswer()) %>

<%= capitalize(master['first_name'].getAnswer()[0]) %>
<%= capitalize(master['first_name'].getAnswer()[master['counter'].getAnswer()]) %>

dateDays()

Description

Return the number of days since 1900.

Syntax

dateDays(date [,format])

Parameters

date A date {string}.
format The {string} format of the date parameter. Possible options are 'MM/DD/YYYY' and 'DD/MM/YYYY'. If no format is given then 'MM/DD/YYYY' will be used.

Examples

Viewer

// returns '44504'
<% dateDays('12/24/1977') %>

// returns '44504'
<% dateDays('12/24/1977', 'MM/DD/YYYY') %>

// you can also pass variables in
<% dateDays(dob, 'MM/DD/YYYY') %>

// you can also pass array values in
<% dateDays(dob[count]) %>

Template

// returns '44504'
<%= dateDays('12/24/1977') %>

// returns '44504'
<%= dateDays('12/24/1977', 'MM/DD/YYYY') %>

// you can also pass variables in
<%= dateDays(master['dob'].getAnswer(), 'MM/DD/YYYY') %>

// you can also pass array values in
<%= dateDays(master['dob'].getAnswer()[count]) %>

dateDifference()

Description

The difference between two dates. The first three arguments are mandatory, and if the last two are not given we set the date d2 to today. If the second date parameter d2 comes after the first, than the result will be positive.

Syntax

dateDifference(d1 ,d1_format, unit [,d2,d2_format])

Parameters

d1 A date {string}.
d1_format The {string} format of the d1 parameter. Possible options are 'MM/DD/YYYY' and 'DD/MM/YYYY'
unit The {string" unit for the difference. Possible values are 'months', 'days', 'years'.
d2 A date {string} of the date to compare against.
d2_format The {string} format of the d2 parameter. Possible options are 'MM/DD/YYYY' and 'DD/MM/YYYY'

Examples

Viewer

// returns '12426'
<% dateDifference('12/24/1977', 'MM/DD/YYYY', 'days', '01/01/2012', 'MM/DD/YYYY') %>

// returns '13139' based on today value of 12/13/2013
<% dateDifference('12/24/1977', 'MM/DD/YYYY', 'days') %>

// returns '408'
<% dateDifference('12/24/1977', 'MM/DD/YYYY', 'months', '01/01/2012', 'MM/DD/YYYY') %>

// returns '34'
<% dateDifference('12/24/1977', 'MM/DD/YYYY', 'months', '01/01/2012', 'MM/DD/YYYY') %>

// you can also pass variables in
<% dateDifference(dob, 'MM/DD/YYYY', 'months') %>

// you can also pass array values in
<% dateDifference(dob[count], 'MM/DD/YYYY', 'months') %>
<% dateDifference(dob[count], 'MM/DD/YYYY', 'months', entered[count], 'DD/MM/YYYY') %>

Template

// returns '12426'
<%= dateDifference('12/24/1977', 'MM/DD/YYYY', 'days', '01/01/2012', 'MM/DD/YYYY') %>

// returns '13139' based on today value of 12/13/2013
<%= dateDifference('12/24/1977', 'MM/DD/YYYY', 'days') %>

// returns '408'
<%= dateDifference('12/24/1977', 'MM/DD/YYYY', 'months', '01/01/2012', 'MM/DD/YYYY') %>

// returns '34'
<%= dateDifference('12/24/1977', 'MM/DD/YYYY', 'months', '01/01/2012', 'MM/DD/YYYY') %>

// you can also pass variables in
<%= dateDifference(master['date_of_birth'].getAnswer(), 'MM/DD/YYYY', 'months') %>

// you can also pass array values in
<%= dateDifference(master['date_of_birth'].getAnswer()[count], 'MM/DD/YYYY', 'months', master['entered'].getAnswer()[count], 'DD/MM/YYYY') %>

dateFormat()

Description

Returns a given date in another format.

Syntax

dateFormat(date [,in_format,out_format])

Parameters

date A date {string}.
in_format The {string} format of the date parameter. Possible options are 'MM/DD/YYYY' and 'DD/MM/YYYY'
out_format The {string} format of the returned date. See here for all possible output formats.

Examples

Viewer

// returns 'Saturday, December 24th 1977, 12:00:00 am'
<% dateFormat('12/24/1977', 'MM/DD/YYYY', 'dddd, MMMM Do YYYY, h:mm:ss a') %>

// you can pass in variables as well
<% dateFormat(date_of_birth, 'MM/DD/YYYY', 'dddd, MMMM Do YYYY, h:mm:ss a') %>

// you can pass in array indexes as well
<% dateFormat(date_of_birth[0], 'MM/DD/YYYY', 'dddd, MMMM Do YYYY, h:mm:ss a') %>

Template

// returns 'Saturday, December 24th 1977, 12:00:00 am'
<% dateFormat('12/24/1977', 'MM/DD/YYYY', 'dddd, MMMM Do YYYY, h:mm:ss a') %>

// you can pass in variables as well
<% dateFormat(master['date_of_birth'].getAnswer(), 'MM/DD/YYYY', 'dddd, MMMM Do YYYY, h:mm:ss a') %>

// you can pass in array indexes as well
<% dateFormat(master['date_of_birth'].getAnswer()[0], 'MM/DD/YYYY', 'dddd, MMMM Do YYYY, h:mm:ss a') %>

exit()

Description

Exits a stylesheet. This function is used to determine if we want to add the stylesheet or not. Sometimes a stylesheet depends on the value of a variable, so if this is called, all processing on the stylesheet is abandoned. It is best to check this at the beginning of a style sheet. This function is available in templates only.

Syntax

exit()

Examples

Template

// exits the stylsheet
<% exit() %>

formatMoney()

Description

Format a given string into a currency string. For more information, please see the documentation for this library.

Syntax

formatMoney(str)

Parameters

str The {string} to format.

Examples

Viewer

// returns '$12,345,678.00'
<% formatMoney(12345678) %>

// you can also pass variables in
<% formatMoney(rent) %>

// you can also pass array values in
<% formatMoney(rent[count]) %>

Template

// returns '$12,345,678.00'
<%= formatMoney(12345678) %>

// you can also pass variables in
<%= formatMoney(master['rent'].getAnswer()) %>

// you can also pass array values in
<%= formatMoney(master['rent].getAnswer()[count]) %>

formatNumber()

Description

Format a number with custom precision and localization. For more information, please see the documentation for this library.

Syntax

formatNumber(str [,precision,localization])

Parameters

str The {string} to format.
precision An {int} with the custom precision.
localization A {string} separator for thousands.

Examples

Viewer

// returns '5,318,008.00'
<% formatNumber(5318008) %>

// returns '5 318 008.000'
<% formatNumber(5318008, '3', ' ') %>

// you can also pass variables in
<% formatNumber(rent) %>

// you can also pass array values in
<% formatNumber(rent[count]) %>

Template

// returns '$12,345,678.00'
<%= formatNumber(12345678) %>

// returns '5 318 008.000'
<% formatNumber(5318008, '3', ' ') %>

// you can also pass variables in
<%= formatNumber(master['rent'].getAnswer()) %>

// you can also pass array values in
<%= formatNumber(master['rent].getAnswer()[count]) %>

get()

Description

Returns the value (or values, if {array}) of the given answer as a string. This function is only available in templates.

Syntax

get(name [,index])

Parameters

name A {string} value of the variable.
index Optional loop {int} index

Examples

Template

// pass in the name of the variable
<%= get('dob') %>

// pass in an array index
<%= get('dob', 0) %>

isAnswered()

Description

Checks if a variable is answered and has a value (not empty string). A question is considered answered if the variable is defined in the interview, and it is not an empty string. Returns a {boolean}.

Syntax

Viewer

The viewer has a slightly different syntax for this function because of the way variables are stored.

isAnswered(var)

Template

isAnswered(name [,index])

Parameters

Viewer

var The {variable} we are checking from the interview. For example, if a field is named 'first_name', this would be passed in.

Template

name A {string} or {array} containing the name of the variable(s) to lookup.
index An {int} referencing the loop index. If a variable is part of a loop, the answers are stores as an array so we need to pass in the array index to correctly look up if an answer exists.

Examples

Viewer

// returns true or false based on the value of the variable 'q16_1'
isAnswered(q16_1)

// pass in an array index
isAnswered(q16_1[1])

// pass in an array index as a variable
isAnswered(q16_1[counter])

Template

// returns true or false based on the value of the variable 'q16_1'
<% if (isAnswered('q16_1')) {  ... } %>

// pass in an array index
<% if (isAnswered('q16_1', 0)) {  ... } %>

// pass in an array index as a variable
<% if (isAnswered('q16_1', master['counter'].getAnswer())) {  ... } %>

isChecked()

Description

Takes the name and the id of the checkbox we want to evaluate. If the checkbox is part of a loop the index needs to be passed in to correctly parse the checkbox. To check if nota was checked, pass in 'nota' as the id parameter. Returns a {boolean}.

Syntax

Viewer

isChecked(var, id)

Template

isChecked(name, id [,index])

Parameters

Viewer

var A {variable} containing the checkbox.
id A {string} or {array} of the ID given to the checkbox field option in the editor.

Template

name A {string} containing the name of the checkbox field.
id A {string} or {array} of the ID given to the checkbox field option in the editor.
index An {int} referencing the loop index. If a variable is part of a loop, the answers are stores as an array so we need to pass in the array index to correctly look up the field.

Examples

Viewer

// returns true or false based on whether or not the option 'soccer' was checked off in the sports_selected checkbox field
isChecked(sports_selected, 'soccer')

// pass in an array index
isChecked(sports_selected[0], 'soccer')

// pass in an array index as a variable
isChecked(sports_selected[counter], 'soccer')

// check if 'None of the above was selected'
isChecked(sports_selected[0], 'nota')

// returns true if soccer and baseball are both checked
isChecked(sports_selected, ['soccer', 'baseball'])

Template

// returns true or false based on whether or not the option 'soccer' was checked off in the sports_selected checkbox field
<% if (isChecked('sports_selected', 'soccer')) {  ... } %>

// pass in an array index
<% if (isChecked('sports_selected', 'soccer', 0)) {  ... } %>

// pass in an array index as a variable
<% if (isChecked('sports_selected', 'soccer', master['counter'].getAnswer())) {  ... } %>

// check if 'None of the above was selected'
<% if (isChecked('sports_selected', 'nota', 0)) {  ... } %>

// returns true if soccer and baseball are both checked
<% if (isChecked('sports_selected', ['soccer','baseball'], 0)) {  ... } %>

numberWord()

Description

Return the ordinal of a given index up to 20. This does not add a suffix, like ordinal() does.

Syntax

numberWord(number)

Parameters

number A {number}.

Examples

Viewer

// returns one
<% numberWord('1') %>

// variables can also be passed in
<% numberWord(age) %>
<% numberWord(age[0]) %>
<% numberWord(age[counter]) %>

Template

// returns one
<%= numberWord('1') %>

// variables can also be passed in
<%= numberWord(master['age'].getAnswer()) %>
<%= numberWord(master['age'].getAnswer()[0]) %>
<%= numberWord(master['age'].getAnswer()[master['counter'].getAnswer()]) %>

ordinal()

Description

Return the ordinal of a given number. If the second argument is given then the result is in the form 1st, otherwise, the format is 'first'.

Syntax

ordinal(number [,boolean])

Parameters

number A {number}.
boolean {Boolean} True or False.

Examples

Viewer

// returns 'eighth'
<% ordinal(8) %>

// returns '8th'
<% ordinal(8, true) %>

// you can pass in variables collected during the interview
<% ordinal(age, true) %>

Template

// returns 'eighth'
<%= ordinal(8) %>

// returns '8th'
<%= ordinal(8, true) %>

// you can pass in variables collected during the interview
<%= ordinal(master['age'].getAnswer()) %>

round()

Description

The round() function returns the value of a number rounded to the nearest integer. If the fractional portion of number is .5 or greater, the argument is rounded to the next higher integer. If the fractional portion of number is less than .5, the argument is rounded to the next lower integer.

Syntax

round(number)

Parameters

number A {number}.

Examples

Viewer

// returns 1
<% round('1.3') %> 

// a variable is passed in
<% round(age) %>

// age is part of a loop and we are passing in the first array value
<% round(age[0]) %>

<% round(age[counter]) %>

Template

// returns 1
<%= round('1.3') %> 

// the variable name must be quoted
<%= round(master['age'].getAnswer()) %>

<%= round(master['age'].getAnswer()[0]) %>

<%= round(master['age'].getAnswer()[master['counter'].getAnswer()]) %>

sum()

Description

Returns the sum {float} of an array of numbers.

Syntax

sum(values)

Parameters

values An {array} of numbers.

Examples

Viewer

// returns 6.0
<% sum([1,2,3]) %>

// returns 6.0
<% sum(['1','2','3'])%>

// you can also pass variables in
<% sum(rent_each_month) %>

Template

// returns 6.0
<%= sum([1,2,3]) %>

// returns 6.0
<%= sum(['1','2','3'])%>

// you can also pass variables in
<%= sum(master['rent_each_month'].getAnswer()) %>