Use of properties files for displayable text

Rich UI lets you define displayable text in an external file used at run time. Here are specific reasons for defining text in this way:

To override the runtime messages that are available, by default, for failed input validations or for incorrect formatting on input or output
To assign text to widgets without hard-coding that text in the Rich UI application
To display text in one or another language so that your code can be used more widely

Overriding validation or formatting messages

If you wish to override validation or formatting messages, do as follows:

Ensure that you are using the controller mechanism described in Rich UI validation and formatting.
Create a Rich UI properties library—a library part that has the stereotype RUIProperties, as described in RUIPropertiesLibrary stereotype. For an example that follows, the library name is myLibrary, and the library includes declarations of strings named entryForInputRequired and entryForOthers. Those variable names are case sensitive.
In a Rich UI handler or other code, specify the property validationPropertiesLibrary in a part definition or variable declaration, along with other validation and formatting properties. Here is an example declaration:
```
name STRING {inputRequired = yes,
             lowercase = yes,
             inputRequiredMsgKey = "entryForInputRequired",
             typeChkMsgKey = "entryForOthers",
             validationPropertiesLibrary=myLibrary };
```
The property validationPropertiesLibrary is used only when you are overriding validation and formatting messages.
Set up a properties file and include entries (name-value pairs) for which the names match the values of MsgKey properties. In the current example, the properties file includes the following entries:
```
entryForInputRequired=You must specify a value
entryForOthers=Your input is incorrect
someText=Not mentioned
```
The properties file is a text file. The entry names are case sensitive and are useful only if they match a string declaration in the Rich UI properties library.

Here are the implications of the current example:

An input-required error at run time results in display of the message "You must specify a value," which is identified by the name entryForInputRequired.
An input of an uppercase letter at run time also results in display of the message "Your input is incorrect." This outcome occurs because the value of the property typeChkMsgKey is used in response to a variety of errors; in this case, in response to a user input (the uppercase letter) that is disallowed by the lowercase property.

Here are the rules that explain the behavior just described:

For a given data field, you can override the default messages associated with each of the following properties:
- inputRequired
- minimumInput
- validValues
The override relies on one of the following three "MsgKey" properties: inputRequiredMsgKey, minimumInputMsgKey, and validValuesMsgKey.
Also for a given data field, you can specify a single override for errors related to any of the following properties:
- currency
- currencySymbol
- dateFormat
- fillCharacter
- isBoolean
- isDecimalDigit
- isHexDigit
- lowercase
- numericSeparator
- sign
- timeFormat
- timestampFormat
- uppercase
- zeroFormat
That single override also relies on the property typeChkMsgKey.

Assigning text to widgets

The Rich UI mechanism for displaying text from an external file always relies on using an Rich UI properties library, regardless of the purpose of the text. The following statements apply whenever you use the external file for reasons other than overriding a default message:

The rules for EGL library access apply. For example, assume that you have a Rich UI properties library named myLibrary and a button named myButton. Here is one way to assign text (in our example, the string "Not mentioned") to the button in your application:
```
myButton.text = myLibrary.someText;
```
Alternatively, you can reference myLibrary in a use statement, in which case you do not need to reference the library name in the assignment.
You can invoke the implicit library function getMessage to provide inserts to a properties-file entry.

You can also use the library function getMessage to provide inserts to a string inside your code. For details on using inserts, see RUIPropertiesLibrary stereotype.

Displaying text in one or another language

A displayable value comes from a properties file whose name has a root (for example, myLibrary) and includes a locale, which is a code that identifies a human language, For example, en is the locale that represents English, and the file name myLibrary-en refers to a properties file that provides English text.

Each file name has a root name and the extension .properties. The locale is indicated at the end of the root name, before the extension. Locales consist of one to three identifiers, the first preceded with a hyphen and the others (if any) preceded with an underscore. Each additional identifier after the first enables you to indicate a more specific language; in particular, you can specify the dialect, variety, or geographic location of a language.

The identifiers are the language code, country code, and variant code:

Among the language codes are en for English and es for Spanish. The language code is typically from the International Organization for Standardization (ISO) standard ISO-639.
The country code indicates a country where the dialect of the language is spoken. For example, the country code US indicates the United States, and GB indicates Great Britain. In this way, an American English file might be named myLibrary-en_US.properties, while a British English properties file might be named myLibrary-en_GB.properties. The country code is typically from the ISO standard ISO-3166.
The variant code defines a more specific dialect or variety of the language in the properties file. For example, you could use the variant codes A and B to distinguish between two different varieties of Norwegian spoken in Norway. These two files might be named myLibrary-no_NO_A.properties and myLibrary-no_NO_B.properties. Alternatively, you could define a standard type of Norwegian as the locale no_NO and define a variant as no_NO_B. The variant code is specific to a vendor or browser.

Deploying HTML files and the related properties files

You can deploy several HTML files for a given Rich UI application, one for each language that you are supporting. The user requests the HTML file for a specific locale by invoking the HTML file by name, perhaps as a result of clicking a hypertext link that you provide. For example, here is the HTML that invokes the German version of MyApplication.html from www.example.com, if a German version was deployed there:

   <a href="www.example.com/MyApplication-de.html">German version</a>

You store properties files in the WebContent/properties folder of your project. The root of the property file name (for example, myLibrary) must be the name specified in the propertiesFile property in the Rich UI properties library.

The EGL deployer ensures that the HTML file identifies a properties file for each Rich UI properties library that is referenced in your application. The following rules indicate how the file name for a given language is determined:

If the name of an available file exactly matches a locale, the name of that file is referenced.
Otherwise, the EGL deployer references a file that has a name with the closest match possible. For example, if the required locale is no_NO_B but the name of the only available file for Norwegian is myLibrary-no_NO.properties, the name of the available file is referenced. Moreover, if no Norwegian-language properties file is available, the name of the default properties file is referenced. The name of the default file has no locale; an example is myLibrary.properties.

Deployment fails if no properties file is available for a given Rich UI properties library. To avoid the failure, you might want to include a default properties file for each library.

Working with the EGL Deployment Descriptor editor

By working with the Rich UI Deployment tab in the EGL Deployment Descriptor editor, you prepare a Rich UI application for installation on an application server. The locales specified on that tab are derived from the Rich UI preferences, where you can add or remove entries:

You can add or remove an entry for a locale that is generally available in Rich UI; for example, en_US for American English. Whenever you select such a locale in the deployment descriptor, you include the following application components in the deployed output:
- A locale-specific properties file that you provide, if any; and
- Locale-specific runtime messages, which are system messages displayed in response to situations that are handled automatically by the EGL runtime code.
You can add or remove an entry that represents a new locale. Each new locale is available for only one purpose: to include a locale-specific properties file that you provide. However, when you define the locale, you also must specify a locale that is generally available in Rich UI. That generally available locale is used for only one purpose: to ensure that EGL system messages for the specified locale are available at run time.