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 the features include category cloud components, category overview pages and category RSS feeds.

Creating categories

To create a category:

1. Launch the app at Manage > Categories.
2. In the browser subapp, click Add category.
3. In the detail subapp, 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 the category appears in a category cloud component.
   4. Related Categories. Displayed in the Related Categories Link List component in the extras area on a 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 fro extras area.

• categoryRSSFeed: Category RSS feed component.

  Node name
  categorization
  templates
  components
  catCloud
  catCloudWide
  catCloudExtras
  categoryRSSFeed

Here's the category cloud (wide) and 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 form or dialog
• catCloud: Category Cloud component dialog definition.

• categoryRSSFeed: Category RSS Feed component dialog definition.

  Node name
  categorization
  dialogs
  generic
  tabCagorization
  catCloud
  categoryRSSFeed

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 from the Categories app. 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.

  Node name	Value
  categorization
  commands
  categorization
  removeCategories
  class	info.magnolia.module.categorization.commands.RemoveSiteCategories
  generateCategories
  class	info.magnolia.module.categorization.commands.CategoryGeneratorCommand

Executing commands

The Categorization module installs sample configurations for executing the sample commands using observation and scheduling. Commands can also be executed by actions and 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 in/modules/observation/config/listenerConfigurations/generateCategories.

Scheduling

There are sample scheduler configurations for both commands in /modules/scheduler/config/jobs/removeCategories and /generateCategories.

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 Categories app.

Creating a custom command

You can create your own category 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 are displayed 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 STK > Dialog Definitions /pages/article/stkArticleIntro.

To categorize article pages, in the Pages app:

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 Select new.
   2. Select the category in the Categories chooser.
   3. Click Choose.
4. Repeat step 3 for each additional category.

The selected categories display in the Categories line.

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 main area and links to related categories in extras area. Related categories are set in the Categories app. This 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 at STK > Template Definitions:

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

Here's the 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 STK > Dialog Definitions /pages/event/stkEventIntro/form/tabs.

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

Categorizing other content types

You can add the generic tabCategorization tab to forms in other apps using the extends mechanism The example configuration below adds the tab to the detail subapp of the Contacts app. The configuration is in /modules/contacts/apps/contacts/subApps/detail/editor/form/tabs.

Here's the Categories tab in the detail subapp.