Taxonomy Plugin Delivery Tier Configuration

Configure and use the Taxonomy Plugin in the delivery tier (HST).

TaxonomyManager and Beans Annotated Classes

After adding and configuring the Taxonomy plugin using the setup application, a Spring TaxonomyManager component is available out-of-the-box. 

Make sure 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, it should already be there):

  <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>

Render a Document's Categories (Taxonomy Field Type)

Content Bean

If 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 will have a get method that returns a org.onehippo.taxonomy.contentbean.TaxonomyClassification object.

You can use its getTaxonomyValues method to get a List of KeyLabelPathValue objects, then use getKey, getLabel, getKeyPath, and getLabelPath methods on each list item to get the relevant String values.

If dynamic bean generation is disabled, a method similar to the getKeys() method (as described below for the legacy taxonomy mixin) should be added to the content bean.

Delivery API

In the Delivery API, a taxonomy field will show the field like in the example below, with a taxonomyValues entry as an taxonomyAllValues entry, meaning with 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

Assuming the taxonomy field name is "taxonomy", the following JSP snippet renders 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

Assuming the taxonomy field name is "taxonomy", the following Freemarker snippet renders 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>

Render a Document's Categories (Legacy Taxonomy Mixin)

Content Bean

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

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

JSP Template

The Taxonomy Plugin includes a tag library (TLD) containing a single tag (TaxonomyTag) to help render 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, then 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 is limited. Your best option is to obtain all required taxonomy information within an HST component (see below) and use request attributes to make that information available to the Freemarker template.

Obtain a Taxonomy within an HST Component

Import the required classes, obtain the TaxonomyManager, then obtain a taxonomy by the name of its root node (exampletaxonomy in this example):

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 shows several ways to use a Taxonomy object from within the delivery tier: to search for a taxonomy value, to generate the full taxonomy tree and to locate an entry.