Expression language

Conditional expression language in Eximee allows defining conditional logic (e.g. visibility, enabled state, requiredness of fields) using JavaScript syntax extended with certain methods. Conditions are stored as expressions which the platform Eximee evaluates during application runtime. Below the syntax, available methods and attributes, as well as tools that facilitate creating and testing conditions, are described.

Conditional expressions in Eximee

• JavaScript in conditions: All conditions in the application template can be described with JavaScript expressions. This means that in the condition field we can use standard operators (==, !=, >, <, &&, ||, ! ) and JavaScript functions. The syntax allows defining, among others, negation (!condition ), conjunction (condition1 && condition2 ) and alternative conditions (condition1 || condition2).

• Access to component values: To retrieve current field values you should use the function getValue("ID_KOMPONENTU"), where COMPONENT_ID is the identifier of the field, session variable or component in the form. This is the recommended way to obtain a component value (other methods may cause performance issues). For example, calling getValue("PoleTekst1") will return the current text entered in the text field with ID = PoleTekst1.

• Access to other attributes: Besides the value, components also have other properties that can be referenced. For this the function getData("COMPONENT_ID", "ATTRIBUTE")is used, returning the value of the specified component attribute. For example getData("Checkbox1", "visible") will return information about the visibility of the field Checkbox1 (analogous to using isVisible("Checkbox1") ). The list of available attributes for particular component types is presented in the component documentation and partly discussed in the following section.

• Data types in conditions: All values retrieved from fields are treated as text (string) at the moment of condition evaluation. Therefore for numeric or logical comparisons you must convert data types yourself. You can use standard JavaScript functions such as parseInt() (conversion to integer) or parseFloat() (conversion to floating point). For boolean values remember that the string "true"/"false" should be compared as strings or converted to boolean type.

• Constants: Expressions may use textual constants (enclosed in quotes), numeric constants (written plainly) and boolean constants (true/false without quotes).

• Session variables in conditions: If you want to use a session variable (global for the application) in a condition, you can reference it via getValue("VARIABLE_NAME") . In some cases (e.g. inside complex components) the variable name must be prefixed with the @character. For example, the expression getValue("@zmienna1")=="Y" will check whether the session variable variable1 has the value "Y". Note: Predefined system variables (if present) may not require this prefix. However it is recommended to use @ before names of your own variables in complex contexts to avoid ambiguity.

• Composite conditions and dependencies: You can build complex expressions by combining several comparisons with logical operators. For example the expression getValue("Pole1") != "" && parseInt(getValue("Pole2")) > 100. The expression will return true only when Pole1 is not empty and at the same time the numeric value of Pole2 is greater than 100. When defining conditions that depend on other fields' values, remember to define listening – more on this later (the ListeningOn).

Component attributes

Each form component has a set of standard attributes describing its state. The most important common attributes are:

• value – current internal value of the component (e.g. text entered in a field, checkbox selection, selected list option).

• displayValue – the value displayed to the user. It often coincides with value , but for some fields it may differ (e.g. in a Combobox value this is the code/ID of the selected option, and displayValue is the label text).

• visible – information about the component's visibility ("true" or "false"). In conditions you can also use the function isVisible("ID") that serves a similar role.

• enabled – information about the component's enabled (editable) state, takes the value "true" when the field is active or "false" when it is disabled (non-editable). This attribute determines whether the user can interact with the field.

Other attributes may be specific to the component type. For example the dropdown list component (Combobox) provides attributes Each component should have a label ( (text of the selected option), description (additional description) or size (number of available options). The Statements component has a collection of items statementsItemControl representing individual statements. A detailed list of attributes is in the documentation for each component type.

Text field	value displayValue visible
Text area	value displayValue visible
Date	value displayValue visible
Date range	value displayValue visible
Plus minus	value displayValue visible
Formatted (and collapsible) content	value displayValue visible
check the alt value on the application	label - text of the selected value description - description of the selected value size - length of the value list
Account selection	value displayValue visible
Checkbox	moreInfoButtonClicked value displayValue visible
Radio	value displayValue visible
Radio group	value displayValue visible
Tile group	content - will return displayValue value displayValue visible
Tile	visible
Statements	statementsItemControl value displayValue visible
Slider	sliderValue value - (defaultValue) displayValue visible
Step Slider	sliderValue - value value - (defaultValue) displayValue visible
Double-range slider	value displayValue visible
has a globally set number of columns (shared across the entire page).	folded
Checkbox section	value displayValue visible
Repeatable section	folded
Contextual help	value displayValue visible
Product selection	variantId productId value displayValue visible
Picture card	value displayValue visible
Attachments	totalFilesSize fileNames externalIds value displayValue visible
Data confirmation component	wasEdited value displayValue visible
QR code scanner	value displayValue visible
Map	value displayValue visible
Specialized component	value displayValue visible
Frontend component	value displayValue visible

Referencing attributes in conditions: As mentioned, to read an attribute use getData(id, "attribute") . However in practice most conditions simply check the field value (value) or its visibility/enabled state. For convenience the Eximee platform provides dedicated API methods:

• getValue("ID") – returns the value of the component with the given ID (most commonly used).

• isVisible("ID") – returns information about the component's visibility (string "true"/"false").

(Some special components have additional methods, e.g. for handling groups of statements – described later.)

field is sufficient. If the text field AdresEmail has the identifier GesTextField5, then:

• getValue("GesTextField5") will return the entered email address,

• isVisible("GesTextField5") will return "true" if the field is visible or "false" if it has been hidden.

Special attributes – Statement component: For components of type Statements (list of consents/acceptances) functions are available to check whether a specific statement was selected. The method getStatementValue("COMPONENT_ID", "STATEMENT_MID") returns the value of a given statement (consent) on that component. In newer versions this function may be available under the name getStatementItem . Usage is as follows: e.g. getStatementValue("Zgody1", "newsletter") == "true" will return trueif on the component with ID Zgody1, the statement with identifier (MID) newsletter is accepted by the user.

Advanced condition editor

Eximee Designer provides an advanced condition editorthat facilitates creating, editing and verifying conditional expressions. This editor includes the following features:

• Syntax highlighting: JavaScript expression syntax is color-highlighted, which improves readability of complex conditions.

• Automatic suggestions: while editing a condition suggestions of available variables and form fields, as well as suggestions of Eximee API elements and commonly used JS methods, are displayed.

• Support for the prefix "js:": you do not need to manually type the prefix "js:" – the editor hides it in the view and automatically adds it in the source code when saving the condition. This way the user types only the actual expression and the platform takes care of the correct format.

Where the condition editor is used: The advanced editor is used in property fields of components such as: visibility condition, enabled (edit) condition and required condition . These three properties of each form component use the described editor and allow entering a formula that determines respectively whether the component is visible, active (unlocked) and whether it is required to fill in.

Syntax suggestions in the editor: In condition edit mode you can use suggestions by pressing the keys Ctrl + Space . This will display a list of available elements to use. Among the suggestions are, among others:

• Standard JavaScript functions and properties: parseInt(), parseFloat() , the property .length (text length) or size (list size), as well as other commonly used constructs (e.g. the keyword empty to check empty values).

• Eximee API: functions provided by the platform, such as getValue(), getData(), isVisible() or getStatementValue(), will appear on the suggestion list to remind about their availability.

• Identifiers of fields and variables: the editor automatically suggests MIDs of components available in the given form (along with their technical ID in parentheses) and the names of session variables used in the application. This allows quickly inserting a reference to a specific field without needing to remember its exact identifier.

Tip: In case of a large number of fields, to quickly find a suggestion for a specific component start typing its name (MID) – the list will be filtered. Suggestions help avoid typos in IDs and allow discovering available functions.

Examples of using conditional expressions

Below are several example conditional expressions with descriptions of their behavior. Each example shows the code fragment used in the condition definition and an explanation:

• parseInt(getValue("GesTextField3")) > 5

  – integer comparison: checks whether the numeric value entered in the text field GesTextField3 is greater than 5.

• parseFloat(getValue("GesTextField5")) < 200.001

  – floating-point comparison: checks whether the value from the text field GesTextField5 (e.g. an amount or a number with decimal places) is less than 200.001.

• getValue("GesCheckbox1") == "true"

  – logical comparison (equality): checks whether a field of type Checkbox with ID GesCheckbox1 is checked (has the value "true").

• getValue("GesCheckbox1") != "true"

  – logical comparison (inequality): checks whether the same checkbox no is checked (that is a value different from "true" – in practice "false" or no value).

• getValue("GesRadioGroup1") == "audi"

  – text comparison: checks whether in the Radio button group with ID GesRadioGroup1 the option with value "audi" was selected (e.g. one of car brands).

• !!getValue("nazwiskoZew")

  – double negation: checks whether a given value is not empty. Two exclamation marks convert the value to boolean – the expression will return truetrue if the variable or field nazwiskoZew has a non-empty value (e.g. the user entered a surname), and false false otherwise.

• !getValue("nazwiskoZew")

  – negation: checks whether the value is empty. It will return truetrue if the field/variable nazwiskoZew has no value (e.g. the user entered nothing), which in JavaScript is equivalent to a falsy value (e.g. an empty string getStatementItem("GesStatementPopup1", "oswiadczenie1") == "true" "").

• – condition for a component of type

  : checks whether on the component with ID StatementsGesStatementPopup1 the statement with identifier (MID) oswiadczenie1 was selected (i.e. whether the user accepted that statement). getStatementItem("@GesStatementFlat5", "zdrowotne") == "false"

• – a similar condition for

  inside a complex component: checks whether the statement Statements zdrowotne in the component with ID GesStatementFlat5 (embedded in a complex component, hence the prefix ) was not @) selected by the user. !!!(getValue("@GesTextField13") || getValue("@GesTextField8"))

• – example of a requiredness condition: triple negation before the parenthesized expression checks whether

  both text fields GesTextField13 GesTextField8 and are empty. Inside the parentheses the operator returns the first non-empty value (or empty if both values are empty). Applying || inverts the result, and ! converts it to boolean. The overall effect is !! both fields are empty true only when (then e.g. another field becomes required). When any field has a value, the expression will return false (meaning the requiredness condition is not met, so e.g. the given field does not have to be required). false getValue("@GesCombobox1") != 2 && getValue("@GesCombobox1") > 0

• – complex condition for a selection list (Combobox): checks two things at once – whether the value chosen in the Combobox field

  GesCombobox1 is not equal to 2 and whether it is greater than 0 . Such a condition could be used for example to verify a selection other than the default (assuming the valuemeans no selection, and 0 is some excluded option). 2 isVisible("@GesTextField1") == "true"

• – visibility state check: the condition will return

  true if the component with ID trueis currently visible (e.g. another condition did not hide it). This can be used to make behavior dependent on whether another field is on the screen. GesTextField1 getValue("GesTextField5").length == 10

• – text length check: the condition returns

  true if exactly 10 characters were entered in the text field trueThis can be used e.g. to validate format (check if a number has the required length). GesTextField5 (In the above examples sample identifiers generated by the system were used, such as

. In a real project it is recommended to assign readable business identifiers (MIDs) to fields which makes later referencing them in conditions easier) GesTextField5Conditional expressions in complex and business components

Inside a complex/business component, to unambiguously indicate a variable/field from that component, prefix the name with the

• getValue("@nazwaZmiennej") @:

  • getValue("@walutaDomyślna") == "USD"

  • field is sufficient. Why? during condition evaluation.

  • expands into the component identifier, e.g. @ getValue("GesComplexComponent1.nazwaZmiennej") getValue("@walutaDomyślna") == "USD" GesCheckbox11.ariaLabel which eliminates name collisions with the main form on which the component is placed.When a name collision exists (the same variable/field in the main application and in the component) or you want to be precise — use

• even if the condition works without it. @ Good practice: in complex/business components always prefix variable/field names with the

• character in conditional expressions, unless you intentionally want to reference a variable/field from the main form - then omit @ Note: system-predefined variables are placed on the main form, therefore we reference them directly by name omitting the @

• Main form: @.

Examples:

• getValue("walutaDomyślna") == "USD" Inside a component (precisely to a variable from that component):.

• FAQ – Frequently Asked Questions Why? during condition evaluation.

How to set a component to display conditionally (e.g. after checking a checkbox)?

Use the property Visibility condition (visibleCondition) available in the component properties panel. In the condition field enter an expression that should return when the component should be visible. For example: if the field true SekcjaDodatkowa should show after checking the checkbox PokazSekcje (id=GesCheckbox7) then set the visibility condition:getValue("GesCheckbox7") == "true" . When the user checks that checkbox the condition will be met andwill become visible. should show after checking the checkbox Condition does not refresh after another field changes – what am I doing wrong?

Probably the listening setting is missing. For a component to react to changes in the value of another field used in the expression, you must set for it the attribute ListeningOn (Listening) pointing to that field. In other words the component with the condition must "listen" to the component on which the condition depends. In Eximee Designer you do this in the Interactions properties section of the component – add the dependent field's identifier to the Listening list. After correctly setting listening, a change of one field's value will automatically re-evaluate the condition in the other field.

How to check in a condition whether a field is empty or filled? There are several ways to do this. The simplest is to use the fact that an empty string in JavaScript is a value (e.g. an empty string (falsy) value. For example: the expression !getValue("PoleX") will return truewill be true when PoleX is empty (negating an empty string gives true). Conversely, the expression !!getValue("PoleX") will return truewill be true only if PoleX it has some value (double negation converts the value to boolean preserving its "truthiness"). Alternatively you can compare directly to an empty string: getValue("PoleX") == "" (empty) or getValue("PoleX") != "" (filled).

Do I need to add the prefix js:? in a condition expression? "js:" No. In the Eximee Designer editor we enter only the condition expression itself, without any prefixes. The prefix is added automatically in the source code and is used internally to mark that the condition should be interpreted as JavaScript. If you inspect the application's XML configuration you will seecondition="js:...your_expression..."

but in the Designer interface you do not need (and should not) write this manually. How to define a condition that is always met (always true)? If we want an action/condition to be always truetrue (e.g. to make an element always visible or some action always executed), we can enter the constant true as the expression. In practice it is enough to enter the value . The editor will add the appropriate prefix and the condition will be treated as always met. Alternatively, you can enter js:true false in the raw configuration – the effect will be the same. Similarly, an always-false condition can be obtained by entering

(which will cause e.g. the given component to never be visible by itself). Can I use any JavaScript functions in conditions? Basic JavaScript functions and operators are supported, especially those suggested by the editor (like, parseIntparseFloat getValue, getData, logical operators, etc.). Keep in mind that the condition is executed in the user's browser context, so it should not contain calls that may be undefined or unavailable. A good practice is to limit yourself to simple operations and to use the API provided by the Eximee platform (e.g.