Set hint

See also: Validators

Actions – Abstract

The action Set hint sets a specific Hint (text) and an Indicator (color) for a suitable Target element.

images/download/attachments/189434485/image-2024-10-15_15-40-1-version-1-modificationdate-1728999601555-api-v2.png

The action Set hint sets a specific Hint (text) and an Indicator (color) for a suitable Target element.

►IMPORTANT◄ Characteristics set for Hint and Indicator are overridden at runtime by calculation errors, system-dependent hints (e.g. for required fields) or Validators configured for the element.

  • A Target element must be linked so that the action Set hint can be selected under Action type.

  • Whether a linked Target element effectively supports corresponding features depends on its type and state at runtime ('Active', 'Visible', etc.).

The Hint text can be determined by two different methods:

  • The globe icon can be used to set a reference to a localization entry, which is then resolved at runtime by Localization or Company specific localization adaptations to match the locale of the session.

  • Alternatively, texts or Calculation expression can be assigned directly. This must be done for each supported Locale, even if the content is identical for all locales.

The Indicator defines a color value for the text and frame from a predefined selection of signal colors, which can be adjusted by Styles if necessary:

Indicator

Appearance (Example: combobox with display type 'Options')

Styles property

(none)

images/download/attachments/189434485/image2020-7-10_17-5-26-version-1-modificationdate-1728982795391-api-v2.png

(none)

success

successColor

warn

warnColor

error

errorColor

invalid

primary

primaryColor

secondary

secondaryColor

  • The appearance is demonstrated here using a combobox with the display type 'Options', which offers the options for the Indicator for selection and, when selected, executes Set hint with the respective Indicator and its name as the Hint.

The options Set hint and Set indicator control whether the respective characteristic is to be changed at all by the action. If necessary, the characteristics (Hint and Indicator) can also be set independently of each other so that existing assignments are not overwritten.

  • Both options are selected by default.

  • Configuration details appear only for selected options.

  • Selecting an option (Set hint or Set indicator) without specifying any configuration details sets the 'default state' for the corresponding feature of the target element (no text or indicator color).

Examples

Simple use case example: 'Repdigit number'

If an integer calculation result (here 'Sum') produces a value that uses only identical numbers (except 0), a ' ►Repdigit number◄' hint should be displayed below the element.

Runtime example:

images/download/attachments/189434485/image2020-7-10_17-7-59-version-1-modificationdate-1728982795394-api-v2.png

Configuration:

images/download/attachments/189434485/image-2024-10-16_15-19-24-version-1-modificationdate-1729084764023-api-v2.png

For the Sum Text field', which is a calculation field that determines the sum to be checked, the behaviour shown on the left is configured:

  • The behaviour reacts to the Triggering event Changed with the Change types 'Value set by program', because the calculation field is read-only and not bound to a data field, so that value changes are only expected by the calculation.

  • The checking rule defines the Behaviour type Regular expression, for which a Regular expression is specified which executes the Actions on 'true' exactly when the calculated value consists exclusively of identical digits (>0) and contains at least two digits.

  • Under the Actions on 'true', the action Set hint is executed, which sets the text '►Repdigit number◄' as a Hint and assigns the Indicator 'primary' to set the default font color for the hint text and the frame of the element.

  • Under the Actions on 'false', the action Set hint without a Hint and Indicator ensures that 'normal' calculation results appear without special emphasis.

Demonstration example (see above)

The configuration used to create the screenshot in the 'Appearance' column above should serve as an example for the application.

The basis is a Combobox element that offers the following key values for selection via a data service for 'static values':

  • colornames.success

  • colornames.warn

  • colornames.error

  • colornames.invalid

  • colornames.primary

  • colornames.secondary

These values refer to the Resource name of the respective option for the Indicator that is localized in the lobsterui Bundle in the language management.

images/download/attachments/189434485/image-2024-10-16_15-24-2-version-1-modificationdate-1729085042413-api-v2.png

For the Combobox element, the behaviour shown on the left is configured to set the 'success' Indicator exactly when the user selects the 'success' option with the key value colornames.success:

  • The behaviour reacts to the Triggering event Changed with the Change type 'Exclusively by user'.

  • The Behaviour type Filled with is used to check whether the Input matches the key value colornames.success. Only then will the Actions on 'true' be executed.

  • Under the Actions on 'true' the action Set hint is executed, for which the Hint is calculated by printing the localization entry corresponding to the selection ($input) from the language administration. The syntax [Bundle name, Resource name] is used. The Indicator can only be defined statically. Here the option 'success' is selected.

►NOTE◄ According to the same pattern, a separate behaviour must be created for each additional type of Indicator. The Input parameter in the Behaviour type and the Indicator assigned in the action Set hint must be adjusted. The Hint, on the other hand, can be calculated appropriately from $input, since suitable key values have been stored.

Dynamic formatting of elements in a 'data series'

In a Repeatable element container, any set of integer 'Numbers' can be entered as a data series.

Each time a value is entered or changed, the following evaluations should be carried out and immediately visualized:

  • Below the data series, the arithmetic mean should be displayed as the 'Average' of the entered values.

  • Within the data series, the maximum value should be highlighted in green (with a 'Max' hint) and the minimum value in red (with a 'Min' hint).

  • Below average values (between 'Min' and 'Average') should be highlighted in orange (with a text hint indicating the average value).

images/download/attachments/189434485/image2020-7-10_17-14-18-version-1-modificationdate-1728982795408-api-v2.png

Configuration:

In principle, every change to a 'Number' in the data series can cause a new situation for the aggregation values 'Minimum', 'Maximum' and 'Average'. Therefore, the 'formatting' of all 'Number' elements must be updated whenever a single value is changed.

This requires a chain of behaviour with three stages:

images/download/attachments/189434485/image-2024-10-16_16-19-33-version-1-modificationdate-1729088373105-api-v2.png

The first stage of the chain is the behaviour shown on the left ('changed'), which is intended to trigger the update of all hints for elements of the data series if a single value is changed:

  • The behaviour reacts to the Triggering event Focus out and changed, which registers the change of a field value when leaving the field (and not just when a single key is pressed).

  • The Behaviour type Static (with the default value 'true') has been chosen so that the Actions on 'true' are definitely executed. Whether the field was filled or emptied is not relevant for the update.

  • Under the Actions on 'true', the Execute behaviour action calls another behaviour called 'changed', which is configured for the parent Repeatable element container and is described below.

images/download/attachments/189434485/image-2024-10-16_16-16-45-version-1-modificationdate-1729088204925-api-v2.png

As the second step in the chain, the 'changed' behaviour shown on the left triggers a check of all hint types for all instances of the contained 'Number' element for the parent Repeatable element container:

  • The behaviour is triggered exclusively by calling the detail level (see above) and does not require a separate Triggering event.

  • As in the calling behaviour, the Behaviour type Static (with the default value 'true') is used to perform the Actions on 'true' unconditionally.

  • Under the Actions on 'true', all actions relevant for the verification of hints must be called by the Execute behaviour action. These are all configured for the same Target element ('Number'). In the screenshot on the left, only the first action is expanded, which affects the behaviour named 'belowAverageHint' for the 'below average' values. Since the critical average value already exists in a separate calculation field (element ID#6), its value is passed as $input for the behaviour using the Value expression $el(6).
    ►IMPORTANT◄ The option For duplicates also must be set for all actions so that the hints are checked for all individual values of the entire data series.

images/download/attachments/189434485/image-2024-10-16_16-30-57-version-1-modificationdate-1729089057456-api-v2.png

images/download/attachments/189434485/image-2024-10-16_16-32-3-version-1-modificationdate-1729089123063-api-v2.png

The third step is to configure the behaviors shown on the left for the 'Number' Text field in the Repeatable element container, of which only ('belowAverageHint') will be discussed in more detail here. This behaviour controls whether the value of the executing element is marked as 'below average' or not.

  • The behaviour does not need a Triggering event of its own, because it is only triggered indirectly by the Execute behaviour action.

  • The Behaviour type Compare with checks whether the value of the executing element ('Number') is 'smaller' (Compare type) than the Calculation expression specified as the Compare source. Since the current 'average' is already given as a Value expression when the behaviour is called (see second stage above), this $input can be used here directly as a limit.

  • The Actions on 'true' are only executed for 'below average' individual values. This is where the Set hint action comes into play, which refers to the executing element as the Target element. In a calculation expression, the Hint parameter uses the syntax [Bundle name, Resource name] to refer to a localization entry, which is interpreted as 'average'. The average value ($input) is also displayed. The 'warn' label (orange) is selected as the Indicator.

  • Under Actions on 'false', the action Set hint without details for Hint and Indicator ensures that any highlighting is removed for 'not below average' numerical values.

  • The following called behaviours ('minimum Hint' and 'maximumHint') may override the hint status. They follow the same pattern, with different details for the Behaviour type Compare with and the action Set hint.

►NOTE◄ If several test criteria apply to the same 'Number', they are applied according to the order of the behaviour called in the second stage. For example, the 'minimumHint' almost always overrides the 'belowAverageHint', unless all numbers in the data series are identical. But then the 'minimum' is also equal to the 'maximum', so that the 'maximumHint' appears. If several individual values correspond to the minimum or maximum value, the relevant hint appears several times.