Category support

Categories are a way to tag or categorize content. In OpenCms you can build tree-like category structures and assign categories to resources. In particular for XML contents, webpages and images categories are a very beneficial feature.

Categories are integrated in OpenCms the way that you can

manage categories easily via the sitemap editor,
assign categories at nearly all places (the explorer, the page editor, the galleries, the content editor),
use category information easily for filtering content in the add wizard or in galleries, and to improve your website's search page or content lists.

The topic tells you how to deal with categories in OpenCms.

About categories

Categories are basically folders in OpenCms. In each (sub-)sitemap folders below the .categories/ folder are interpreted as categories by OpenCms. For backwards compatibility, the folder can also be named _categories/. Additionally to these (sub-)site specific categories, global categories can be created as folders below /system/categories/.

If a folder is recognized as category by the system, it will appear as category in the "Assing categories" dialogs that is available via a resource's context menu in the explorer, in galleries and in the page editor. It is also available for the content editor via the category widget.

Managing categories

Global categories must be managed via the explorer by adding/deleting/modifying the category folders under /system/categories/. For (sub-)site specific categories, the sitemap editor should be used. For all users with the role Category editor the Categories view is availabe in the sitemap editor.

The categories view in the sitemap editor

The sitemap editor's categories view allows to edit local categories, i.e., the ones that are located in the currently opened (sub-)sitemap. Global categories, i.e., the ones defined system wide or in parent (sub-)sitemaps, are just displayed.

Editing a category means to edit Title and folder name.

Assigning categories via the content editor

Categories can be assigned via the content editor when editing a content. You should use elements of type OpenCmsDynamicCategory (introduced in OpenCms 10.5) and configure the category widget for these elements. This combination of type and widget allows you to assign categories to the content easily. It also allows for changing only special sub-categories via an editor field and to leave the other categories unchanged. As a consequence, you have the possibility to set different sub-categories (e.g., location/ and topic/) via different editor fields. Moreover, in contrast to using OpenCmsCategory as type, the selected categories will be synchronized for each locale and directly assigned to the resource, without being saved in the XML content itself.

Using OpenCmsDynamicCategory as type is only possible for elements that must appear exactly once in the content.

Please read the section about the category widget for information on it's configuration.

Using categories when searching for content

When you add a content to a page, you select a file or you browse in a gallery, OpenCms shows a dialog that typically has a Categories tab. Via that tab you can select categories and if you click on Results, only resources with the chosen categories assigned are displayed.

When searching content, you can restrict the displayed contents by category

Accessing categories in JSPs

When you assign categories to content, you may want to display the assigned categories when the content is rendered. Or, if you have a list of contents or a search page for your website, you may want to filter the shown results by category. Therefor, you need to access categories assigned to the content in a JSP.

Categories can be read in JSPs using EL. You can obtain a CmsJspCategoryAccessBean via the following options:

Reading a resource's categories in a JSP

content.categories: In a formatter where you use <cms:formatter var="content" ...> the categories assigned to the content are returned as CmsJspCategoryAccessBean.
cms.readCategories: The categories of the currently requested resource are returned as CmsJspCategoryAccessBean.
cms.readCategory["location/europe/"]: The category with the provided path is returned as CmsCategory.
cms.readPathCategories["location/europe/"]: Returns the list of all categories on the provided path as CmsCategory. In the example the list with the the CmsCategory objects for "/location/" and "/location/europe/" would be returned.
cms.readResourceCategories["root/path/to/resource"]: Returns the categories assigned to the resource with the given root path as CmsJspCategoryAccessBean.

Once you have an object categories of type CmsJspCategoryAccessBean, you have the following methods to access the categories:

categories.isEmpty: Yields true if no category is assigned at all, otherwise false.
categories.subCategories["location/"]: Yields again a CmsJspCategoryAccessBean for all sub-categories of "location/".
categories.allItems: The list of all categories as CmsCategory objects (sorted depth-first).
categories.leafItems: The list of all leaf categories (categories without sub-categories) as CmsCategory objects.
categories.topItems: The list of all categories that are direct children of the current main category (as CmsCategory objects).

Code examples

Display all categories of a content in a list

<c:set var="categories" value="${content.readCategories}" />
<c:if test="${not content.readCategories.isEmpty}">
  <ul>
    <c:forEach var="category" items="${categories.allItems}">
      <li>${category.title}</li>
    </c:forEach>
  </ul>
</c:if>

Display all leaf categories of a content in a list

<c:set var="categories" value="${content.readCategories}" />
<c:if test="${not content.readCategories.isEmpty}">
  <ul>
    <c:forEach var="category" items="${categories.leafItems}">
      <li>${category.title}</li>
    </c:forEach>
  </ul>
</c:if>

Rebuild the category tree for the categories assigned to a content

<c:set var="categories" value="${content.readCategories}" />
<c:if test="${not content.readCategories.isEmpty}">
  <ul>
    <c:forEach var="category" items="${categories.topItems}">
      <li>${category.title}
        <c:set var="subCategories" value="${categories.subCategories[category.path]}" />
        <c:if test="${not content.readCategories.isEmpty}">
          <ul>
            <c:forEach var="subCategory" items="subCategories.topItems">
              <li>{subCategory.title}</li>
            </c:forEach>
          </ul>
        </c:if>
      </li>
    </c:forEach>
  </ul>
</c:if>

Display the path titles of a category as label

<!-- facetItem.name returns the category path, e.g., "location/europe/germany/" -->
<c:set var="label"></c:set>
<c:forEach var="category" items="${cms.readPathCategories[facetItem.name]}" varStatus="status">
	<c:set var="label">${label}${category.title}</c:set>
	<c:if test="${not status.last}"><c:set var="label">${label}&nbsp;/&nbsp;</c:set></c:if>
</c:forEach>

Categories and search facilities

Categories are indexed by default. The category information is stored in the index fields category and category_exact. Both are multivalued and contain the category paths of the assigned categories as values. The main difference is that category is of type text_general and category_exact of type string.

To enable facetting on categories, you can build a facet on the field category_exact. To easily render the facet itself in a JSP, you may use the above code example on displaying the path titles of a category.