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.