Categorization module

Edition	CE
License	MLA, GPL
Issues	MGNLCAT
Maven site	Categorization
Latest	2.8

Edition

License

MLA, GPL

Issues

MGNLCAT

Maven site

Categorization

Latest

2.8

The Categorization module allows you to add categories to content. Categorization, also known as tagging or labeling, is a tool to manage large amounts of content. Categories help you describe content and allow visitors to find it by browsing or searching.

Module structure

artifactID

magnolia-module-categorization-parent

Parent reactor.

magnolia-categorization

Main module containing the API, commands and the catfn templating functions.

magnolia-categorization-support

Submodule containing the CategorizationSupport interface.

magnolia-categorization-app

Submodule containing the Categories app.

magnolia-categorization-app-compatibility

Submodule containing the Categories compatibility app. Bundled in magnolia-community-webapp and used for backward compatibility.

For custom bundles, you have to add it yourself.

Installing

If you are using a preconfigured Magnolia webapp or bundle, the modules are already included. The same is true if you are using a custom webapp based on magnolia-community-webapp or magnolia-dx-core-webapp.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.categorization</groupId>
  <artifactId>magnolia-categorization</artifactId>
  <version>2.8</version>
</dependency>

magnolia-categorization depends on magnolia-categorization-support. It is sufficient to add the former to the POM file of your webapp.

What is a category?

A category is a non-hierarchical keyword assigned to a piece of content to help describe and find that content. Compared to building a hierarchy, categorization is a bottom-up approach. You can classify your content in an unlimited number of ways, and there is no wrong choice. Instead of belonging to only one category, an item may belong to several.

Categorization is typically a prerequisite to faceted search. You first need a faceted classification system before you can combine facets to filter content quickly.

Example: Tour types in the Magnolia Travel Demo include categories such as active, beach and cultural.

Tour types

Categories assigned to a content item are typically displayed as links on the website.

Categories on site

Creating categories

Use the Categories app to create categories.

Fields:

Category name (required): Internal name used to access the category programmatically (for example, with catfn functions).
Display name: Friendly name displayed to users when the category is rendered, for example, as a link on the website.
Importance: Gives the category more weight. Used to promote certain categories.
Related categories: Links to other categories. Helps visitors discover related content.

Create your own app to manage a subset of categories. Authors appreciate when they can focus on one thing at a time such as categories for a particular purpose. Managing a smaller subset helps authors work more efficiently. The Tour Categories app in the Magnolia Travel Demo is an example of this strategy. The app only shows categories that apply to tours.

Additional fields in the Tour Categories app:

Image (required): Image representing the category.
Icon (required): Icon representing the category.
Description: Short description for the category.
Body Text: Full description for the category.

Categorizing content

To categorize content, edit the content item’s properties and choose applicable categories.

Example: A tour of Kyoto is categorized as ecotourism and offPath (off the beaten path).

Edit mode

The easiest way to make categorization available to editors is to use the existing categories field from the Categorization module. If you configure your dialog using a YAML file, paste the categories field into your form definition.

Example definition

form:
  properties:
    categories:
      label: Categories
      $type: linkField
      buttonSelectNewLabel: Select new ...
      buttonSelectOtherLabel: Select another ...
      datasource:
        $type: jcrDatasource
        workspace: category
        rootPath: /tour-types

Getting content by category

Use the catfn functions to access categorized content in your templates. This set of templating functions helps you find content in a particular category. A typical use case is to offer the visitor similarly tagged pages, helping them discover additional interesting content.

Example 1: List all pages tagged with travel.

[#assign rootPage = cmsfn.asJCRNode(cmsfn.root(content, "mgnl:page"))!]
[#assign travelPages = catfn.getContentByCategory(rootPage, "travel")!]

<ul>
[#list travelPages as page]
   [#assign title = cmsfn.asContentMap(page).title!page.getName()]
    <li>${title}</li>
[/#list]
</ul>

Example 2: List the categories of the current page.

<p>This page has the following categories:
[#assign currentNode = cmsfn.asJCRNode(content)]
[#assign myCategories = cmsfn.asContentMapList(catfn.getCategories(currentNode))]
[#list myCategories as cat ]
    ${cat.displayName},
[/#list]
</p>