Web Console Output Templating

Templating and Internationalization support of the Web Console is based on Java Resource Bundles loaded from the plugin bundles and is transparent to the plugin itself.

Basic Mechanism

All requests handled by web console plugins are wrapped by response wrapper, which installs a Writer filter if the response is a text/html response. This writer filter recognizes variables of the pattern ${name} and tries to replace that part of the output with another string:

  • If a variable of that name exists, the value of that variable is used. See Variable Resolution below.

  • Otherwise if a resource bundle provides a translated string for the name, that string is used. See Resource Bundles below.

  • Otherwise the name itself is just placed in the output.

Example

Consider the plugin bundle provides a localization for the default german locale de:

{panel:title=OSGI-INF/l10n/bundle_de.properties} Hello = Guten Tag {panel}

And the plugin defines a variable replacement and writes output with the following code:

WebConsoleUtil.getVariableResolver().put("world", "Schweiz");
response.getWriter().println("${Hello} ${world}");

The response sent to the client whose primary locale is de is then filtered to be:

Guten Tag Schweiz

Variable Resolution

Variable Resolution is based on a org.apache.felix.webconsole.VariableResolver object provided as a request attribute prior to calling the ServletResponse.getWriter() method. If no such resolver is provided in the request, an instance of the org.apache.felix.webconsole.DefaultVariableResolver is used and stored in the request. Replacing the VariableResolver after the getWriter() has been called has no effect for variable resolution. Variables may be added to the VariableResolver even after the getWriter() method has been called.

Resource Bundles

Resources for the Resource Bundles is provided by the Web Console bundle on the one hand and by the bundle providing the plugin on the other hand. Resources are identified inside a bundle with the Bundle-Localization manifest header as described in Section 3.10 Localization in the Core Specification.

This also means, that additional translations may be provided by fragment bundles.

During request processing the Locale of the request (ServletRequest.getLocale()) is used to identify the actual resources to use. From this information a ResourceBundle is constructed from a collection of the resources provided by the plugin bundle and the resources provided by the Web Console.

Web Console Localization

The Web Console contains a single localization file OSGI-INF/l10n/bundle.properties. Fragments attached to the Web Console bundle may provide translations for these resources. All plugins of the Web Console itself will use a ReosurceBundle, which is only based on the localization of the Web Console itself.

Using Templating

To use the described templating, the plugin developer may provide the following:

  1. Use templated strings in the generated response. Such templated strings will be replaced with variable values or localization strings as available.

  2. Set variable mappings in a VariableResolver. The simplest thing is to get a default VariableResolver calling the WebConsoleUtil.getVariableResolver(ServletRequest) method.

  3. Provide localization files and optionally set the Bundle-Localization header if the base file name is not the default OSGI-INF/l10n/bundle.