Show/hide expression
Description
If the expression evaluates to true, the control will be shown, otherwise the control will be hidden. The calculation is done in the Browser (i.e. on the 'client side') using Javascript.
Expression Syntax
Expressions must follow the following syntax rules:
- String literals are enclosed in either single quotes (') or double quotes ("). For example: 'MA', "Spain".
- Strings are case sensitive. E.g. "value" = "Value" evaluates to false.
- Logical operators are and, or, and not.
- True and false values are expressed as true and false. Note that these values are not quoted.
- Use only the functions listed in the Insert function list or JavaScript functions you have created.
- Use = to test for equality. For example: dialog.isDirty = false
- Expressions using logical fields must explicitly test the value of the field. For example: HasShipped = true, HasShipped = false
- Session variables can be used in an expression if and only if the session variable has been published to the client.
Inserting Functions
Functions can be used in the expression. The following built-in functions can be used in an expression:
- Function
- Description
- alltrim(C character)
Trims whitespace from the beginning and end of a string.
- at(C search_string, C string)
Returns the location where search_string occurs in a string. Does a case-sensitive comparison. If the search_string is not found, returns -1.
- at(C search_string, C string)
Returns the location where search_string occurs in a string. Does a case-insensitive comparison. If the search_string is not found, returns -1.
- crlf()
Inserts a CR-LF (newline) character.
- f_upper(C character)
Capitalizes the first letter of a string.
- formatNumber(N numeric, C format_string)
Converts a number to a formatted string. See Number toFormat() method for more information about creating the format.
- if(L condition, A result_true, A result_false)
Tests a logical expression. If the expression evaluates to true, returns result_true. If the expression evaluates to false, returns result_false.
- iif(L condition, A result_true, A result_false)
See if().
- left(C text, N number_of_characters)
Returns a substring of a string, starting with the leftmost character.
- len(C character)
Returns the number of characters in a string.
- lower(C character)
Converts a string to lowercase.
- ltrim(C character [, C characters_to_trim])
Removes leading matching characters in a string. Defaults to removing spaces (" "). You can specify what characters to trim using the second argument. See ltrim() for more information.
- occurs(C searchFor, C searchIn
Returns the number of times one string is found in another. Does a case-insensitive comparison.
- occursi(C searchFor, C searchIn)
Returns the number of times one string is found in another. Does a case-sensitive comparison.
- right(C character, N number_of_characters)
Returns a substring of a string, starting with the rightmost character.
- round(N number, N decimal_places)
Rounds a number to a specified number of decimal places.
- round_down(N number, N decimal_places)
Rounds a number down to the specified number of decimal places.
- round_up(N number, N decimal_places)
Rounds a number up to the specified number of decimal places.
- round_awayFromZero(N number, N decimal_places)
Rounds a number to the specified number of decimal places. If the number is greater than zero, the number is rounded up. If the number is less than zero, the number is rounded down.
- round_towardZero(N number, N decimal_places)
Rounds a number to the specified number of decimal places. If the number is greater than zero, the number is rounded down. If the number is less than zero, the number is rounded up.
- rtrim(C character [, C characters_to_trim])
Removes trailing matching characters in a string. Defaults to removing spaces (" "). You can specify what characters to trim using the second argument. See rtrim() for more information.
- str(N number [, N length [, N decimal_places [, C number_format]]])
Converts a number to a string. See str() for information about number formats.
- strtran(C character, C substring, C replacement)
Replaces each occurrence of a substring within a string with the specified value. Comparison is case-insensitive.
- substr(C character, N starting_position [, N number_of_characters])
Returns a substring portion of a string.
- time(C time_format, javascriptDateObject)
Converts a JavaScript date object to a string. See Date toFormat() method for more information about creating the format.
- toNumber(C character)
Converts a string to a number.
- upper(C character)
Converts a string to uppercase.
- val(C character)
Converts a string to a number. If the string contains leading non-numeric characters, returns 0.
- w_upper(C character)
Capitalizes the first character of each word in a string.
- word(C character, N word_number [, C separator])
Returns a specified word from a string. Default separator is a space (" "). You can specify the character(s) that define how to split the string into multiple words using the third argument. If the separator is a blank string (""), the default separator is used.
These functions can be inserted into an expression using the Insert Function button below the expression box.
Inserting Fields
The value of controls in the component as well as several system fields can be used in the expression. When the value of a control or system field changes, the expression is executed. Available fields include:
- Field Name
- Description
- Control Name
A control in the component. The value of the control is used in the expression. The data type of the value is the same data type specified in the control's Type property.
- data.rowNumber
Returns the current row number. Only applies to a Grid Component. UX Component always returns 1.
- dialog.isDirty
Value is true if any control in the UX component has been modified. Otherwise, value is false.
- dialog.isDataDirty
Value is true if any data bound control in the UX component has been modified. Otherwise, value is false.
- dialog.activePanelName
The name of the current active panel. Only applies if the UX Component has panels.
- dialog.activePanelId
The ID of the current active panel. Only applies if the UX Component has panels.
- dialog.isNewRecord
Value is true if the UX component is editing a new record (e.g. {dialog.object}.newRecord() has been called.) Otherwise, returns false.
- dialog.orientation
The device orientation. (e.g. "portrait" or "landscape")
- dialog.loggedInUserNameFriendly
The friendly name for the current logged in user.
- dialog.isLoggedIn
Value is true if the user is currently logged in. Otherwise, value is false.
- dialog.activeLayoutRule
The name of the current active Responsive Layout rule. If no Responsive Layout rules have been created, value is blank.
- dialog.hasDirtyLists
Value is true if a List in the UX Component has been modified. Otherwise, value is false.
Using JavaScript Functions
In addition to the functions listed in Insert Function dialog, you can also use your own JavaScript functions to create an expression.
JavaScript functions can be defined in the component's Javascript Functions section and referenced in the expression. For example, assume the following function has been defined to test whether the selected country is "United States":
var selectedUSA = function(country) { if (country === "United States of America") { return true; } return false; }
This function can be used in the client-side enable, show/hide, or readonly expression to control access to a dropdown list of States:
selectedUSA(Country) = true
Videos
Applying Security Client-Side
A common pattern in applications is to control the visibility (or enabled state) of certain controls on a page based on the 'role' that the user has in the application security framework. For example, a button might only be visible to users in the 'Administration' role.
Typically, the security settings are enforced server-side. But in some situations you might want to enforce the security rules on the client-side.
In this video we show how controls in a UX can be shown/hidden client-side based on the user's role.