Categorization

The Categorization module allows you to add and edit categories to tag article pages. The module is integrated with the Standard Templating Kit and features include category cloud components, category overview pages and category RSS feeds.

Creating categories

Categories are stored in the Data module  and managed in AdminCentral in Data > Category.

To create a category:

1. Cick New Item.
2. In the dialog, enter:
   
   1. Category Name. This is the internal name of the category.
   2. Display Name. This is displayed to users on pages.
   3. Importance. Allows editors to give more weight to certain categories. It affects the appearance of the category label and the order in which categories display in category cloud components.
   4. Related Categories. Display in the Related Categories teaser component in extras area on the Category overview page. They provide a method for discovering additional interesting content.

Organizing categories

You can organize categories in hierarchical structures of categories and/or folders. 

Component definitions

Component definitions are configured in /modules/categorization/templates/components:

• catCloud: Standard category cloud component definition.
• catCloudWide: Category cloud component definition for base area.
• catCloudExtras: Category cloud component definition for extras area.

• categoryRSSFeed: Category RSS feed component.
  

Here's the category cloud (wide) and the RSS feed component.

Making components available

You can add categorization components in suitable areas in any template definition.

In the demo sites the catCloudWide and categoryRSSFeed components are available in base and extras areas. This is configured in the template prototype. 

The example configuration below adds the catCloud component to content area in the stkArticle template. The configuration is at STK > Template Definitions /pages/stkArticle/areas/main/areas/content/availableComponents.

Here's the category cloud in content area on an article page.

Dialog definitions

Dialog definitions are configured in /modules/categorization/dialogs:

• tabCategorization: Generic categorization tab to tag articles with categories. Can be added to any dialog
• catCloud: Category Cloud component dialog definition.

• categoryRSSFeed: Category RSS Feed component dialog definition.
  

Here's the categorization tab, RSS feed and category cloud dialogs.

Commands

The Categorization module provides example commands configured in /modules/categorization/commands/categorization:

• RemoveSiteCategories removes categories from pages on a specified path. It "un-tags" content, but does not remove the categories in Data > Categories. You could:
  
  • Use this command as is, for example 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.

• CategoryGeneratorCommand creates categories automatically and tags articles with them. Categories are generated for pages based on STK templates that have a category property of type content and subcategory property other than null. This command has no practical usage. It is provided to demonstrate the capabilities of the Categorization module and what you can do by creating custom commands.
  

Executing commands

The Categorization module installs sample configurations to execute the sample commands using observation and scheduling. Commands can also be executed by Groovy scripts.

The following properties are available for all commands and are used in the sample configurations:

• repository. Repository containing the pages to process, typically website.
• path. Root page to start processing. The command will process this page and any pages under it.
• UUID. Root page to start processing. Use either path or UUID, not both. If neither are specified then the root node in the specified repository is used.
  
  

Observation

The sample listener configuration for CategegoryGeneratorCommand is configured in /modules/observation/config/listenerConfigurations/generateCategories. See Observation module for more.

Scheduling

Sample scheduler configurations for both commands are configured in /modules/scheduler/config/jobs/removeCategories and /generateCategories. See Scheduler module for more.

Groovy scripts

You can also execute the commands in a Groovy script. Here's the script to execute the generateCategories command for the /demo-project/about/subsection-articles/large-article page.

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 based on STK templates that have a category property set to content and a subcategory property set to anything except null. Here's the result in the Data > Categories.

Creating a custom command

You can create your own commands by customizing the example commands. For example, you might want to customize CategoryGeneratorCommand 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.

Your command class must extend BaseRepositoryCommand . Register the custom command in the categorization catalog in /modules/categorization/commands/categorization. For more information see Commands.

Categories in the STK

Categorizing articles 

In the demo sites, categories display in the Page Header component of article pages. These pages are based on the stkArticle template. The generic tabCategorization tab is available in the header dialog. You can find the dialog definition in Templating Kit > Dialog Definitions /pages/article/stkArticleIntro.

To categorize article pages, in Website:

1. Open an article page for editing.
2. Click the edit icon on the Page Header toolbar.
3. Go to the Category tab of the dialog:
   
   1. Click Add and then Choose.
   2. Select the category in the Categories chooser.
   3. Click OK.
4. Repeat step 3 for each additional category.

The selected categories display in the Categories row.

Category overview page

The category links point to a category overview page. This is a way for visitors to discover related, interesting content. The page displays teasers to content tagged with the same category in content area and links to related categories in extras area. Related categories are set in the Data > Cateory. The overview page is based on the stkCategoryOverview template and the components in both areas are autogenerated. The stkCategoryOverview component renders in main area and the stkRelatedCategoriesLinkList component in extras area. For more information see Autogenerated components and Feature components. You can add the category overview page to any location in the website tree. It should not be included in the site navigation since the user navigates to it automatically by clicking a category in an article header, category cloud or related categories list.

You can find the relevant configurations in Templating Kit > Template Definitions:

• Page:  /pages/stkCategoryOverview.
• Components: /components/features/stkCategoryOverview and /stkRelatedCategoriesLinkList.

Here's the overview page for the Family category

Categorizing other pages

You can add the generic tabCategorization tab to any dialog using the extends mechanism.

The example configuration below adds the tab to the stkEventIntro dialog at Templating Kit > Dialog Definitions /pages/event/stkEventIntro/form/tabs.

Here's the Page Header component on a news pages tagged with categories.