HST Dynamic Resource Bundles Support

Bloomreach Content's delivery tier (HST) supports dynamic management of Java resource bundles stored in the repository. HST integrates with JSTL tag libraries, allowing you to configure resource bundles per virtual host group, virtual host, mount, or sitemap item. You can access these resource bundles using standard JSTL tag libraries and APIs, regardless of whether they are stored in the repository or as Java classpath resources.

Introduction

HST enables dynamic management of Java resource bundles in the repository and integrates with JSTL tag libraries.

You can assign multiple resource bundle IDs—separated by commas or whitespace—to each sitemap item, mount, virtual host, or virtual host group configuration. The <hst:setBundle/> tag also accepts multiple resource bundle IDs as the basename attribute value, separated by commas or whitespace.

When creating localized web page templates using JSTL tag libraries, you might use the <fmt:setBundle/> and <fmt:message/> tags as shown below:

<fmt:setBundle basename="org.example.app.Messages" />
<fmt:message key="greeting.one" />

This approach is functional, but it has limitations:

  • Resource bundle files are loaded from the classpath (for example, classpath:org/example/app/Messages.properties, classpath:org/example/app/Messages_en.properties, classpath:org/example/app/Messages_en_US.properties). You cannot update these bundles at runtime; changes require redeployment and a container restart.
  • You must include the <fmt:setBundle/> tag in every template page. Changing the basename attribute requires editing the template and, for JSP templates, redeploying the application and restarting the container.
  • The standard tag does not support multiple resource bundles as fallbacks, where the first bundle has the highest priority.

When you manage resource bundle documents in the repository, changes are applied immediately at runtime. No redeployment or restart is required.

Resource Bundle Documents

You can create and manage resource bundle documents in the CMS using the Resource Bundle Editor plugin. This plugin is included by default when you create a project using the Maven archetype.

The HST Resource Bundle feature is context-aware based on preview or live mode. When you access a site in preview mode, resource bundles are loaded from the preview variants of resource bundle documents. In live mode, resource bundles are loaded from the live variants.

Hint: For details on how resource bundle documents are stored, see Resource Bundle Node Structure.

Resource Bundle Configurations in HST

You can configure the basename value of the default resource bundle for each template, virtual host group, virtual host, mount, or sitemap item.

The following CND snippets show the configuration nodes:

[hst:virtualhosts] > nt:base, mix:referenceable, mix:versionable
// <SNIP>// single resource bundle base name or (comma or white space separated) multiple resource bundle names.
- hst:defaultresourcebundleid (string)
// <SNIP>

[hst:virtualhost] > nt:base, mix:referenceable
// <SNIP>
// single resource bundle base name or (comma or white space separated) multiple resource bundle names.
- hst:defaultresourcebundleid (string)
// <SNIP>

[hst:mount] > nt:base, mix:referenceable
// <SNIP>
// single resource bundle base name or (comma or white space separated) multiple resource bundle names.
- hst:defaultresourcebundleid (string)
// <SNIP>

[hst:sitemapitem] > nt:base, mix:referenceable
// <SNIP>
// single resource bundle base name or (comma or white space separated) multiple resource bundle names.
- hst:resourcebundleid (string)
// <SNIP>

You can configure either the hst:resourcebundleid or hst:defaultresourcebundleid property. Both properties accept multiple basename values, separated by commas or whitespace.

For example, setting the hst:resourcebundleid property to org.example.app.Messages on a sitemap item has the same effect as including <fmt:setBundle basename="org.example.app.Messages"/> in every template executed through that sitemap item. This removes the need to manage the <fmt:setBundle/> tag in templates and eliminates the need for redeployment. The HST container automatically sets the default resource bundle for all templates. To override the default, define <fmt:setBundle/> in your template and specify a different basename.

You can also assign multiple resource bundle basenames to the hst:resourcebundleid and hst:defaultresourcebundleid properties. This is useful, for example, when using channel inheritance to override keys in a specific channel that are defined in a shared resource bundle. Internally, if you set org.example.app.Messages1, org.example.app.Messages2 as the basename value, HST creates a CompositeResourceBundle. It searches org.example.app.Messages1 first, then org.example.app.Messages2 if the key is not found in the first bundle. Separate each basename with a comma or whitespace.

If you do not add a resource bundle document for a given basename in the repository, the HST container uses the default Java classpath resources for that basename (for example, classpath:org/example/app/Messages.properties, etc.).

The hst:defaultresourcebundleid and hst:resourcebundleid property values are inherited by descendant configuration nodes. If you do not specify hst:resourcebundleid on a sitemap item, HST uses the value from the parent sitemap item. If no hst:resourcebundleid is set on sitemap items, HST checks the hst:defaultresourcebundleid property on the mount. Similarly, values set on a virtual host group or virtual host are inherited by child nodes.

Summary:

  • You can set one or more default resource bundle IDs (the basename values) on sitemap items, mounts, virtual hosts, or virtual host group configuration nodes. This sets the default resource bundle for request processing. You do not need to use the <fmt:setBundle/> tag to specify the default bundle.
  • If you do not manage a resource bundle document in the repository, resources are loaded from the classpath. For example, if the default resource bundle ID is org.example.app.Messages and no corresponding document exists in the repository, HST uses classpath resources such as classpath:org/example/app/Messages.properties.
  • Default resource bundle configuration is inherited: from parent to child sitemap item, from mount to sitemap item, from virtual host to mount, and from virtual host group to virtual host.
  • You can set multiple resource bundle IDs (for example, org.example.app.Messages1, org.example.app.Messages2). The lookup order matches the order of the IDs.

Hint: Starting with brXM 12.1, you can define a channel's default resource bundle ID as a channel parameter. End users can configure this through the channel's settings in the Experience manager. For details, see Make a Channel's Default Resource Bundle IDs Configurable in the Experience Manager.

HST Tag Libraries Supporting Dynamic Resource Bundles

HST tag libraries provide an extended setBundle tag, allowing you to use resource bundle documents from the repository if available. The <hst:setBundle/> tag inherits all functionality from the standard <fmt:setBundle/> tag and adds the ability to look up resource bundles in the repository.

If you use a single default resource bundle for a sitemap item, mount, virtual host, or virtual host group, you typically do not need to use <hst:setBundle/>. The default resource bundle is set automatically based on the repository configuration. To override the resource bundle in a template and use repository-managed bundles instead of classpath resources, use the <hst:setBundle/> tag.

If a resource key is not found in the bundle defined by <hst:setBundle/>, the tag falls back to the resource bundle hierarchy defined by the relevant sitemap item, mount, virtual host, or virtual host group. You can disable this fallback by setting the fallbackToDefaultLocalizationContext attribute to false.

Note: Within a single resource bundle, fallback to the default locale value when a key's value is an empty string for a specific locale is not supported. Provide a value for all locales unless an empty string is intentional.

The <hst:setBundle/> tag is defined as follows:

<tag>
  <description>
    Loads a resource bundle and stores it in the named scoped variable or
    the bundle configuration variable
  </description>
  <name>setBundle</name>
  <tag-class>org.hippoecm.hst.tag.SetHstBundleTag</tag-class>
  <body-content>empty</body-content>
  <attribute>
    <description>
      Resource bundle base name. This is the bundle's fully-qualified resource
      name, which has the same form as a fully-qualified class name, that is,
      it uses "." as the package component separator and does not have any file
      type (such as ".class" or ".properties") suffix.
    </description>
    <name>basename</name>
    <required>true</required>
    <rtexprvalue>true</rtexprvalue>
  </attribute>
  <attribute>
    <description>
      Flag whether or not to fall back to the Java standard resource bundles
      if no resource bundle is found from the HST ResourceBundleRegistry by the
      basename.
      The default value is true.
    </description>
    <name>fallbackToJavaResourceBundle</name>
    <required>false</required>
    <rtexprvalue>true</rtexprvalue>
  </attribute>
  <attribute>
    <description>
      Flag whether or not to fall back to the default localization context, which might
      have been set in the virtual hosts, vitual host, mount or sitemap item level.
      The default value is true.
     </description>
    <name>fallbackToDefaultLocalizationContext</name>
    <required>false</required>
    <rtexprvalue>true</rtexprvalue>
  </attribute>
  <attribute>
    <description>
      Name of the exported scoped variable which stores the i18n localization
      context of type javax.servlet.jsp.jstl.fmt.LocalizationContext.
    </description>
    <name>var</name>
    <required>false</required>
    <rtexprvalue>false</rtexprvalue>
  </attribute>
  <attribute>
    <description>
      Scope of var or the localization context configuration variable.
    </description>
    <name>scope</name>
    <required>false</required>
    <rtexprvalue>false</rtexprvalue>
  </attribute>
</tag>

The <hst:setBundle/> tag works similarly to <fmt:setBundle/>, but provides additional capabilities:

  • Set the basename attribute to retrieve the resource bundle from either a repository document or a classpath file. By default, the repository is searched first, then the classpath.
  • Specify multiple resource bundle IDs (comma or whitespace separated) in the basename attribute. Bundles are searched in order until a key is found.
  • Use the fallbackToJavaResourceBundle attribute to control whether the classpath is searched if a value is not found in the repository. The default is true.
  • Use the fallbackToDefaultLocalizationContext attribute to control whether resource bundles configured on the sitemap item, mount, virtual host, or virtual host group are searched if a value is not found in the specified bundle. The default is true.

You can use <hst:setBundle/> instead of <fmt:setBundle/> in any situation. If you have resource bundle documents associated with the specified basenames, <hst:setBundle/> enables use of repository-managed bundles. Because it supports fallback to classpath resources by default, <hst:setBundle/> is suitable for development and production.

Dynamic Resource Bundles Reloading on Changes at Runtime

The HST container includes a JCR observation listener that monitors changes to all resource bundle documents in the repository. When you publish or unpublish a resource bundle document in the CMS, the container invalidates its internal resource bundle cache. Changes are reflected on your website immediately.

Programmatic Access to Repository-Managed Resource Bundles

HST provides an API for programmatic access to resource bundles managed in the repository.

In most cases, use the utility method org.hippoecm.hst.resourcebundle.ResourceBundleUtils#getBundle(String basename, Locale locale) to retrieve a resource bundle for a given basename and locale. This method falls back to Java classpath resource bundles if no repository document is found. To control fallback behavior explicitly, use ResourceBundleUtils#getBundle(String basename, Locale locale, boolean fallbackToJavaResourceBundle).

Share Feedback
Page: /build/content-beans-translations/hst-2-dynamic-resource-bundles-support
Section: Build
Category *