Expressions
When clicking on the Control Expression icon on the Layout screen of the View Designer wizard, or selecting to add an Expression in the Properties section of a control, the Expression builder screen opens. Fields and/or Controls can be used to build an expression on the selected control. The Build Expression wizard enables a user to build expressions that perform operations and return values. An expression can be a short expression that refers to a field object or a long expression that supports decision functions or formatting based on fields or other items.
Click Add Expression to add an expression on the selected control. The Add Expression Form opens.
The Context Browser consists of two tabs:
- Context - Fields available for building an expression in the context of the control
- Operators - Operators available
Fields can be dragged and dropped from the Context Browser onto the Expression Details canvas to build expressions using Operators which can be found in the Operators tab. When dragging Operators onto the canvas, drop zones are displayed to indicate where these can be dropped. A preview of the expression can be viewed in the Preview panel at the bottom of the Expression Builder. In this scenario, we've used the SaleQuantity field multiplied by the SaleUnitPrice which will be displayed in the SaleTotal control, meaning a calculation will automatically be performed on the control in runtime.
When selecting the Context tab in the Context Browser, the information as per the image below is displayed. These fields are in context of the View used and can be used in conjunction with operators to build an expression on the control. An expression can be a short expression that refers to a field object or a long expression that supports decision functions or formatting based on fields or other items.
Fields | Description |
---|---|
System Values - Current Date | Current Date or Now |
Current User - FQN | Fully Qualified Name-Representing a combination of the Label and User Name |
Current User - Display Name | The user's display name as per the user provider |
Current User - Description | Description of the current user as per the user provider |
Current User - E-mail | The user's E-mail address as per the user provider |
Current User - Manager FQN | The user's Manager as per the user provider |
Fields | The fields of the SmartObject linked to the View |
Controls | The controls used on the View |
When selecting the Operators tab in the Context Browser, the information as per the image below is displayed. These fields can be used in conjunction with operators to build an expression on the control. An expression can be a short expression that refers to a field object or a long expression that supports decision functions or formatting based on fields or other items.
Operator | Description |
---|---|
Conversion |
Converts data into other formats, based on input value and returns the converted value |
List Aggregators |
List Aggregators perform calculations, usually based on input of a collection of values and returns a number |
Date and Time | The Date and Time functions perform an operation on a date and time input value and return a string, numeric, or date and time value |
Logical | A Logical function perform a logical operation or comparison on objects and expressions and returns a Boolean value |
Mathematical | Mathematical functions perform calculations, usually based on input values and returns a number |
Operators | Provides a large set of operators, which are symbols that specify which operations to perform in an expression.The feature help topic lists the mathematical operators you can use in constructing an expression. Arithmetic operators perform mathematical operations on two expressions of one or more of the data types of the numeric data type category |
Regular Expression | Regular Expressions provide a powerful, flexible, and efficient method for Workflowing text. A regular expression is a pattern that the regular expression engine attempts to match in input text |
Text | Converting a value or field to a text string allows you to concatenate text strings or perform other text functions |
Value Aggregators | Perform calculations, usually based on input values, and returns a number result |
Note that the success of a conversion depends on the data itself and not only on the input type. For example, converting a Decimal to Boolean will only work if the decimal number is 1.0 or 0.0.
Boolean can be converted from a number, where 1 equals True and 0 equals False.
Function | Accepted input types |
---|---|
To Boolean | Text, Number, Decimal, Boolean |
To Date | Text, Date, DateTime |
To Date and Time | Text, DateTime |
To DateTime | 1) Text,Date 2) Text,Time (2 parameters) |
To Decimal | Text, Number, Decimal, Boolean |
To Number | Text, Number, Decimal, Boolean |
To Text | Text, Number, Decimal, Boolean |
To Time | Text, DateTime, Time |
To Time Duration from Milliseconds | Number |
An item is selected and then added to the canvas by using drag-and-drop.
Functions | Description | Example |
---|---|---|
To Boolean | Converts a value to a Boolean data type. | Input Value: "True" Result: True |
To Date and Time | Converts a value to a Date and Time data type. | Input Value: "2009/02/02 05:05:05 AM" Result: 2009/02/02 05:05:05 AM |
To Decimal | Converts a value to a Decimal Data type. | Input Value: "1" Result: 1.0 |
To Number | Converts a value to an Number data type. | Input Value: "1.0" Result: 1 |
To Text | Converts a value to a Text data type. | Example:
Input Value: 12345 Result: "12345" |
Date and Time functions perform operations on date and time input values and return a string, numeric, or date and time value. Values are converted to their native data types where possible.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
Add Days | Adds a specified number of days to a date | Date and Time: 01/01/2009 00:00:00 AM Days: 1 Result: 01/02/2009 00:00:00 AM |
Add Hours | Adds a specified number of hours to a date and time | Date and Time: 01/01/2009 00:00:00 AM Hours: 1 Result: 01/01/2009 01:00:00 AM |
Add Minutes | Adds a specified number of minutes to a date and time | Date and Time: 01/01/2009 00:00:00 AM Minutes: 1 Result: 01/01/2009 00:01:00 AM |
Add Seconds | Adds a specified number of seconds to a date and time | Date and Time: 01/01/2009 00:00:00 AM Seconds: 1 Result: 01/01/2009 00:00:01 AM |
Date/Time Difference |
Determines the difference between two dates, returning the difference in the specified interval with sub-intervals as decimal fractions. Intervals available: year, month, day, hour, minute, second and millisecond |
Interval: Day First Date: 01/01/2009 00:00:00 AM Second Date: 01/02/2010 00:00:00 AM Result: -366 |
Day | Gets the day of a given date | Date: 01/01/2009 00:00:00 AM Result: 1 |
Day Difference | Determines the number of days between two dates. Times are excluded from the calculation. |
Example 1: Example 2: |
End of Month | Gets the last day of a month | Date and Time: 01/01/2009 00:00:00 AM Result: 01/31/2009 11:59:59 PM |
End of Quarter | Gets the last day of a quarter | Date and Time: 01/01/2009 00:00:00 AM Result: 03/31/2009 11:59:59 PM |
End of Week | Gets the last day of a week | Date and Time: 01/01/2009 00:00:00 AM Result: 01/06/2009 11:59:59 PM |
End of Year | Gets the last day of a year | Date and Time: 01/01/2009 00:00:00 AM Result: 12/31/2009 11:59:59 PM |
Format Date and Time | Formats a date and time to a text representation using a specified date and time format | DateTime: 01/01/2009 00:00:00 AM Format: "dddd, dd MMMM yyyy" Result: "Thursday, 1 January 2009" |
Maximum | Gets the maximum date and time from a list of values | Values: {01/01/2009 00:00:00 AM, 01/02/2009 00:00:00 AM }
Result: 01/02/2009 00:00:00 AM |
Minimum | Gets the minimum date and time from a list of values | Values: {01/01/2009 00:00:00 AM, 01/02/2009 00:00:00 AM }
Result: 01/01/2009 00:00:00 AM |
Month | Gets the month of a given date as a number | Date: 01/01/2009 00:00:00 AM Result: 1 |
Now | Gets the current date and time | Result: 05/20/2009 03:34:27 PM |
Start of Month | Gets the first day of a month | Date and Time: 01/01/2009 00:00:00 AM Result: 01/01/2009 00:00:00 AM |
Start of Quarter | Gets the first day of a quarter | Date and Time: 01/01/2009 00:00:00 AM Result: 01/01/2009 00:00:00 AM |
Start of Week | Gets the first day of a week | Date and Time: 01/01/2009 00:00:00 AM Result: 12/28/2008 00:00:00 AM |
Start of Year | Gets the first day of a year | Year: 2009 Result: 01/01/2009 00:00:00 AM |
Subtract Days | Subtracts a specified amount of days from a date | Date and Time: 01/01/2009 00:00:00 AM Days: 1 Result: 12/31/2008 00:00:00 AM |
Subtract Hours | Subtracts a specified amount of hours from a date and time | Date and Time: 01/01/2009 00:00:00 AM Hours: 1 Result: 12/31/2008 00:23:00 AM |
Subtract Minutes | Subtracts a specified amount of minutes from a date and time | Date and Time: 01/01/2009 00:00:00 AM Minutes: 1 Result: 12/31/2008 00:59:00 AM |
Subtract Seconds | Subtracts a specified number of seconds from a date and time | Date and Time: 01/01/2009 00:00:00 AM Seconds: 1 Result: 12/31/2008 00:00:59 AM |
Today | Gets the current day | Result: 05/20/2009 00:00:00 AM |
Tomorrow | Return tomorrow's date | Result: 05/21/2009 00:00:00 AM |
Week Number | Gets the week number of the year of a specified date | Date: 01/01/2009 00:00:00 AM Result: 6 |
Weekday | Gets the name of the day of the week from a specified date | Date: 01/01/2009 00:00:00 AM Result: "Thursday" |
Year | Gets the year of a date | Date: 01/01/2009 00:00:00 AM Result: 2009 |
Yesterday | Returns yesterday's date | Result: 05/19/2009 00:00:00 AM |
The following table lists the date and time abbreviations recognized by the Format Date and Time function.
Date and Time | Abbreviations | Example |
---|---|---|
Year | y, yy, yyyy | 9, 09, 2009 |
Month | M, MM, MMM, MMMM | 2, 02, Feb, February |
Day | d, ddd, dddd | 21, Sat, Saturday |
Hour | h, hh, H, HH | 4, 04, 16, 16 |
Minute | m, mm | 1, 01 |
Second | s, ss | 1, 01 |
Millisecond | ffff | 9999 |
A.M. or P.M. | t, tt | P, PM |
The following table lists the standard date and time specifiers recognized by the Format Date and Time function.
Specifier | Pattern value (for en-US culture) |
---|---|
t | h:mm tt |
d | M/d/yyyy |
T | h:mm:ss tt |
D | dddd, MMMM dd, yyyy |
F | dddd, MMMM dd, yyyy h:mm:ss tt |
Constructing a Dynamic String
If you want to use parts of a date to construct a dynamic string, the following options may be considered:
- Use the separate expresssion values such as Day, Month, Year, etc and combine them as required
- Use a formatted date to construct a string closer to the required outcome
Examples:
- d Short date pattern (e.g.: 02/17/2007)
- D Long date pattern (e.g: Saturday, 17 February 2007)
- t Short time pattern (e.g.: 22:10)
- T Long time pattern (e.g.: 22:10:30)
- F Full date pattern (e.g.: Saturday, 17 February 2007 22:10:30)
- m (or M) Month and day pattern (e.g.: February 17)
- s Sortable date and time pattern (e.g.: 2007-02-17T22:10:30)
- y (or Y) Year and month pattern (e.g.: 2007 February)
- This can still be customized even further with extra expressions
If a Date value was used in a prior version of K2 smartforms as part of a string construction/function, the Date format will have to be changed if the previous Date format is still required. Values are now converted to their native data types where possible. In order to get the same result as previously when just using Date and not using the native data types, the starting point date will have to be wrapped in the To Text conversion function.
Using the To Text conversion function to convert the Current Date:
Current Date as reflected in current release of K2 smartforms:
Current Date as reflected after being converted:
List Aggregators perform calculations, usually based on input from a collection of values, and then returns a result.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
Average | Calculates the average of a collection of values | Input Values: { 1, 2, 3 } Result: 2 |
List Count | Calculates the total count of a collection of values | Input Values:{ 1, 2, 3 } Result: 3 |
Maximum | Gets the maximum value of a list of values | Values: { 1, 2, 3 } Expected When Empty: 0 Result: 3 |
Minimum | Gets the minimum value of a set of values | Values: { 1, 2, 3 } Expected When Empty: 0 Result: 1 |
Sum | Gets the sum of a set of values | Values: { 1, 2, 3 } Result: 6 |
Logical functions perform a logical operation or comparison on objects and expressions and returns a Boolean value.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
And | Perform an And operation on two Boolean values, returning true if both values are true, false if any value is false | Input Value: True Input Value: False Result: False |
Equals | Determines if two values or fields are equal | Result: True |
Greater Than |
Determines if the value on the left is greater than the value on the right | Result: True |
Greater Than Equals | Determines if the value on the left is greater than or equal to the value on the right | Result: True |
If | Returns one of two values (Boolean condition, True, False) based on a Boolean condition. Nested expressions are allowed up to 7. | Condition: True True Value: "Test string 1" False Value: "Test string 2" Result: "Test string 1" |
Less Than | Determines if the value on the left is less than the value on the right | Result: True |
Less Than Equals | Determines if the value on the left is less or equal to the value on the right | Result: True |
Not |
The Not function changes false to true and true to false. Returns a true value if the condition evaluates to false and a false value if the condition evaluates to true |
Condition: True Result: False |
Not Equals | Determines if two values or fields are not equal | Condition: True Result: False |
Or | Perform an Or operation on two Boolean values, returning true if one of the values is true, false if both values are false | Value: True Value: False Result: True |
Xor | Perform an Exclusive Or operation on two Boolean values, returning true if one and only one of the values is true | Value: True Value: True Result: False |
False | Gets the Boolean value of false | Result: False |
True | Gets the Boolean value of true | Result: True |
The True value and False value inputs need to return values of the same type. For example, dragging a SmartBox SmartObject Delete method into a True Value will be allowed by the If’s Input wizard, but it will not work at runtime because the Delete method does not return a value
Mathematical functions perform calculations, usually based on input values, and returns a result.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
Absolute | Gets the absolute value of a number | Input Value: -2 Result: 2 |
Format Number | Formats a number to a text representation using a specified numeric format specifier | Number: 0.111 Format: "C" Result: "$ 0.11" |
Power | Gets one value raised to the power of another | Base: 2 Power: 2 Result: 4 |
Random | Gets a random number less than or equal to a specified maximum value | Maximum: 2 Result: 1 |
Root | Gets the positive nth root of a positive number | Number: 100 Nth Root: 2 Result: 10 |
Round | Rounds a number up or down to a value with a specified precision | Value: 1.111 Digits: 1 Result: 1.1 |
Round Down | Rounds a value down | Value: 1.15 Digits: 1 Result: 1.1 |
Round Up | Rounds a value up | Value: 1.15 Digits: 1 Result: 1.2 |
Square | Gets the square of a number | Number: 2 Result: 4 |
Square Root | Gets the square root of a number | Number: 100 Result: 10 |
It is important to remember that the formatting of number strings/text using the Format Number expression function, is bound to the culture of the user when it comes to default precision specifiers and delimiters. Support includes but is not limited to the following:
Format Specifier | Name | Description | Examples |
---|---|---|---|
"C" or "c" | Currency | Result: A currency value. Supported by: All numeric types. Precision specifier: Number of decimal digits. Default precision specifier: Culture specific |
Format Number( 123.456, C) -> $123.46 [en-US] Format Number( 123.456, C) -> 123,46 € [fr-FR] Format Number( 123.456, C) -> ¥123 [ja-JP] Format Number( -123.456, C3) -> ($123.456) [en-US] Format Number( -123.456, C3) -> -123,456 € [fr-FR] Format Number( -123.456, C3) -> -¥123.456 [ja-JP] |
"E" or "e" | Exponential (scientific) | Result: Exponential notation. Supported by: All numeric types. Precision specifier: Number of decimal digits. Default precision specifier: 6. |
Format Number( 1052.0329112756 , E) -> 1.052033E+003 [en-US] Format Number( 1052.0329112756 , e) -> 1,052033e+003 [fr-FR] Format Number( -1052.0329112756 , e2) -> -1.05e+003 [en-US] Format Number( -1052.0329112756 , E2) -> -1,05E+003 [fr_FR] |
"F" or "f" | Fixed-point | Result: Integral and decimal digits with optional negative sign. Supported by: All numeric types. Precision specifier: Number of decimal digits. Default precision specifier: Culture specific |
Format Number ( 1234.567, F) -> 1234.57 [en-US] Format Number ( 1234.567, F) -> 1234,57 [de-DE] Format Number ( 1234, F1) -> 1234.0 [en-US] Format Number ( 1234, F1) -> 1234,0 [de-DE] Format Number ( -1234.56, F4) -> -1234.5600 [en-US] Format Number ( -1234.56, F4) -> -1234,5600 [de-DE] |
"N" or "n" | Number |
Result: Integral and decimal digits, group separators, and a decimal separator with optional negative sign. Supported by: All numeric types. Precision specifier: Desired number of decimal places. Default precision specifier: Culture specific |
Format Number ( 1234.567, N) -> 1,234.57 [en-US] Format Number ( 1234.567, N) -> 1 234,57 [ru-RU] Format Number ( 1234, N1) -> 1,234.0 [en-US] Format Number ( 1234, N1) -> 1 234,0 [ru-RU] Format Number ( -1234.56, N3) -> -1,234.560 [en-US] Format Number ( -1234.56, N3) -> -1 234,560 [ru-RU] |
"P" or "p" | Percent |
Result: Number multiplied by 100 and displayed with a percent symbol. Supported by: All numeric types. Precision specifier: Desired number of decimal places. Default precision specifier: Culture specific |
Format Number ( 1, P) -> 100.00 % [en-US] Format Number ( 1, P) -> 100,00 % [fr-FR] Format Number ( -0.39678, P1) -> -39.7 % [en-US] Format Number ( -0.39678, P1) -> -39,7 % [fr-FR] |
Operators perform calculations, usually based on input values, and returns a result.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
Divide | Divides two or more numbers or decimals | Input Value: 1.1 Result: 2 |
Minus | Subtracts two or more numbers or decimals |
Input Value: 3.2 Result: 1 |
Modulus | Returns the integer remainder of a division | Input Values: 9. 3 Result: 3 |
Multiply | Multiplies two expressions of numbers or decimals | Input Values: 2. 5 Result: 10 |
Plus | Adds two or more numbers or decimals | Number: 1.1. Result: 2 |
Left Bracket | In a group expression, this marks the beginning of a sub expression | Example: ( |
Right Bracket | In a group expression, this marks the end of a sub expression | Example: ) |
Regular Expressions provide a powerful, flexible, and efficient method for processing text. A regular expression is a pattern that the regular expression engine attempts to match to input text.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
Matches |
For doing a regular expression pattern match of a value. e.g. to check if the input value is a valid E-mail address. Parameters: Pattern(Text) Text Value(Text)
|
Example 1: Example 2: Example 3: Note that * will always return a match Example 4: Example 5: Matches words ending in 'es' Example 6: Matches words ending in 'es' |
Not Matches |
For doing a regular expression pattern match of a value to be excluded. e.g. to exclude all members whose names begin with 'A'. Parameters: Text Value(Text) Pattern(Text) |
Note that * will always return an empty result |
Text functions perform operations such as concatenations or insertions on text. Text-based operations are 1-based, meaning that the index of the first character in a string is 1.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
Concatenate | Joins two text strings into one text string | Values: { "Street", "Region", "State" } Separator: ";" Result: "Street;Region;State" |
Contains | Returns a true value if a substring is found within another string | Sequence: "12345" Text: "234" Result: True |
Ends with | Returns True if a given string ends with the specified substring | |
Find | Returns the index if the specified string is found within another string. Returns 0 if no match can be found | Substring: "12345" Text: "234" Result: 2 |
Hyperlink | Creates a hyperlink with a display name and URL | Display Name: "K2" URL: "http://www.k2.com" Result: "<a href=http://www.k2.com> K2</a>" |
Insert | Inserts a substring into a string at a specified position | Text: "Example" Substring: "00000" Position: 2 Result: "E00000xample" |
Is blank | Returns True if a string is empty | |
Is not blank | Returns True if a string is not empty | |
Join | Concatenates a list of text values or fields, delimiting each with a separator | Values: { "1", "2", "3" } Separator: ";" Result: "1;2;3" |
Left | Returns a subset of characters from the left side of a string | Text: "Test" Length: 1 Result: "T" |
Length | Returns the length of a string | Text: "Test" Result: 4 |
Mid | Returns a subset of characters from a string, starting at a specified index and continuing to the end of the string | Text: "Example" Start: 3 Result: "mple" |
Mid (Length) | Returns a subset of characters from a string, starting at a specified index and continuing to the specified Length | Text: "Example" Start: 3 Length: 3 Result: "mpl" |
Pad Left | Pads a string with a padding character on the left side up to a specified length | Source String: "Example" Pad Character: "#" Overall Length: 9 Result: "## Example " |
Pad Right | Pads a string with a padding character on the right side up to a specified length | Source String: "Example" Pad Character: "#" Overall Length: 9 Result: " Example #" |
Proper | Converts a string to proper case | Text: "the quick brown fox jumps over the lazy dog" Result: "The Quick Brown Fox Jumps Over The Lazy Dog" |
Replace | Replaces a substring within a string with a new substring | Text: "Ex000le" Find: "000" Replace: " amp " Result: "Example" |
Right | Returns characters from the right side of a string | Text: "Example" Length: 3 Result: "ple" |
Starts With | ||
To Lower | Converts a string to lower case | Text: "Example" Result: " example " |
To Upper | Converts a string to upper case | Text: "Example" Result: " EXAMPLE " |
Trim | Removes leading and trailing spaces and line breaks from a string | Text: " Example " Result: "Example" |
URL Encode | Encodes a URL string | URL: "http://local.com/test url.asmx" Result: "http%3a%2f%2flocal.com%2ftest+url.asmx" |
URL Decode | Decodes a URL string | URL: "http%3a%2f%2flocal.com%2ftest+url.asmx" Result: "http://local.com/test url.asmx" |
Empty String | Returns an empty string | Result: "Blank" |
It is important to note the following when testing for [is empty] and [is not empty]:
- When using View fields, numeric fields will never evaluate to "empty" as the default value is "0".
- When using controls, the values will evaluate as expected
Value Aggregators perform calculations, usually based on input values, and returns a number result.
An item is selected and then added to the canvas or SmartForms field part by clicking the Add button or by using drag-and-drop.
Functions | Description | Example |
---|---|---|
Average | Calculates the average of a collection of values | Input Values: { 1, 2, 3 } Result: 2 |
Maximum | Gets the maximum value of a list of values | Values: { 1, 2, 3 } Expected When Empty: 0 Result: 3 |
Minimum | Gets the minimum value of a set of values | Values: { 1, 2, 3 } Expected When Empty: 0 Result: 1 |
Sum | Gets the sum of a set of values | Values: { 1, 2, 3 } Result: 6 |
The following points need to be considered when applying Expressions on List and Editable List Views:
Applying Expressions on the Body Control
When applying an Expression on a body control (column) and the control is linked to a field (i.e. Property of the SmartObject), the related field will be updated per row once the Expression is evaluated. In this instance, the Expressions are evaluated when the list values are retrieved. Aggregations, for example, are calculated according to the related field information on the View and not necessarily the information as saved in the SmartObject. If there is already information in the SmartObject prior to applying the Expression on the View, then the values that are in the SmartObject and what is displayed on the View might differ.
If a user loads an Editable List with an Expression on the body control and then proceeds to save the values, all the modified records will be updated. This is especially useful for batch updates if a specific value relating to an Expression is changed and all records need updating.
It is important to note that the values should be saved on the View in order to update the values in the SmartObject
Using Expressions on the Add/Edit Item Row
An alternative is to apply the Expression on the Add/Edit Item row’s controls and not the body. This will ensure that only records that have manually been altered will be updated and that what is shown on the column is consistent with what is currently saved or will be saved. This will also not alter historical data unless the record itself was edited
For contextualized information, see the tutorial Using Expressions on an Editable List View
- It is important to note that when adding an Expression to a control, the data type of the control should match the expression input.
- It is important to note the following when testing for [is empty] and [is not empty]:
- When using View fields, numeric fields will never evaluate to "empty" as the default value is "0".
- When using controls, the values will evaluate as expected