HST Tag Library for Substituting Variables in Content

Overview

The HST tag library enables dynamic substitution of variables within content. Use this functionality when you need to resolve message keys or variables at runtime, rather than at compile time.

When to Use

JSTL Core Tag Libraries, such as <fmt:message key="company.greeting" />, are suitable for most internationalization scenarios where message keys are known at design time. However, if the message key is determined at runtime—for example, retrieved from a document property or a shared object—JSTL Core tags are insufficient. In these cases, use the HST tag library to resolve variables dynamically based on the current localization context or a specified resource bundle.

Considerations

• The messagesReplace tag replaces variables only in templates where it is used. In other contexts, such as REST output, variables remain unprocessed and appear as raw placeholders.
• Replacing phrases with variables can affect search results. If a phrase is replaced in all documents, it will not appear in search results as plain text. To preserve searchability, leave important terms as plain text on key pages.

HST Tag Library: <hst:messagesReplace/>

Use the <hst:messagesReplace /> tag to substitute variables in content at runtime. The tag processes all output within its body, replacing variables with values from the current localization context (the default resource bundle) or a specified resource bundle.

JSP Example

<hst:messagesReplace>
  <c:out value="${requestScope.document.companyGreeting}"/>
</hst:messagesReplace>
copy

Freemarker Example

<@hst.messagesReplace>${document.companyGreeting?html}</@hst.messagesReplace>
copy

If the nested output contains a variable such as ${company.greeting} Hippo!, the tag library looks up company.greeting in the resource bundle and replaces it with the corresponding value. For example, if company.greeting maps to Welcome to, the result is Welcome to Hippo!.

You can nest other HST tags, such as <hst:html />, within <hst:messagesReplace /> to process variables inside HTML content.

JSP Example

<hst:messagesReplace>
  <hst:html hippohtml="${requestScope.document.body}"/>
</hst:messagesReplace>
copy

Freemarker Example

<@hst.messagesReplace>
  <@hst.html hippohtml=document.body/>
</@hst.messagesReplace>
copy

All variables within ${document.body} are replaced using the default resource bundle in the current localization context.

To use a custom resource bundle, specify it with the bundle attribute.

JSP Example

<hst:messagesReplace bundle="${requestScope.customBundle}">
  <hst:html hippohtml="${requestScope.document.body}"/>
</hst:messagesReplace>
copy

Freemarker Example

<@hst.messagesReplace bundle=customBundle>
  <@hst.html hippohtml=document.body/>
</@hst.messagesReplace>
copy

You must provide the ${customBundle} object. For example, create a resource bundle and set it as a request attribute in the doBeforeRender() method.

Variable Prefix, Suffix, and Escape Character

Info: These features are available in HST 2.28.13 (Hippo 7.9.x), HST 3.0.1 (Hippo 10.0.x), and HST 3.1.0 (HST 10.1.x).
In earlier HST versions, the escape character was the dollar sign ($).

• The default escape character is the backslash (\).
• To specify a different escape character, use the escapeChar attribute:

<hst:messagesReplace escapeChar="#">
copy

• By default, variables use the ${ prefix and } suffix.
• To change the prefix and suffix, use the variablePrefix and variableSuffix attributes:

<hst:messagesReplace variablePrefix="@" variableSuffix="@">
copy

HST Tag Library Functions: hst:replaceMessages and hst:replaceMessagesByBundle

The HST tag library provides two functions for variable substitution in JSP and Freemarker templates.

• hst:replaceMessages(basename, text): Replaces variables in text using the resource bundle identified by basename.
• hst:replaceMessagesByBundle(bundle, text): Replaces variables in text using the provided ResourceBundle object.

JSP Example

<c:out value="${hst:replaceMessages("com.example.Messages", requestScope.document.summary)}" />
copy

Freemarker Example

${hst.replaceMessages("com.example.Messages", document.summary)}
copy

This function reads the summary property from the document bean and replaces all variables of the form ${company.greeting}, ${company.peptalk}, etc., using the specified resource bundle.

If you already have a ResourceBundle object, use hst:replaceMessagesByBundle:

JSP Example

<c:out value="${hst:replaceMessagesByBundle(customBundle, requestScope.document.summary)}" />
copy

Freemarker Example

${hst.replaceMessagesByBundle(customBundle, document.summary)}
copy

You must provide the ${customBundle} object, for example by setting it as a request attribute in the doBeforeRender() method.

Info: To use tag library functions in Freemarker templates, Freemarker 2.3.22 or later is required. This version is included in Hippo 7.9.8 and later. For earlier releases, override the Freemarker version in the project root POM's /project/properties section:

<freemarker.version>2.3.22</freemarker.version>
copy