Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

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

The RSS feed component uses the functionality of the RSS Aggregator module. See Category RSS Feed component for more information.

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.

Node nameValue
 pages 

 stkArticle

 

 areas

 

 main

 

 areas

 

 content

 

 availableComponents

 

 stkTextImage

 

 catCloud

 

 id

categorization:components/catCloud

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

  • 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 nameValue

     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.

Node nameValue
 modules 

 observation

 

 config

 

 listenerConfigurations

 

 generateCategories

 

 listener

 

 command

 

 class

info.magnolia.module.categorization.commands.CategoryGeneratorCommand

 repository

 website

 class

 info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener

 nodeType

 mgnl:content

 active

 false

 description

 generates categories for new added page

 eventTypes

 NODE_ADDED

 includeSubNodes

 true

 path

 /demo-project

 repository

 website

Scheduling

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

Node nameValue
 modules 

 scheduler

 

 config

 

 jobs

 

 removeCategories

 

 params

 

 path

/demo-project

 repository

 website

 active

 false

 catelog

 categorization

 command

 removeCategories

 cron

0 0 * * * *

 description

removes categories from website

 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.

Node nameValue

 pages

 

 event

 

 stkEventIntro

 

 form

 

 tabs

 

 tabMain

 

 tabCategorization

 

 extends

/modules/categorization/dialogs/generic/tabCategorization

 i18nBasename

info.magnolia.module.templatingkit.messages

 label

 dialogs.pages.event.stkEventHeader.label

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.

Node nameValue

 modules

 

 contacts

 

 apps

 

 contacts

 

 subApps

 

 browser

 

 detail

 

 editor

 

 form

 

 tabs

 

 personal

 

 address

 

 contactDetails

 

 tabCategorization

 

 extends

/modules/categorization/dialogs/generic/tabCategorization

Here's the Categories tab in the detail subapp.