Taxonomy Plugin Delivery Tier Configuration

This page describes how to configure and use the Taxonomy Plugin in the delivery tier (HST).

TaxonomyManager and Beans Annotated Classes

After you add and configure the Taxonomy plugin using the setup application, the Spring TaxonomyManager component is available by default.

Verify that the hst-beans-annotated-classes context parameter is defined in src/main/webapp/WEB-INF/web.xml in your project's site module. If you created your project from the archetype, this parameter should already be present:

<context-param>
  <param-name>hst-beans-annotated-classes</param-name>
  <param-value>classpath*:org/example/**/*.class
    ,classpath*:org/onehippo/**/*.class
    ,classpath*:com/onehippo/**/*.class
    ,classpath*:org/onehippo/forge/**/*.class
  </param-value>
</context-param>

Rendering a Document's Categories (Taxonomy Field Type)

Info: This feature is available in brXM 15.3.0 and later.

Content Bean

When you add a taxonomy field to a document type using the Document Type Editor and have dynamic bean generation enabled (default), the generated content bean for the document type includes a getter that returns a org.onehippo.taxonomy.contentbean.TaxonomyClassification object.

Call the getTaxonomyValues method to retrieve a List of KeyLabelPathValue objects. For each object in the list, use the getKey, getLabel, getKeyPath, and getLabelPath methods to access the corresponding string values.

If dynamic bean generation is disabled, you must manually add a method similar to getKeys() (see Legacy Taxonomy Mixin) to the content bean.

Delivery API

In the Delivery API, a taxonomy field appears as shown below. The taxonomyValues entry contains the selected categories, and the taxonomyAllValues entry includes the selected categories and their ancestors:

"taxonomy": {
  "taxonomyValues": [
    {
      "key": "my-sub-category",
      "label": "My Sub Category",
      "keyPath": "1/my-category/my-sub-category/",
      "labelPath": "1/My Category/My Sub Category/"
    }
  ],
  "taxonomyAllValues": [
    {
      "key": "my-sub-category",
      "label": "My Sub Category",
      "keyPath": "1/my-category/my-sub-category/",
      "labelPath": "1/My Category/My Sub Category/"
    },
    {
      "key": "my-category",
      "label": "My Category",
      "keyPath": "0/my-category/",
      "labelPath": "0/My Category/"
    }
  ],
  "taxonomyName": "myTaxonomy"
}

JSP Template

If the taxonomy field name is taxonomy, use the following JSP code to render a list of taxonomy categories for the current document:

<ul>
  <c:forEach var="category" items="${document.taxonomy.taxonomyValues}">
    <li>${category.label}</li>
 </c:forEach>
</ul>

Freemarker Template

If the taxonomy field name is taxonomy, use the following Freemarker code to render a list of taxonomy categories for the current document:

<#if document.taxonomy??>
  <ul>
    <#list document.taxonomy.taxonomyValues as category>
      <li>${category.label}</li>
    </#list>
  </ul>
</#if>

Rendering a Document's Categories (Legacy Taxonomy Mixin)

brXM 15.3.0 introduced the taxonomy field type, which replaces the legacy mixin-based taxonomy field. The legacy mixin remains supported for backward compatibility.

Content Bean

After you add the taxonomy mixin to a document type using the Essentials setup application, run the Beanwriter tool to update the document type's content bean class. This adds a getKeys() method:

public String[] getKeys() {
    return getMultipleProperty("hippotaxonomy:keys");
}

JSP Template

The Taxonomy Plugin provides a tag library (TLD) containing a single tag (TaxonomyTag) for rendering a document's categories.

Declare the taxonomy tag library:

<%@ taglib uri="http://www.hippoecm.org/jsp/hst/taxonomy" prefix='tax'%>

Use the tax:categories tag to obtain a list of lists of org.onehippo.taxonomy.api.Category objects. Iterate through the nested lists and render each category for the document's locale:

<tax:categories var="list" keys="${document.keys}" />
<c:forEach var="ancestors" items="${list}">
  <ul>
    <c:forEach var="category" items="${ancestors}">
      <c:set var="categoryInfo" value="${category.infos[document.locale]}" />
      <li>${categoryInfo.name}</li>
    </c:forEach>
  </ul>
</c:forEach>

Freemarker Template

Due to CMS-13025, Freemarker support for the legacy taxonomy mixin is limited. The recommended approach is to retrieve all required taxonomy information within an HST component (see Obtain a Taxonomy within an HST Component) and expose it to the Freemarker template via request attributes.

Obtain a Taxonomy within an HST Component

To access a taxonomy within an HST component, import the required classes, obtain the TaxonomyManager, and retrieve the taxonomy by the name of its root node (for example, exampletaxonomy):

import org.onehippo.taxonomy.api.Taxonomy;
import org.onehippo.taxonomy.api.TaxonomyManager;

final TaxonomyManager taxonomyManager =
  HstServices.getComponentManager().getComponent(TaxonomyManager.class.getSimpleName(), "org.onehippo.taxonomy.contentbean");
Taxonomy taxonomy = taxonomyManager.getTaxonomies().getTaxonomy("exampletaxonomy");

The Taxonomy Essentials demo feature demonstrates several ways to use a Taxonomy object in the delivery tier, including searching for a taxonomy value, generating the full taxonomy tree, and locating a specific entry.