Categorization module allows you to create hierarchical categories and tag articles and content with them. When applied to content, categories create a taxonomy, a set of metadata that describes and classifies the content. Categories are displayed as links in the article header or as a weighted list known as category cloud. By clicking category links, visitors discover related, interesting content, resulting in more page views and longer stays on the site.

• Download
• Installing
• Uninstalling
• Features
• Configuration
• Creating categories
• Tagging content with categories
• Tagging articles
• Tagging other pages
• Tagging data items
• Displaying categories
• Category Overview page
• Category cloud paragraphs
• Adding a cloud to base area
• Adding a cloud to main area
• Adding a cloud to extras area
• Inheriting clouds to subpages
• Category appearance in cloud
• RSS feed
• Organizing categories
• Parent-child hierarchy
• Folder hierarchy
• Commands
• Generating categories automatically
• Removing categories automatically
• Adding your own commands
• Scheduling
• Observation
• Importing and exporting categories

Download

Enterprise users can download the Categorization module from Magnolia Store or Nexus repository.

Installing

Categorization is a Community Edition module (4.1 and higher) included in the Standard Templating Kit module bundle and typically automatically installed. Go to Magnolia Store > Installed modules in AdminCentral to verify installation. To install the module individually, see the general module installation instructions.

Uninstalling

See the general module uninstalling instructions and advice.

Features

The Categorization module allows you to:

• Add and edit categories.
• Tag articles and data items with categories.
• Display categories with their tagged article.
• Display category cloud paragraphs.
• Display a Category Overview page.
• Create RSS feeds for articles tagged with selected categories.

Configuration

The module is ready to use as such. No initial configuration is necessary. For customization, see the following configurable elements:

Dialogs:

• Create and edit categories: /modules/data/dialogs/category
• Tag articles with categories: /modules/categorization/dialogs/generic
• Add and edit Category Cloud paragraph: /modules/categorization/dialogs/catCloud
• Add and edit Category RSS Feed paragraph: /modules/categorization/dialogs/categoryRSSFeed

• Category Cloud: /modules/categorization/paragraphs/catCloud
• Category Cloud Wide: /modules/categorization/paragraphs/catCloudWide
• Category Cloud Extras: /modules/categorization/paragraphs/catCloudExtras
• Category RSS Feed: /modules/categorization/paragraphs/categoryRSSFeed

• Generate categories: /modules/categorization/commands/categorization/generateCategories
• Remove categories: /modules/categorization/commands/categorization/removeCategories

• /modules/scheduler/config/jobs/generateCategories
• /modules/scheduler/config/jobs/removeCategories

• /modules/observation/config/listenerConfigurations/generateCategories

Creating categories

1. Go to Data > Category.
2. Click New Item in the toolbar or right-click the parent and select New Item.
   
   
3. Enter a Category Name. This is the internal name for the category displayed in AdminCentral.
4. Enter a Display Name. This is displayed to users on Web pages.
5. Select Importance.
   Importance allows editors to emphasize or give more weight to certain categories. It affects the appearance of the category label and the order in which the category appears in a category cloud paragraph.
6. Select Related Categories.
   Related categories are displayed in the Related Categories Link List paragraph in the extras area on a Category Overview page. They provide a method for discovering additional interesting content.

Tagging content with categories

Categories become visible to visitors when you tag content with them. They are typically displayed as links that lead to a Category Overview page. The page displays other content that is tagged with the same category. This is a way for visitors to discover related, interesting content.

Tagging articles

By default, the module allows you to tag any page that has the stkArticle template assigned to it. You can extend this ability to other page templates.

To tag an article with a category:

1. Open an article page for editing.
2. Click Edit Article Header.
3. Go to the Category tab.
   
   
4. Click Choose to choose a category.
   
   
5. To tag the article with more than one category, click Add.

Tagging other pages

Besides articles you can tag other pages. Add the generic Category tab to the desired page's header dialog through configuration. The generic tabCategorization configuration is in /modules/categorization/dialogs/generic/tabCategorization. You can reference it to avoid duplication. Referencing is a mechanism that saves time and effort as you only need to configure the item once and reuse it elsewhere.

1. Go to Templating Kit > Dialog Definitions > /pages/article/stkArticleHeader. This is the dialog definition for articles. It already contains a Category tab.
2. Copy the tabCategorization content node and paste it into the target dialog definition. Here we paste it into /pages/event/stkEventHeader so we can tag event pages.
3. Open an event page for editing.
4. Click Edit Event Header.
5. Go to the Category tab. This is the new tab you just configured.
6. Select a category such as Local and save. The category link is displayed in the event header.

You can tag other page types the same way. Find the dialog that controls the page header and add the Category tab to it.

Tagging data items

Besides web pages, you can tag other content objects such as data items. The tabCategorization tab can be added to other dialogs. For example, copy the tab configuration to /modules/data/dialogs/Contact to tag contacts.

The Category tab is included in the Contact dialog.

<nodeType hasOrderableChildNodes="true" isMixin="false" name="dataBase" primaryItemName="">
   <supertypes>
      <supertype>mix:referenceable</supertype>
      <supertype>nt:hierarchyNode</supertype>
   </supertypes>
   <propertyDefinition 
      autoCreated="false" 
      mandatory="false" 
      multiple="false" 
      name="*" 
      onParentVersion="COPY" 
      protected="false" 
      requiredType="undefined" />
   <propertyDefinition 
      autoCreated="false" 
      mandatory="false" 
      multiple="true" 
      name="*" 
      onParentVersion="COPY" 
      protected="false" 
      requiredType="undefined" />
   <childNodeDefinition 
      autoCreated="false" 
      defaultPrimaryType="" 
      mandatory="false" 
      name="*" 
      onParentVersion="COPY" 
      protected="false" 
      sameNameSiblings="true">
      <requiredPrimaryTypes>
         <requiredPrimaryType>nt:base</requiredPrimaryType>
      </requiredPrimaryTypes>
   </childNodeDefinition>
</nodeType>

Displaying categories

In addition to the page header, you can display categories to users in the Category Overview page and cloud paragraphs. Both are ways to discover related interesting content.

Category Overview page

The Category Overview page displays all articles tagged with the selected category. It is a way to find related, interesting content. You can add the page to at any location in the website. It does not need to be included in the site navigation since the user navigates to it automatically by clicking a category in an article header, in a category cloud or in the Related categories list. The template for the page is Category Overview.

Categories that are related to the selected category are displayed on the right hand side of the Category Overview page. This list contains categories that editors have linked to the selected category as well as categories that are siblings, children or parents of the selected category. The paragraph that renders the list is Can't resolve link to: /reference/paragraph/categorization.

The categorization module provides the ability to display editorial tag clouds that contain selected categories in varying formats and locations.

The module allows for expansion with respect to providing the ability to easily add category clouds to various areas.

Category cloud paragraphs

A category cloud is a weighted lists of categories, displayed as a group where important categories are given more visual weight. The visual weight is typically accomplished by making popular categories larger or bolder. Clicking a category in the cloud displays the Category Overview page with other articles tagged with the same category.

The Categorization module provides three cloud paragraphs:

catCloud in the main area of the page

catCloudWide in the base area of the page

catCloudExtras in the extras area of the page

The paragraphs are configured in Configuration > /modules/categorization/paragraphs. Each paragraph displays a category cloud of different width, accommodating the page area in which is resides.

Adding a cloud to base area

The base element category cloud cateCloudWide is readily configured. You can add it to the base of any page.

To add a base element category cloud:

1. Open a page for editing.
2. Click New Base Element at the bottom of the page.
3. Select Category Cloud.
4. Enter a Title to be displayed at the paragraph heading.
5. Click Choose to choose a category to display in the cloud. Click Add to add more categories to the cloud.
6. Select a Category order:
• None displays categories in the order they were selected.
• Name displays categories in alphabetical order.
• Importance displays categories in the order of their level of importance.
7. Save.

Adding a cloud to main area

The category cloud paragraph is not available in the main area by default. You need to configure it first.

To make the paragraph available:

1. Go to Templating Kit > Site Definitions > /default/templates/prototype/mainArea.
2. Under mainArea, create a new content node paragraphs.
3. Under paragraphs, create a new content node catCloud.
4. Under catCloud, create a new data node name and set its value to catCloud

To add the paragraph on the page:

1. Open an article page for editing.
2. Click New Content in the main area.
3. Select Category Cloud.
4. Enter a Title to be displayed at the paragraph heading.
5. Click Choose to choose a category to display in the cloud. Click Add to add more categories to the cloud.
6. Select a Category order:
• None displays categories in the order they were selected.
• Name displays categories in alphabetical order.
• Importance displays categories in the order of their level of importance.
7. Save.

Adding a cloud to extras area

To make the paragraph available:

1. Go to Templating Kit > Site Definitions > /default/templates/prototype/extrasArea/paragraphs.
2. Under paragraphs, create a new content node catCloudExtras.
3. Under catCloudExtras, create a new data node name and set its value to catCloudExtras

To add the paragraph on the page:

1. Open an article page for editing.
2. Click New Extras in the main area.
3. Select Category Cloud.
4. Enter a Title to be displayed at the paragraph heading.
5. Click Choose to choose a category to display in the cloud. Click Add to add more categories to the cloud.
6. Select a Category order:
• None displays categories in the order they were selected.
• Name displays categories in alphabetical order.
• Importance displays categories in the order of their level of importance.
7. Save.

Inheriting clouds to subpages

Make the paragraph inheritable:

1. Go to Configuration > /modules/categorization/dialogs/catCloud/tabMain.
2. Under tabMain, create a new content node inheritable.
3. Under inheritable, create a new data node reference and set its value to /modules/standard-templating-kit/dialogs/generic/controls/inheritable.

Make the page template script inherit its content from parent pages. In this example we place a cloud paragraph in the base area of a section page. This area is rendered by baseArea.ftl script:

1. Go to Templating Kit > Templates > /templating-kit/templates/global.
2. Edit the baseArea template script.
3. Add inheritance to contentNodeIterator tag:
   [@cms.contentNodeIterator contentNodeCollectionName="base" inherit=true]
4. Check the Enable template checkbox.
5. Save.

1. Open a page such as /demo-project/about/subsection-articles for editing.
2. Click New Base Element at the bottom of the page.
3. Select Category Cloud.
4. Enter a Title to be displayed at the paragraph heading.
5. Click Choose to choose a category to display in the cloud. Click Add to add more categories to the cloud.
6. Select a Category order:
• None displays categories in the order they were selected.
• Name displays categories in alphabetical order.
• Importance displays categories in the order of their level of importance.
7. Check the Show in subpage checkbox.
8. Save.

When you add a category cloud to an extras area it is automatically inherited to child pages if the Show in subpage checkbox is checked.

When you add a category cloud to a main area, edit the mainArea template at Templating Kit > Templates > /templating-kit/templates/global the same way the baseArea template was edited above.

Category appearance in cloud

Tag cloud is an editorial tool. This means that the weight of categories is calculated by their popularity, number of visits or search hits. An editor decides how prominently a given category is displayed in the cloud. This allows editors can emphasize categories to promote topical content such as campaigns.

The visual appearance is a combination of the importance level set by the editor and a style defined in CSS. Setting a high level of importance results in a larger and bolder font. Can't resolve link to: /templating/stk/css-concepts explains how the style sheet defines the appearance.

To change the CSS style:

1. Go to Templating Kit > Resources > /templating-kit/themes/pop/css.
2. Edit styles.css.
3. Search for tagCloud.
4. Edit the font size and weight as specified for categories with importance levels 2 through 5.
5. Save.

Another example of extension is displaying icons for categories. See blog post Category cloud with images for details.

RSS feed

You can create an RSS feed of articles that have been tagged with a particular category. As a prerequisite, at least one page under the selected root node must be tagged with the selected category.

To create a RSS feed for a category:

1. Open a page in the website for editing.
2. Click New Extras.
3. Select Category based RSS feed.
4. In Content Root, select a branch in the site hierarchy where you want to look for content. For example, if you want to create a feed for event pages, select the Events Overview page.
5. Click Choose... to choose a category. The RSS aggregator will search the branch for any page that has been tagged with this category and includes the page in the feed.
6. Click Add if you want to include more categories in the criteria. If the RSS aggregator finds a page that has any of these categories, it includes the page in the feed.
7. Click Save.

Organizing categories

You can organize categories in a hierarchical structure. Such a structure establishes relationships between categories which in turn allows visitors to navigate to related, interesting content.

Parent-child hierarchy

You can make a category the child of another category by creating or moving it under an existing category.

When an article is tagged with the parent category, the parent is displayed on the article's category line.

The Category Overview page displays the children as related categories.

When an article is tagged with a child category, the child is displayed in the article's category line.

The Category Overview page displays the child's parent and siblings as related categories.

Folder hierarchy

Folders are a convenient way to handle a large number of categories such as a controlled vocabulary.

To create a folder:

1. Click Refresh if a category is already selected.
2. Click New Folder.
3. Set name of new folder.
4. Move or create categories inside the folder.

Note: Categories cannot contain folders.

Commands

The module provides example commands for generating categories and tagging articles with them automatically.

When installing with the Observation and Scheduler modules there is some configuration that needs to be performed to activate the commands.

Generating categories automatically

The generateCategories command creates categories automatically and tags articles with them. It names the categories according to the template used on the page. For example, a page whose template is of type article is tagged with category article. The command also examines which section of the site the page belongs to and creates a matching category. For example, if the page resides under section Articles, it creates a category Articles and tags the page with it.

You can also execute the command in a Groovy script.

cm = info.magnolia.commands.CommandsManager.getInstance()
command = cm.getCommand('categorization-generateCategories')
command.setRepository('website')
command.setPath('/demo-project/about/subsection-articles/large-article')
command.execute(ctx)

The command generates categories for pages whose template type is stk, template category is content and template subcategory is set to any string. Categories won't be generated for pages with a template where category is set to feature. As a result, categories will be generated for articles but not for a glossary.

The command creates two folders in Data > Categories: sections and types. When you execute the command on a page such as /demo-project/about/subsection-articles/large-article whose section is subsection-articles and template type is article, the command creates the corresponding categories in the folders.

The command is not intended to be used as such. It is an example that helps you understand what you can do with the Categorization module and custom commands. For example, you might want to customize the command to crawl event pages periodically and tag them with Event, or newsletters with News. Commands can automate some of the tagging work that editors would otherwise need to do by hand.

Removing categories automatically

The removeCategories commands removes tags from content. It doesn't remove the categories from data, just "unapplies" them. In this respect it partially reverses what the generateCategories command does. The command accepts the same parameters as generateCategories.

You could use this command as such to perform a cleanup before a re-tagging effort. Or customize it to perform targeted stripping of certain categories. For example, if you had tagged a section of the site with a campaign category such as Offers or LastMinute you could strip them once the campaign is over. This is the kind of editorial tag cloud control that allows you to emphasize prime content.

Adding your own commands

You can add a new command by creating a class that extends the BaseRepositoryCommand class, as is done with generateCategories and removeCategories. Add the new command to the list of commands in Config > /modules/categorization/commands/categorization.

Scheduling

Use the Scheduler module to execute commands at a given time. Example schedules for generateCategories and removeCategories are installed with the Categorization module. See Scheduling in Technical Guide for more on scheduling commands.

Observation

The Observation module includes an example listener generateCategories that applies categories to new pages automatically. The listener listens for NODE_ADDED events, such as adding of new pages, and executes the same CategoryGeneratorCommand.java logic as generateCategories.

To activate the generateCategories listener:

1. Click Configuration.
2. Go to /modules/observation/config/listenerConfiguration/generateCategories.
3. Change active to true.

As with the scheduler, you can execute your own categorization commands by setting the command class property to the fully qualified path of your custom Java class. For example, if you have site branch that contains financial information, tag any new pages added to that branch with Finance automatically.

Importing and exporting categories

You can import and export categories in JCR System View XML format. A third party taxonomy such as a controlled vocabulary can be imported into the system provided it follows this format. If the schema does not follow the format you can convert it with a custom script such as using Magnolia CMS built-in Groovy scripting.

To export a taxonomy created in the Categorization module in JCR System View XML format:

1. Go to Data > Category.
2. Right-click in the empty space on the right-hand side page.
3. Select Export tree to xml.
4. Click OK.

1. Go to Data > Category.
2. Right-click in the empty space on the right-hand side page.
3. Select Import from xml.
4. Select file to be imported.
5. Click Import.