Taxonomy Plugin Delivery Tier Configuration

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

TaxonomyManager and Beans Annotated Classes

Afteradding and configuring the Taxonomy plugin using the setup application, a SpringTaxonomyManager component is available out-of-the-box. 

Make sure thehst-beans-annotated-classes context parameter is defined in src/main/webapp/WEB-INF/web.xml in your project'ssite module (if youcreated 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 youadd a taxonomy field to a document type using theDocument Type Editor and havedynamic 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 itsgetTaxonomyValues method to get aList of KeyLabelPathValue objects, then usegetKey,getLabel,getKeyPath, andgetLabelPath methods on each list item to get the relevant String values.

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

Delivery API

In theDelivery API, a taxonomy field will show the field like in the example below, with ataxonomyValues entry as antaxonomyAllValues 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 youadd the taxonomy mixin to a document type using the Essentials setup application, make sure to run theBeanwriter tool to update the document type's content bean class. This will add agetKeys() 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 thetax:categories tag to obtain a list of lists oforg.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 theTaxonomyManager, 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 aTaxonomy object from within the delivery tier: to search for a taxonomy value, to generate the full taxonomy tree and to locate an entry.