General Properties Resources

The general properties path refers to a localized text property stored in a Java properties file on the classpath. The prefix path is extended with two further steps: the first step is the resource identifier for the properties file; the second step is the property key. Java properties files can be added to any package within the javasource folder of an application component, the same location used for the renderer plug-in classes.

The resource identifier to use to locate the properties should correspond to the location of the properties resource on the classpath. For example, if the properties file X.properties is placed in a Java package sample.resources, after building the application it will be stored in a JAR file on the classpath as the file /sample/resources/X.properties. Then the resource name will the be sample.resources.X. See the Javadoc documentation for the standard java.util.ResourceBundle API for more information on the naming convention and mechanism used to locate the properties for properties files in more than one locale.

The example below shows how a renderer plug-in may retrieve the value of the age property from the PersonDetails.properties file in the sample Java package. The code is defined in the context of the render method. The localized text value is stored in the ageLabel variable ready to be added to the appropriate point of the HTML document.

Figure 1. Accessing General Properties

Path agePath = ClientPaths.GENERAL_RESOURCES_PATH
    .extendPath("sample.PersonDetails", "age");
String ageLabel = context.getDataAccessor().get(agePath);

Only the get method is supported when accessing general properties resources. If no such property can be found, the get method will throw a DataAccessException.

Path objects are immutable; they are similar to java.lang.String objects in that respect, or to the component objects described in Overview of the Renderer Component Model. Operations such as extendPath, do not modify the path, they return a new path (see the Javadoc for details). Therefore, if several properties are required from the same resource, a path can be created that includes the resource identifier step and then that path can be extended again and again to retrieve individual property values. This is shown in the example below, where the value of the dtlsPath variable is never changed by calls to extendPath after it has been initialized.

Figure 2. Accessing Multiple General Properties

Path dtlsPath = ClientPaths.GENERAL_RESOURCES_PATH
    .extendPath("sample.PersonDetails");

DataAccessor da = context.getDataAccessor();

String ageLabel = da.get(dtlsPath.extendPath("age"));
String dobLabel = da.get(dtlsPath.extendPath("date.of.birth"));
String nameLabel = da.get(dtlsPath.extendPath("name"));
String addressLabel = da.get(dtlsPath.extendPath("address"));

Where properties files are supplied for several locales, the properties file name will differ, but the path used to reference the property should not include the locale. For example, if the properties files PersonDetails_en_US.properties and PersonDetails_es.properties are defined in the sample package folder, the above code will not change; the resource identifier remains sample.PersonDetails. The DataAccessor will automatically determine the locale of the active user and select the correct properties resource. The usual locale fall-back sequence, described by the java.util.ResourceBundle API, is followed.