HST Tag Library for Substituting Variables in Content

Introduction

Goal

Dynamically substitute variables in content.

Background

In most internationalization use cases, JSTL Core Tag Libraries would be good enough (e.g, <fmt:message key="company.greeting" />).

However, if the message key is not statically determined unlike the above example but can only be determined at runtime, then JSTL Core Tag Libraries wouldn't suffice. For example, if you get the message key from somewhere at runtime (e.g, from a shared object resolved at runtime or from document properties), then you cannot use JSTL Core Tag Libraries to resolve the message key or variables at runtime.

To solve this kind of advanced use cases, HST supports a custom tag library and tag library functions, which can resolve variables (e.g, enclosed by "${" and "}" like "${var1}", "${var2}", etc.) by either current localization context (i.e, the current default resource bundle) or a given resource bundle object at runtime.

Considerations

Please realize that the replace function will influence your search results. If you replace a specific phrase in all your documents, that phrase will not turn up as a result when searching. Leave the term "as is" without replacing it by a variable on some main page.

Also realize that the replacement takes only place on templates where the messagesReplace tag is used. On all other places the content will show the raw variable, for example in REST output, where HST tags are not used.

HST Tag Library: <hst:messagesReplace/>

You can use  <hst:messageReplace /> tag like the following examples:

JSP

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

Freemarker

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

Basically,  <hst:messagesReplace /> tag will read all output inside the tag, and it will replace any variables from the nested output by the current localization context (i.e, the current default resource bundle) if exists.

For example, if  <c:out value="${document.companyGreeting}"> outputs " ${company.greeting} Hippo!" for instance, then the tag library will find the resource bundle value by the key, " company.greeting", and replace the message with the value, resulting " Welcome to Hippo!", assuming " company.greeting" resource key is mapped to " Welcome to" string in the default resource bundle object in the current localization context.

Because the tag library replaces all the variables from all the nested output, you can also you  <hst:html /> tag within it like the following example:

JSP

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

Freemarker

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

So, if  ${document.body} contains any variables, then all those variables will be replaced by the default resource bundle in the current localization context.

Also, if you want to use a custom resource bundle object instead of the default resource bundle, then you can specify the custom resource bundle object with " bundle" attribute like the following example:

JSP

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

Freemarker

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

You should provide the  ${customBundle} object by yourself in the above case. For example, you can create a resource bundle object and set it to "customBundle" request attribute in #doBeforeRender() method.

Variable Prefix, Variable Suffix and Escape Character

The default escape character is the backslash: \.

You can specify a different escape character through the attribute escapeChar. For example:

<hst:messagesReplace escapeChar="#">

By default variables are expected to be prefixed with ${ and suffixed with }.

You can specify a different prefix and suffix through the attributes variablePrefix and variableSuffix. For example:

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

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

HST also supports two JSP Tag Library functions to replace variables.

In the following example, you can use  ${hst:replaceMessages(basename, text)} to replace variables in text by messages in the resource bundle resolved by the  basename:

JSP

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

Freemarker

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

The function reads the property, " summary" from the " document" bean and replace all the variables enclosed by " ${" and " }" (e.g,  ${company.greeting}, ${company.peptalk}, etc.) by messages in the resource bundle resolved by the  basename, " com.example.Messages".

If you already have a  ResourceBundle object, then you can use  ${hst:replaceMessagesByBundle(bundle, text)} function in stead by passing the  ResourceBundle object directly instead of using  basename:

JSP

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

Freemarker

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

You should provide the  ${customBundle} object by yourself in this case. For example, you can create a resource bundle object and set it to "customBundle" request attribute in #doBeforeRender() method.

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