| This model class encapsulates the full power of localization support within
the Wicket framework. It combines the flexible Wicket resource loading
mechanism with property expressions, property models and standard Java
MessageFormat substitutions. This combination should be able
to solve any dynamic localization requirement that a project has.
The model should be created with four parameters, which are described in
detail below:
- resourceKey - This is the most important parameter as it contains
the key that should be used to obtain resources from any string resource
loaders. This paramater is mandatory: a null value will throw an exception.
Typically it will contain an ordinary string such as
"label.username". To add extra power to the key functionality the
key may also contain a property expression which will be evaluated if the
model parameter (see below) is not null. This allows keys to be changed
dynamically as the application is running. For example, the key could be
"product.${product.id}" which prior to rendering will call
model.getObject().getProduct().getId() and substitute this value into the
resource key before is is passed to the loader.
- component - This parameter should be a component that the string
resource is relative to. In a simple application this will usually be the
Page on which the component resides. For reusable components/containers that
are packaged with their own string resource bundles it should be the actual
component/container rather than the page. For more information on this please
see
org.apache.wicket.resource.loader.ComponentStringResourceLoader .
The relative component may actually be
null when all resource
loading is to be done from a global resource loader. However, we recommend
that a relative component is still supplied even in these cases in order to
'future proof' your application with regards to changing resource loading
strategies.
- model - This parameter is mandatory if either the resourceKey,
the found string resource (see below) or any of the substitution parameters
(see below) contain property expressions. Where property expressions are
present they will all be evaluated relative to this model object. If there
are no property expressions present then this model parameter may be
null
- parameters - The parameters parameter allows an array of objects
to be passed for substitution on the found string resource (see below) using
a standard
java.text.MessageFormat object. Each parameter may
be an ordinary Object, in which case it will be processed by the standard
formatting rules associated with java.text.MessageFormat.
Alternatively, the parameter may be an instance of IModel in
which case the getObject() method will be applied prior to the
parameter being passed to the java.text.MessageFormat. This
allows such features dynamic parameters that are obtained using a
PropertyModel object or even nested string resource models.
As well as the supplied parameters, the found string resource can contain
formatting information. It may contain property expressions in which case
these are evaluated using the model object supplied when the string resource
model is created. The string resource may also contain
java.text.MessageFormat style markup for replacement of
parameters. Where a string resource contains both types of formatting
information then the property expression will be applied first.
Example 1
In its simplest form, the model can be used as follows:
public MyPage extends WebPage
{
public MyPage(final PageParameters parameters)
{
add(new Label("username", new StringResourceModel("label.username", this, null)));
}
}
Where the resource bundle for the page contains the entry
label.username=Username
Example 2
In this example, the resource key is selected based on the evaluation of a
property expression:
public MyPage extends WebPage
{
public MyPage(final PageParameters parameters)
{
WeatherStation ws = new WeatherStation();
add(new Label("weatherMessage",
new StringResourceModel("weather.${currentStatus}", this, new Model(ws)));
}
}
Which will call the WeatherStation.getCurrentStatus() method each time the
string resource model is used and where the resource bundle for the page
contains the entries:
weather.sunny=Don't forget sunscreen!
weather.raining=You might need an umberella
weather.snowing=Got your skis?
weather.overcast=Best take a coat to be safe
Example 3
In this example the found resource string contains a property expression that
is substituted via the model:
public MyPage extends WebPage
{
public MyPage(final PageParameters parameters)
{
WeatherStation ws = new WeatherStation();
add(new Label("weatherMessage",
new StringResourceModel("weather.message", this, new Model(ws)));
}
}
Where the resource bundle contains the entry
weather.message=Weather station reports that
the temperature is ${currentTemperature} ${units}
Example 4
In this example, the use of substitution parameters is employed to format a
quite complex message string. This is an example of the most complex and
powerful use of the string resource model:
public MyPage extends WebPage
{
public MyPage(final PageParameters parameters)
{
WeatherStation ws = new WeatherStation();
Model model = new Model(ws);
add(new Label("weatherMessage",
new StringResourceModel(
"weather.detail", this, model,
new Object[]
{
new Date(),
new PropertyModel(model, "currentStatus"),
new PropertyModel(model, "currentTemperature"),
new PropertyModel(model, "units")
}));
}
}
And where the resource bundle entry is:
weather.detail=The report for {0,date}, shows the temperature as {2,number,###.##} {3} \
and the weather to be {1}
author:
Chris Turner |
