Bloomreach Forge Properties Plugin – Usage in an HST site

Usage in an HST site

There is a <properties:property/> tag available for usage in a frontend. You also can access properties bean in HST components through the Properties Manager (or directly by path) to prepare a map of name/value pairs for the JSP.

Use the <properties:property/> tag in JSP

The JSP tag is easy to use for your site's labels and will suffice if the properties documents and the property names do not change in a standing environment. If that is the case, you may want to parameterize the attribute values. This is a standard usage of the JSP tag:

  <%@ taglib prefix='properties'
      uri="http://www.onehippo.org/properties/jsp/tags"%>

  <properties:property var="myVariable"
                       name="myPropertyName"
                       documentPath="myPropertiesDocumentPath"/>
  <div>${myVariable}</div>

Attributes of <properties:property/>
var	Optional variable name by which to store the property value as request attribute.
name	Mandatory name of the name/value pair that is the property.
documentPath	Optional path to the properties document to get the property from, relative to the default document location as configured in the Properties Manager. If absent, the default document name from the Properties Manager is taken.
language	Optional two letter language code to be used to retrieve a translated variant of the properties document. If language is not given then request's locale is used.
managerPostFix	Optional postfix that is added to 'org.onehippo.forge.properties.api.PropertiesManager.' to retrieve the Properties Manager by id. Defaults to 'labels'.

Parameterized properties with nested <properties:param/> tags

Formatting a property value with parameters is supported by the <properties:param/> tag which is nested in <properties:property/>. All the possibilities of the class java.text.MessageFormat can be used. These are two examples:

  <properties:property name="date.short" documentPath="example" >
      <properties:param value="<%= new java.util.Date() %>"/>
  <properties:property>

In property file named 'example' for key date.short the value is "Today's date is {0,date,short}". Above code will result in "Today's date is 21/09/12".

  <properties:property name="test.string" documentPath="example" >
      <properties:param name="Tom"/>
      <properties:param value="Mac"/>
  </properties:property>

In property file named 'example' for key test.string value is "{0} and {1} are good friends". Above code will result in "Tom and Mac are good friends". \

Attribute of <properties:property/>
value	Required value of the parameter of type Object.

Use the PropertiesManager in a HST component

This is an example of how properties documents are read using the manager. The manager will look for properties with configured name or the default name from the configure default location, relative to the given site content base bean.

For use with 7.8

   // get the manager and base bean
  ComponentManager componentManager = (ComponentManager) this.getDefaultClientComponentManager();
  PropertiesManager propertiesManager = componentManager.getComponent(PropertiesManager.class.getName());
  HippoBean baseBean = this.getSiteContentBaseBean(request);
  ...

For use with 7.9

  // get the manager and base bean
  PropertiesManager propertiesManager = HstServices.getComponentManager().getComponent(PropertiesManager.class.getName());
  HippoBean baseBean = this.getSiteContentBaseBean(request);
  ...

...
  // Example A: retrieve one document bean by the configured default name
  PropertiesBean defaultPropertiesBean = this.propertiesManager.getPropertiesBean(baseBean);
  Map<String, String> defaultLabels = PropertiesUtil.toMap(propertiesBean);
  request.setAttribute("labels", defaultLabels);

  // Example B: retrieve one document bean by path parameter
  String labelsPath = this.getParameter("labelsPath", request);
  PropertiesBean propertiesBean = this.propertiesManager.getPropertiesBean(labelsPath, baseBean);
  Map<String, String> labels = PropertiesUtil.toMap(propertiesBean);
  request.setAttribute("labels", labels);

  // Example C: retrieve multiple document beans by hardcoded paths
  List<String> labelsPaths = Arrays.asList("common", "specific");
  List<PropertiesBean> propertiesBeans = this.propertiesManager.getPropertiesBeans(labelsPaths, baseBean);
  Map<String, String> allLabels = PropertiesUtil.toMap(propertiesBeans);
  request.setAttribute("labels", allLabels);

Retrieval of properties beans in a HST component directly by path

This is an example of how a properties bean containing labels is read from a configured path relative to site base bean. This is typically something that you can do in your project's base component.

  String labelsPath = this.getParameter("labelsPath", request);
  Properties labels = (Properties) this.getSiteContentBaseBean(request).getBean(labelsPath);
  request.setAttribute("labels", new PropertiesMap(new PropertiesBean(labels));

Reading property maps in JSP files

Because the PropertiesMap set at the request is a Map, it can be read using expression language. This is an example of reading labels:

  <div id="header">
      <span>${labels['header.title']}</span>
      <span>${labels['header.subtitle']}</span>
  </div>