Allgemein

One of the new features released with the latest version of Catapult (currently 0.110) is the ability to define locale specific templates.

In older versions a request to a URL /page.html always renders that same page. Also <inc:partial /> always includes the same file.

Now you can provide different pages and different templates for different locales. The naming of the files is based on the naming conventions for ResourceBundles in Java. This means you can additionally create

• page_language.html (e.g. page_de.html, page_en.html, page_es.html, …)
• page_language_country.html (e.g. page_de_DE.html, page_de_CH.html, page_fr_CH.html, …)
• page_language_country_variant.html (e.g. page_de_DE_variant.html)
• page_language__variant.html
• page___variant.html

The language part is a two letter lower case language code and the country part a two letter upper case country code. The variant may be any alphanumeric string.

Catapult will render the most specific page or template, depending on the current locale.

Moreover, more (locale) specific templates may inherit from more general templates of the same base name. For example: let’s assume you have created the four files page.html, page_de.html, page_de_CH.html, and page_fr.html. Then the three locale specific files (for de, de_CH, and fr) might refer to a template of the same base name by using

<dir:page xmlns:dir="/path">
  ...
</dir:page>

Catapult then determines the next most specific base, which means in our example that both page_de.html and page_fr.html inherit from page.html whereas page_de_DE.html inherits from page_de.html (which in turn as aforesaid inherits from page.html). Using this mechanism you can override specific parts or enhance a base template for certain locales.

However, for simple internationalization, the i18n features of Catapult should be sufficient. So don’t duplicate HTML files just to insert static text in different languages if the overall structure remains the same.

Multitenancy

If you have to implement a web application that supports multiple tenants, the locale specific template feature can be used to implement tenant-dependent pages and templates. The trick is to use the variant of the locale to identify the current tenant. Providing such a special locale is usually done in a servlet filter and out of scope for Catapult. The tenant specific pages then should be named page.html, page___tenant1.html, page___tenant2.html and so on (note: three underscores between page and the tenant name).

So, by using the mechanism of putting the tenant as variant into the locale you not only can display different texts for different tenants but also completely different HTML.

A new version of Catapult is available from our maven repository.

A major change in this release affects the treatment of parameters that can be passed to templates (either by using XML attributes in the template element or by providing model attributes from a controller). In prior Catapult versions accessing an unassigned variable (or missing parameter) simply evaluates to null.

This was often used in fallback constructs like this to define a default value:

p:var="#{#var ?: 42}

The value of the variable var is either its old value, if it is not null, or it is the default value (42 in this case).

This won’t work anymore in Catapult 0.99. Accessing an undeclared variable will throw an exception during the rendering of the page. The reason for this change is that typos in variable names will be detected immediately (see also issue 22).

The new way to define default values for parameters is by using the new namespace http://www.catapultframework.org/xml/default-param:

xmlns:d="http://www.catapultframework.org/xml/default-param"
d:var="#{42}"

Either the variable var has been passed to the template explicitely or its value is 42.

For backwards compatibility and to facilitate the migration to the new version, the Catapult property catapult.renderer.ignore-undeclared-variables may be set to true. In this case unassigned variables will again evaluate to null. However, an error will be logged so you can detect such usages.

As always, the full changelog for version 0.99 is available in our code repository.