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 type that has the
stereotype RUIProperties. Details are here: 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 validationPropertiesLibrary field
in a type definition or variable declaration, along with other validation
and formatting fields. Here is an example declaration:
name STRING {inputRequired = yes,
lowercase = yes,
inputRequiredMsgKey = "entryForInputRequired",
typeChkMsgKey = "entryForOthers",
validationPropertiesLibrary=myLibrary };
The validationPropertiesLibrary field
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 fields. 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 typeChkMsgKey field 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 fields:
- inputRequired
- minimumInput
- validValues
The override relies on one of the following three "MsgKey"
fields: inputRequiredMsgKey, minimumInputMsgKey, and validValuesMsgKey.
- Also for a given data field, you can specify a single override
for errors related to any of the following fields:
- currency
- currencySymbol
- dateFormat
- fillCharacter
- isBoolean
- isDecimalDigit
- isHexDigit
- lowercase
- numericSeparator
- sign
- timeFormat
- timestampFormat
- uppercase
- zeroFormat
That single override also relies on the typeChkMsgKey field.
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.
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 annotation
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.