Current locale
Value resolver – Abstract
Purpose: This returns the dynamic enumeration value of the Locale valid in the current session. For country-specific languages, the reference to the country can be selected or unselected.
The Current locale value resolver identifies the Locale applicable to the current session. The return value is a value from the relevant dynamic enumeration (Locale).
The Locale without country option defines whether the value resolver for country-specific distinct languages returns their enumeration value or the enumeration value of the global locale to which the applicable language refers.
►NOTE◄
The Current locale cannot be temporarily changed by the Run as event action, unlike other session features (e.g. User of session, Role of session and Company of session).
If a different temporary user is declared as User of session by a Run as event action, the user's 'language' selection does not apply as the Current locale executed in the changed context.
If a user changes the language via Change locale, this change only takes effect when the user logs in again as Current locale, although the change is immediately saved in the user account.
Configuration
The Locale without country option relates to the possibility of defining country-specific versions of a given global locale when defining languages in the dynamic enumeration Locale.
|
|
If the option is not checked (default), then the value resolver returns the dynamic enumeration value for the (country-specific, if applicable) locale in effect in the session, e.g. the language 'German (Switzerland)' (de_CH) or 'English (US)' (en_US). ►NOTE◄ The return value with this setting corresponds to the value in the locale property of a Print XML. |
|
|
If the option is checked, then the value resolver returns the dynamic enumeration value for the global locale that either applies directly to the session or is referred to by the logged-in country-specific language:
Special case:
|
Example
An association criteria (see Association criteria) is considered 'passed' if a country-specific locale is used in the current session.
Depending on this association criteria, an Image/Icon element can be displayed or hidden in a form that shows a graphic for the flag of the country 'coded' in the locale (if available).
Runtime example:
The image shows a section of an input form for shipment details, where the Current locale is visualized by flag icons in the header area in addition to a reference in the User of session.
In the session shown, the Locale 'English (US)' (en_US) is selected. The right flag symbol (here: USA) should only be visible if a country-specific locale is selected.
►NOTE◄ The left flag of the two 'flags' is defined by another section in the Client workflow described only partially below, based on Current locale ('without country'). However, it must be taken into account that the internal name of the Locale 'English' (en) does not correspond to an ISO 3611 alpha2 abbreviation. The output in the runtime example can be obtained by placing a copy of the flag graphic gb.png under the name en.png. Then this assignment (en=gb) can also be used in other contexts. Otherwise, this can be done by replacing the 'language name' en with the country code gb (or any other such as us or au) using Replace text when building the file name.
Configuration:
To detect the selection of a country-specific locale in the context of the current session, a custom association criteria is created and configured as follows:
|
An Entity property rule is used to compare the return values of the Current locale value resolver with and without selecting the Locale without country option:
|
|
A behaviour is added to the form that links the visibility for the Image/Icon element representing the 'country' referenced in the locale to the association criteria shown above:
|
|
Depending on the selected locale, the appropriate flags appear in the form header. In response to the Form data loaded trigger, another behaviour is called that uses a Client workflow to define a 'client object' that contains all the required 'header data' as field values.
The following section shows how to use the Current locale value resolver to extract the country identifier for the 'country' from the 'locale with country'.
►NOTE◄ In this case, it is assumed that when defining a country-specific language, it complies with the convention (see Locale) that the internal 'name' of the dynamic enumeration value links the flag for the global locale to the two-character ISO-3166-alpha2 country flag for the referenced country via an underscore ('_'). In the system-provided path ./assets/ammap/flags/, there is a png graphic file for most country flags that represents the corresponding 'flag'.
|
The Set value event action shown on the right assigns the relative file path for the Image/Icon element to the country field of the 'client object', which is displayed optionally for country-specific languages. The file path is built using a Concat strings value resolver:
|
|
Runtime example:
The image shows the section of a data input form for shipment details already shown at the beginning of this chapter.
However, the Locale 'German (Switzerland)' (de_CH) is selected in the session shown.
Further runtime example:
This image shows the appearance of the same shipment details input form after the following steps have been performed:
An additional supported language 'Klingon' has been created in the dynamic enumeration for Locale, which is assigned the internal 'name' (name) xt_KG.
A small image of the Klingon flag was uploaded with the File manager (relative file path: ./assets/ammap/flags/xt_kg.png).
For the user, 'Klingon' was selected via Change locale and the session was logged off and on again.
What happens at runtime?
The name xt_KG for the language 'Klingon' formally refers to a global locale with the randomly chosen name xt, which is not defined in the system.
Therefore, the language predefined by the system 'English' (en) is effective and also specified by the Current locale value resolver per Locale without country option (see the 'Locale' flag on the left in the image).
The Replace text value resolver in the Client workflow therefore attempts to eliminate the prefix en_ which is not found in xt_KG.
Therefore, the name xt_KG is assigned to the formal country-specific language 'Klingon' without any substitution, but in lowercase letters as the file name for the 'locale' flag (right in the image), whose file name should therefore be xt_kg.png.