Expression
Expression functions are non-visual widgets that you can use to evaluate a JavaScript expression. You can write JavaScript expressions to validate, calculate, convert, and compare data in your mashup.
Use the parameter option to create new parameters for the function. You can set the data type and the default value for each parameter. Parameters are used by the function to store data values. You can create parameters to bind data from sources such as property fields and data services in the mashup. All parameters are listed as bindable properties under the Parameters section for the function.
You can select the output data type for the parameters using the Output Base Type option. Data comparison expressions return a BOOLEAN output. Calculations or string manipulations return a NUMBER or a STRING data type. Make sure that the target widget for the Output property supports the output base type.
The expression field enables you to define JavaScript code. You can define arithmetic, comparison, and regular expressions.
Arithmetic Expressions
• Simple expressions—Using simple operators to perform addition, subtraction, multiplication, and division. For example:
(Parameter1 + Parameter2) / Parameter3 returns the sum of Parameter1 and Parameter2 divided by Parameter3.
• Complex expressions—Using functions to perform calculations such as exponents, square roots, and natural logarithms.
Math.pow(Parameter1, Parameter2) returns Parameter1 raised to the power of Parameter2.
Comparison Expressions
You can use all of the JavaScript comparison operators to compare data from input parameters.
Regular Expressions
The Expression function supports the JavaScript notation for regular expressions. You can use regular expressions to validate and filter input data using the following syntax.
• /<expression>/.test(<parameter>)
◦ <expression>—The regular expression to evaluate.
◦ test()—A method that compares the specified data parameter with the expression.
◦ <parameter>—The name of the parameter with the data to evaluate.
• /^(?:\d{3}\-){2}\d{4}$/.test(phoneNumber)
◦ ^—The beginning of the string.
◦ (?:\d{3}\-){2}—Matches three number digits followed by a dash, and repeats twice. (###-###-)
◦ \d{4}—Matches a single digit and repeats four times. (####)
◦ $—The end of the string.
Logging JavaScript Exceptions
Exceptions occur when your JavaScript expression returns an error. You can log exceptions by using the TW.log.error method. In the following example, an exception occurs because the function is not defined:
try {
undefinedFunction();
}
catch (e){
TW.log.error("The function does not exist: " + e);
}
undefinedFunction();
}
catch (e){
TW.log.error("The function does not exist: " + e);
}
 |
Errors are logged during run time. Click Show/Hide Log on the top toolbar to show or hide the Mashup Builder logs.
|
Expression Function Options
You can set the following configuration options:
• Description—Sets a description for the function.
• Parameters—Specifies custom parameters for the function.
• Expression—The JavaScript expression to evaluate.
• Auto Evaluate—Evaluates the expressions automatically when input parameter data is changed.
• Fire on First Value—Evaluates the JavaScript expression when the first value is passed in. The expression is not evaluated when a second value is passed in.
• Data Change Type—Controls when the changed event is triggered.
• Output Base Type—The data type of the expression output.
• Disable Initial Output—Prevents the function from assigning an initial undefined value to the Output property before the expression is evaluated.
Creating an Expression Function
1. On the Functions panel, click 
. The New Function dialog opens.
. The New Function dialog opens.2. Select Expression from the drop down list.
3. Enter a name for the function, and then click Next.
4. Under Expression, enter a JavaScript expression to evaluate.
5. Add data input parameters:
a. Click Add Parameter.
b. Enter a parameter name.
c. Enter a default value and a tooltip, and then select a parameter base type.
6. Select a data type from the Output Base Type drop down list.
7. Click Done.
The function is added to the Functions panel under the Expressions category.
Properties
The Expression function contains the following properties.
Property | Description | Base Type | Default Value | Bindable? (Y/N) | Localizable? (Y/N) |
|---|---|---|---|---|---|
Evaluate | A bindable service that evaluates the expression. | n/a | n/a | Y | N |
Changed | A bindable property that triggers an event when the data is changed. | n/a | n/a | Y | N |
Output | The output from the evaluated expression. You can set the binding for this property directly in the expression field. To set a binding, type output=<> To prevent this property from sending an initial undefined value, select the Disable Initial Output check box. | n/a | n/a | Y | N |