Mobile app session replay templates have various functions you can use to customize your session replay.

Version functions

getTemplateLanguageVersion()

Returns a version string that indicates the version of the template language.

The current version is 1.0.0.0.

See also the versionXX() comparison predicate functions.

getTemplateLibraryVersion()

Returns a version string that indicates the version of the template library.

The current version is 1.1.0.0.

See also the versionXX() comparison predicate functions.

Predicate functions

These functions return a Boolean true/false value.

JSON type id functions:

isNull(jsonValue)

isBool(jsonValue)

isInt(jsonValue)

isUInt(jsonValue)

isIntegral(jsonValue)

isDouble(jsonValue)

isNumeric(jsonValue)

isString(jsonValue)

isArray(jsonValue)

isObject(jsonValue)

These JSON type id functions return true only if the value's type is the type at the name of the function end.

isIntegral() and isNumeric() are compound tests that return if the type is of the multiple types.

isEmpty(jsonArrayValue)

Returns true if the array is empty or false if it is not.

eq(jsonValue1, jsonValue2)

Compares two JSON values for equality. jsonValue1 and jsonValue2 might be any JSON type.

fileExists("filename")

Returns True if the given file name file exists and False if the given file name does not exist.

Can be used along with readRawFile(), readJsonFile(), and template().

Note: The "filename" might include a path, but that path name specified must begin with the directory that contains the templates and the file must be contained in that directory or a subdirectory.

lt(jsonValue1, jsonValue2)

le(jsonValue1, jsonValue2)

gt(jsonValue1, jsonValue2)

ge(jsonValue1, jsonValue2)

Compares ordinal relationship of two values. jsonValue1 and jsonValue2 must either both be numeric types, or must both be strings.

Returns true if the ordinal relationship between jsonValue1 and jsonValue2 match the named condition and false if they do not.

String comparison is strictly lexical and sorted by ASCII / UTF-8 numerical values.

exists(jsonObject, "valueName1" [, "valueName2" [, "valueName3" ] ] )

This predicate function indicates whether the named values exist in a JSON object.

Returns false if either the jsonObject is not an object, any of the named values (except for the last) are not objects, or if any of the "value-name" arguments are not present in the object indicated by the parameter that precedes it.

A single call can be used to verify existence up to three levels deep with the variants that take multiple "valueName" parameters. In that case, the objects are searched in sequence so that if "valueName1" refers to an object in jsonObject, the object referred to by "valueName1" is then checked for the existence of a value named "valueName2". If that value is an object that object is then checked for the presence of a value, that is named "valueName3" if "valueName3" was also specified.

Example

if( exists( [], "layout"), template( [] ["layout"],"layout.tlt")) 
if( exists( [], "layout", "coordinates", "x" ), concat("\n<!-- X is : ", 
["layout"]["coordinates"]["x""], "-->\n") )

valueInArray(jsonValue, jsonArray)

Returns true if at least one value in the jsonArray returns true when compared with jsonValue for equality.

Example

if( valueInArray( [][tlType], ("button", "canvas", "label", "grid") ), ("exists", "does not exist") valueInArray( (3, 5, 7), ( (1, 2, 3), (4, 5, 6), (3, 5, 7)) )

Returns true.

versionEQ(jsonVersionString, jsonVersionString)

versionNE(jsonVersionString, jsonVersionString)

versionLT(jsonVersionString, jsonVersionString)

versionGT(jsonVersionString, jsonVersionString)

versionLE(jsonVersionString, jsonVersionString)

versionGE(jsonVersionString, jsonVersionString)

Compares two version strings made up of 1 or more integers that are separated by . or ,, for example, of the form ##.##.## or ##,##,##. This function returns true of false depending on the condition reflected by the function name and the string values.

See also the getTemplateLanguageVersion() and getTemplateLibraryVersion() functions.

Note: If two version strings contain a different number of integers, only the integers that they have in common are compared. For example, 5 can be thought of as 5.*.*.*.*. 5.6 and 5 are equal. If this behavior is undesired, then adding extra ".0"(s) onto the potentially shorter version string (or both) guarantees strict ordering (For example, "5.6" and "5.0.0.0" are "not equal").

Example

versionEQ("5.6" , "5.6.3")

Returns true.

versionNE("5.6" , "5.6.3")

Returns false.

versionLE("5.6" , "5.6.3")

Returns true.

versionGT("5.6" , "5.6.3")

Returns false.

versionLT("5.6" , "5.6.3")

Return false.

Although mathematical logic would say 5.6<5.6.3 is true, the semantics of the version comparison logic says that only the number of shared digits are compared. Therefore, the comparison is really 5.6<5.6, which is false.

versionGE("5.6" , "5.6.3")

Returns true.

Although mathematical logic would say 5.6>= 5.6.3 is false, the semantics of the version comparison logic says that only the number of shared digits are compared. Therefore, the comparison is really 5.6>=5.6, which is true.

Boolean logic functions

and(predicate-expression, predicate-expression)

Returns true if both predicate-expressions evaluate to true and returns false if either predicate-expression evaluates to false.

Note: The left predicate is evaluated first and if that expression evaluates to false, the right predicate expression is not evaluated and false is returned.

or(predicate-expression, predicate-expression)

Returns true if either predicate-expression evaluates to true and false if both expressions evaluate to false.

Note: The left predicate is evaluated first and if that expression evaluates to true, the right predicate expression is not evaluated and true is returned.

xor(predicate-expression, predicate-expression)

Returns true if one of the predicate-expressions evaluates to true and the other to false. Otherwise, it returns false.

Note: This function is equivalent to not(equals(predicate-expression, predicate-expression) ).

not(predicate-expression)

Returns true if the predicate-expression evaluates to false and returns false if the expression evaluates to true.

Math functions

add(jsonNumericValue, jsonNumericValue)

If both numeric parameters are integer, this function performs an integer addition and returns the integer result. If either parameter is floating point, a floating point addition is performed and the result is floating point.

sub(jsonNumericValue, jsonNumericSubtractedValue)

If both numeric parameters are integer, this function performs an integer subtraction and returns the integer result. If either parameter is floating point, a floating point subtraction is performed and the result is floating point.

mult(jsonNumericValue, jsonNumericValue)

If both numeric parameters are integer, this function performs an integer multiplication and returns the integer result. If either parameter is floating point, a floating point multiplication is performed and the result is floating point.

div(jsonNumericValue, jsonNumericDiviserValue)

If both numeric parameters are integer, this function performs an integer division (truncated) and returns the integer result. If either parameter is floating point, a floating point division is performed and the result is floating point.

remainder(jsonIntegerValue, jsonIntegerDivisorValue)

Returns the integer remainder of the first parameter divided by (modulo) the second parameter. Both parameters must be integers.

numericToFloat(jsonNumeric)

Converts any numeric type (integer, unsigned, real/float, Boolean) to a JSON real/float value. The expected use is to convert an integer parameter to a floating point number so that a subsequent math operation (for example, div()) returns a fractional result instead of truncating the result.

Example

roundFloatToInt( div( ["anIntValue"], numericToFloat( 
["anIntDivisor"] ) ) )

stringToFloat(jsonString)

Parses a jsong string that contain a floating point number and returns it as a JSON numeric value.

Example

stringToFloat("5.3")

Returns 5.3.

truncateFloatToInt(jsonFloat)

Takes a floating point JSON value and truncates it to an integer value.

Examples

truncateFloatToInt( 5.8 )

Returns 5.

truncateFloatToInt( -5.8 )

Returns -5.

roundFloatToInt(jsonFloat)

Takes a floating point JSON value and rounds it to the nearest integer value.

Examples

roundFloatToInt( 5.8 )

Returns 6.

roundFloatToInt( -5.8 )

Returns -6.

min(jsonNumericExpr, jsonNumericExpr)

max(jsonNumericExpr, jsonNumericExpr)

Returns the larger or smaller of two numeric values. Values are converted to doubles for comparison, but the original value with its type preserved is returned.

Note: Boolean false converts to 0 / 0.0 and true converts to 1 / 1.0.

Examples

min( 5, 5.5)

Returns an int value of 5.

max( 5, 5.5)

Returns a float value 5.5.

min( false, 3)

Returns the boolean value false.

arrayMin(jsonArray [ , "iter-name", accessorExpression ] )

arrayMax(jsonArray [ , "iter-name", accessorExpression ] )

Returns the smallest or largest value in an array. If the single argument version is used, the jsonArray is presumed to be a simple array of numeric values. The optional iter-name and accessorExpression parameters can be used to access elements that are contained deeper in the array structure when the jsonArray contains more complex JSON structures.

Example

arrayMin( (5, 7, true, 4.3 ) )

Returns boolean true.

arrayMax( arrayOfControls, "iter", [@"iter"]["ctrl"]["height"])

Return the maximum height of a control in an array of controls.

Note: This function is equivalent to arrayMax( foreach( arrayOfControls, "iter", [@"iter"]["ctrl"]["height"]) ).

str( jsonNumericValue )

Returns a JSON string value that contains a serialization of a numeric value. Boolean values serialize to true or false.

Template logic functions

size(jsonArrayOrObject)

Returns the number of elements in an array or object.

getMemberNames(jsonObject)

Returns a JSON array that contains the names of the values that are contained in the jsonObject parameter.

To iterate over the elements contained in an object

foreach( getMemberNames(jsonObject) , "iter", jsonObject[ [@"iter"] ] )

assert( predicate-expression, message-string-expression [, assertPassExpression] )

If the predicate-expression evaluates to false, the message-string-expression is evaluated and an unrecoverable exception is thrown that contains the resulting string for handling by the Replay Server.

If the predicate-expression evaluates to true, the optional assertPassExpression is evaluated if it is present and its result is returned. If the optional assertPassExpression is not specified, an empty string is returned.

Note: The expected usage of the two argument version of the assert() function is the sole function call within a stand-alone expression, whereas the three argument version of assert() is for use in the context of a more complex expression.

{{
assert(versionLT([$"templateLangVersion"], "2"), 
              concat("these templates only tested on version 1.x of 
              template language; template language version is : " , 
              [$"templateLangVersion"] ) )
}}

{{ if(equals([$"osType"],
      "Android), "osType is Android",
       assert (equals([$"osType"],"iOS"), concat("invalid value for 
       osType", [$"osType"]) ,
       "osType is iOS")
      )
}}

arrayConcat( arrayOfStringValues [, separatorStringValue] )

Each value that is contained in the arrayOfStringValues parameter is concatenated into a new string value. If the optional separatorStringValue parameter is specified, that value is inserted between each value of the array in the rendered output.

concat( value1, value2 [, value3 [, value4 ] ] )

2 - 4 string values may be specified that will be concatenated into a single string. If more than four string values need to be concatenated, then nested calls of concat() can be used.

template(jsonSubTree/Object, "template filename" [,defaultStringValue] )

Loads, processes and renders the result of a template instantiation into a Json string object. If the defaultStringValue is specified, it will be evaluated and returned only in the case that the "template filename" does not exist, but not for any other errors (e.g. a parsing error).

Note: The "template filename" can include a path, but that path must be specified starting with the directory containing the templates and the file must be contained in that directory or in a subdirectory.

Note: The 3 argument variant was added with template library version 1.1.0

default(expression, expression-on-error)

Allows error/exception handling for certain (recoverable) errors/exceptions. If an expression has a recoverable error, expression-on-error is evaluated, and its result is used instead.

Note: Use of default() should be avoided, when possible. It catches all defaultable errors whether the error is the one that was expected and hides problems in the templates, and makes debugging of the templates much more difficult. Use if(..., )when feasible to test for the condition that would be expected to cause an error and provide the default behavior there instead of with default().

If a condition triggers the default() frequently, performance might be impacted compared to testing for the condition in advance.

if(predicate-expression, then-expression, else-expression)

The JSON value returned by the if() function is either the result of the then-expression or the else-expression, depending on the value that is returned by the predicate expression. The predicate expression evaluates to true if a boolean value is true, an integer or unsigned integer that is not equal to 0, or a string or array is not empty.

Analogous to the C/C++ ternary operator:

     predicate ? true-value : false-value;

let("variable-name", expression-to-assign, expression-using-variable(...[@"variable-name"]...) )

This function is a limited, scoped assignment of a value to a temporary variable that is valid only for the evaluation of the expression that is the third parameter to the let() statement. The result of the expression-using-variable becomes the returned value from let(). The "variable-name" is the plain-text of the name within expression-using-variable. That value is then accessed with [@"variable-name"].

Example

let("hexClr", htmlColor(["color"]),
default(some-expression-using([@"hexClr"]), concat("problem rendering 
with ", [@"hexClr"]))
)

Note: Typically the expression-using-variable that is the third parameter to a let() call is moderately complex.

foreach(json-array, "iter-name", expression( ...[@"iter-name"]... ) )

This function iterates over the json-array parameter and assigns each element of the array to the iterator-name one at a time and evaluates expression with that context. The JSON value that results from each evaluation of the array is assigned to the corresponding element of a result array. For example, an input array with 11 elements produces a result array with exactly 11 elements. If any of the evaluations result in an unhandled exception, all results are discarded and the result is the exception.

filter(json-array, "iter-name", predicate_expression(...[@"iter-name"]...) )

This function iterates over an array much like foreach() except that the expression is a predicate-expression where the result indicates whether the corresponding element of the json-array parameter should be copied to the result array. For example, if an input array has 11 elements, the resulting array has 0 - 11 elements, depending on the predicate expression. If any of the evaluations results in an unhandled exception, the result-array is discarded and the result is the exception. The predicate_expression evaluates to true if a Boolean value is true, an integer or unsigned integer is not equal to 0, or a string or array is not empty.

readJsonFile("json filename" [, defaultJsonValue] )

Returns a JSON value parsed from a file containing a single JSON value, which might be JSON primitive value (e.g. string, integer, float, true, false or null) or a more complex value composed with JSON objects or arrays (but must still be a single value).

If the optional defaultJsonValue parameter is specified, it is evaluated and its value returned only if the "json filename" specified does not exist.

Note: The "jason filename" can include a path, but the path name that is specified must begin with the directory that contains the templates and the file must be contained in that directory or in a subdirectory.

readRawFile("filename" [, defaultStringValue] )

Loads the specified file and returns the contents as a JSON string.

If the optional defaultStringValue parameter is specified, it is evaluated and a value is returned only if filename does not exist.

Note: The "filename" can include a path, but that path must be specified starting with the directory containing the templates and the file must be contained in that directory or in a subdirectory.

readJsonFile("json filename" [, defaultJsonValue] )

Returns a JSON value parsed from a file containing a single JSON value (which can be a JSON primitive value (e.g. string, integer, float, true, false, or null) or a more complex value composed with JSON objects and/or arrays (but must still be a single value). If the optional defaultJsonValue parameter is specified, it is evaluated and its value returned only if the specified json filename does not exist.

Note: The "json filename" can include a path, but that path must be specified starting with the directory containing the templates and the file must be contained in that directory or in a subdirectory.

HTML generation functions

htmlColor( jsonIntValue )

Returns a JSON string that contains a hex representation of the integer parameter that is suitable for specifying a color in HTML. The jsonIntValue must be between 0 and 0x00FFFFFF (decimal 16777215).

htmlEscape( jsonStringValue)

Provides html escaping to avoid accidental or malicious injection of text that might interfere with the html context where the text is inserted.

htmlAttr( attrValue, attrName [, attrUnits] )

Returns a JSON string that contains a generated html attribute declaration. Any double quotation marks characters (") that are included in any of the attrValue, attrName, or attrUnits values are escaped (replaced) with " note that only double-quote characters are escaped (& is not escaped) so that you do not have to worry about accidentally double escaping if an already escaped string is passed in.

Example

htmlAttr( 5, "id" )

returns: id="5"

cssDecl( attrValue, attrName [, attrUnits] )

Returns a JSON string that contains a generated css declaration.

cssDecl( 100, "height","px" )

returns height:100px;