Categorization module

Edition CE

License

MLA, GPL

Issues

MGNLCAT

Maven site

Categorization

Latest

2.7.1
Related topics

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.

info.magnolia.categorization

The main module containing the API, commands, the Categories app and the templating functions catfn.

magnolia-categorization-support

The submodule containing the interface CategorizationSupport (moved from STK with the release of Magnolia 5.4).

if you are using a preconfigured webapp or bundle - plural

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 dx-core-webapp).

Otherwise:

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.7.1</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. Categories help you describe and find content. Compared to building hierarchy, categorization is a bottom-up approach. You can classify your content in 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. Then you can combine facets to filter content quickly.

Example: Tour types in the Magnolia Travel Demo are categories: active, beach, cultural and so on.

image

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

image

Creating categories

Use the Categorization 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 as a link on the website, for example.

  • Importance: Gives the category more weight. Use importance to promote certain categories and influence their presentation.

  • Related categories: Links to other categories. Helps visitors discover other related content.

  • Description: A short description of the category.

  • Image (required): An image representing the category.

  • Icon (required): An icon representing the category.

  • Body Text: A full description of the category.

Create your own app

Create your own app to manage a subset of categories. Authors appreciate it when they can focus on one thing at a time such as categories for a particular purpose. Managing a smaller subset reduces cognitive load and 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.

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

image

The easiest way to make categorization available to editors is to use the ready-made categories field from the Categorization module. This generic multivalue field allows editors to apply any number of categories to the content item.

  • JCR: If you configure your dialog or editor using JCR nodes, extend the categories field definition.
    The Tours app extends the categories field. The additional targetTreeRootPath property narrows the choice to categories in the /tour-types folder.
    image

  • YAML: If you configure your dialog or editor using a YAML file, paste the categories field into your form definition.
    For example:

    form:
  tabs:
    - name: tabCategories
      label: Categories
      fields:
        - name: categories
          class: info.magnolia.ui.form.field.definition.MultiValueFieldDefinition
          label: Select category
          field:
            name: linkField
            class: info.magnolia.ui.form.field.definition.LinkFieldDefinition
            targetWorkspace: category
            appName: categories
            identifierToPathConverter:
              class: info.magnolia.ui.form.field.converter.BaseIdentifierToPathConverter

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. See Category overview for a ready-made template that does the same.

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

More examples: catfn

Templates

The Categorization module provides templates for common use cases. Check them out before you write your own.

Category overview

Category overview is a page template that offers visitors similar content based on the category they have clicked. The page renders links to other pages that belong to the same category.

image

The category overview template is available as a page and as a component:

  • categorization:pages/categoryOverview is the page template. The page autogenerates the component for your convenience. You need to add this page on your site if you want to use the category cloud component. Links in the category cloud take visitors to the category overview page. The Category Overview page definition includes two properties type=feature and subtype=categoryOverview which make the page a link target.

  • categorization:components/categoryOverview is the component template. You can add the component to any page, it doesn’t have to be on the Category Overview page, but you need to add the type=feature and subtype=categoryOverview properties to the page definition if you want links the cloud component to work.

Visitors typically request the category overview page by passing a category name as a selector in the URL:

http://localhost:8080/magnoliaAuthor/category-overview~travel~.html

where:

  • category-overview.html is the page name.

  • travel is a category name as a selector.

You can style the page as you like. Make a simple textual index or visually attractive teasers. Here’s an example from the https://demopublic.magnolia-cms.com/tour-typeactive.html[Travel Demo] that teases tours in the active category.

image

Category cloud

A tag cloud is a weighted list of keywords. The importance of each tag is shown with font size. Bigger font means the tag is more prominent or more content is tagged with the tag. Visitors can quickly see what is hot on the site.

Magnolia’s category cloud is different from a typical tag cloud. Instead of using the number of tagged items as weighting criterion, editors assign an importance level to each category. The higher the importance, the bigger the font. This mechanism allows editors emphasize prime content. For example, if you run an ecotourism campaign on a travel site, set the importance level of the ecotourism category to 5. This makes the category big in the cloud and drives more clicks to campaign content.

Links in the cloud point to the Category overview page, which means you must have a category overview page on your site.

image

The category cloud template script renders an unordered (bulleted) list of links by default:

<div class="tagcloud">
  <ul>
    <li class="level-1">
      <a href="/magnoliaAuthor/category-overview~active~.html" >Active</a>
    </li>
    <li class="level-5">...</li>
    <li class="level-5">...</li>
    <li class="level-2">...</li>
    etc.

Add your own style sheet to make the list look like a cloud, such as:

category-cloud.css

.tagcloud {line-height: 3em; text-align: center;}
.tagcloud li {padding: 6px; display: inline;}
.tagcloud li.level-1 { font-size: 1.0em;}
.tagcloud li.level-2 { font-size: 1.4em;}
.tagcloud li.level-3 { font-size: 1.8em;}
.tagcloud li.level-4 { font-size: 2.0em;}
.tagcloud li.level-5 { font-size: 2.2em;}
Feedback