You can use Rich UI to define displayable text in an external
file that is used at run time.
You might want to define text in this way for the following reasons:
- 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
To
override validation or formatting messages:
- Make sure that you are using the controller mechanism, as described
in "Rich UI validation and formatting."
- Create a Rich UI properties library, which is a library part that
has the RUIProperties stereotype, as described
in "RUIPropertiesLibrary stereotype." For the 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 property
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 };
Use
the validationPropertiesLibrary property
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 this 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.
Consider the implications of this example:
- If an input-required error occurs at run time, the message "You
must specify a value" is displayed; this message is identified by
the name entryForInputRequired.
- If an uppercase letter is input at run time, the message "Your
input is incorrect" is displayed. This outcome occurs because the
value of the typeChkMsgKey property is used
in response to a variety of errors; in this case, in response to a
user input (the uppercase letter) that is not allowed by the lowercase property.
These rules explain the behavior in the example:
- For a given data field, you can override the default messages
that are 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 that are 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 typeChkMsgKey property.
Assigning text to widgets
The Rich UI mechanism
to display text from an external file 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 this 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 getMessage implicit
library function to provide inserts to a properties-file entry.
You can also use the getMessage library
function to provide inserts to a string inside your code. For details
about using inserts, see "RUIPropertiesLibrary stereotype."
Displaying text in one or another language
You
can have several files, one for each language to support. The choice
of language is based on the user's browser setting.
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 .properties extension. 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. You
can use each additional identifier after the first 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 part of the Java™ specification.
- 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 part of the Java specification.
- 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.
Alternately, 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
not part of the Java specification.
Here are the access rules:
- If the application or browser requests a locale that matches a
locale in a file name, the displayable strings in the specified file
are available at run time.
- If the application or browser requests a locale that is more specific
than what is present in any of the file names, a more general locale
is used. For example, if the application requests the locale no_NO_B
but the only available Norwegian locale is no_NO, the locale no_NO
is used.
It is good programming practice to include a default properties
file. The default file is used if the user requests either no locale
or a locale that is more general than any that are specified in a
file name. The name of the default file has no locale; for example, myLibrary.properties.
Accessing an application that uses a specific locale
In
most cases, the locale that is used at run time depends on the browser
locale. However, the user can request a different locale by invoking
a locale-specific HTML file, perhaps as a result of clicking a hypertext
link that you provide. For example, here is HTML that invokes the
German version of MyApplication.html from www.example.com (assuming
that a German version was deployed there):
<a href="www.example.com/MyApplication-de.html">German version</a>
Deploying properties files
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.
By working with the Rich
UI Deployment wizard, you prepare a Rich UI application for installation
on one or another type of Web server. You can do either or both of
the following tasks:
- You can select from the list of generally available locales; for
example, en for English. Whenever you specify a locale from the list,
your selection includes the following application components in the
deployed output:
- A locale-specific properties file that you provide, if any; and
- Locale-specific runtime messages. In the Rich UI deployment wizard,
the phrase runtime messages refers to messages other
than those that can be in the properties file.
- In addition to selecting from a list of generally available locales,
you can specify new locales. Each new locale is available for only
one purpose— to include a locale-specific properties file that you
provide. If you identify a new locale, you also must specify one of
the generally available locales for use when the new locale is requested.
That generally available locale is used for only one purpose—to include
runtime messages other than those that can be in the properties file.