Functional users need a simple way to change wording of messages used throughout a KNS client application. Those messages may even be in a language foreign to that of the Foundation shipped messages (which are shipped in English). To facilitate ease of message changing, the KNS builds functionality on top of the standard Java message properties mechanism.
Once the Rice application has been generated, in src/main/resources, there will be a file named configurationServiceData.xml. That file lists a number of properties files which will be loaded:
<configuration>
<properties fileName="KR-ApplicationResources.properties" />
<properties fileName="KIM-ApplicationResources.properties" />
</configuration>Each of these files are listed relative to the src/main/resources directly. A property file simply relates messages to keys, like so (from the src/main/resources/KR-ApplicationResources.properties file):
document.question.cancel.text=Are you sure you want to cancel?
document.question.delete.text=Are you sure you want to delete?
document.question.deleteContext.text=Are you sure you want to delete [b]{0}[/b]?
document.question.disapprove.text=Are you sure you want to [b]disapprove[/b] this document?
document.question.saveBeforeClose.text=Would you like to save this document before you close it?This is the standard Java property file format, with keys (for instance, “document.question.cancel.text”) related to messages.
A message may also have escaped HTML tags and templated positions in the text for other Strings to be interpolated in. An example of this is found in the “document.question.deleteContext.text” message. The [b] and [/b] will be translated automatically to bold markup. The {0} will be replaced, if possible, by another String. An example of this will be covered below.
Rice Best Practices suggest that each module in the client application have a KeyConstants class which relates the names of user message keys to the String constants. org.kuali.rice.kns.util.RiceKeyConstants is the key constants class for the KNS.
Developers of client applications can also override pre-existing messages. Messages are loaded in the order listed in the configurationServiceData.xml file above, so client application specific files should be listed later in the file. Then, if the client application user message file redefines a user message using the same key, as so:
document.question.cancel.text=Canceling will lead to permanent disuse of this document. Are you completely certain this is the action you want to take?
users will be treated to the longer, more worried user message.
Retrieving the text for user messages can be done in a number of ways, based on the context the user message occurs in. The easiest use case is to get the text of the message directly through the default implementation of org.kuali.rice.kns.service.KualiConfigurationService. It has a method, getPropertyString, which, when handed the key to the message, returns the message text.
final String message = KNSServiceLocator.getKualiConfigurationService().getPropertyString(RiceKeyConstants.ERROR_DATE_TIME);
This will return the String “{0} is not a valid date/time.” Note that in this case, the String will not be interpolated; java.text.MessageFormat should be used to switch the {0} with an actual, useful String.
KualiConfigurationService also has a method, getPropertyAsBoolean, which translates the messages (regardless of case) of “true”, “yes”, “on”, or “1” as a boolean true and everything else as a false.
The vast majority of user messages are warnings when an error occurs. Thankfully, as was seen in the section on validations, the KNS handles error messages through the user messages system. For instance, in this code:
GlobalVariables.getErrorMap().putError("someProperty", ClientApplicationConstants.ERROR_MESSAGE, new String[] { businessObject.getSomeProperty().toString() });The error message displayed will be the one with the key held by ClientApplicationConstants.ERROR_MESSAGE, and the value of businessObject.getSomeProperty().toString() will be interpolated into the message.
The message must be in the user messages file loaded by KualiConfigurationService.
User messages are also available to the web layer of transactional documents and user screens through the standard Struts bean:message tag.
Messages to be loaded to struts are configured via the client application’s project configuration file, in the rice.struts.message.resources property, like so:
<param name="rice.struts.message.resources">KR-ApplicationResources,org.kuali.rice.kew.ApplicationResources,org.kuali.rice.ksb.messaging.ApplicationResources,KIM-ApplicationResources</param>
Again, the files are listed relative to the src/main/resources directory. There is nothing to prevent programmers from using one user message file for both the KualiConfigurationService messages and the Struts messages.
Once Struts has these messages loaded, it is easy to access them in a JSP page or jsp TAG file. Indeed, a great many of the delivered Rice tags make use of these message resources in order to display information, as seen from this sample from the standard kul:page tag:
<title><bean:message key="app.title" /> :: ${headerTitle}</title>In this case, the user message – set in KR-ApplicationResources.properties – with the property key of “app.title” will be displayed (which, by default as “Kuali”).
Developers curious about further information about the bean:message tag would be advised to read Struts’ documentation of the feature: http://struts.apache.org/1.2.x/userGuide/struts-bean.html.