Use of properties files for displayable text

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:

Overriding validation or formatting messages

To override validation or formatting messages:
  1. Make sure that you are using the controller mechanism, as described in "Rich UI validation and formatting."
  2. 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.
  3. 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.

  4. 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.

Feedback