Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
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.
Categories are stored in the Data module and managed in AdminCentral in Data > Category.
To create a category:
You can organize categories in hierarchical structures of categories and/or folders.
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.
The RSS feed component uses the functionality of the RSS Aggregator module.
Here's the category cloud (wide) and the RSS feed component.
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 are configured in /modules/categorization/dialogs
:
tabCategorization
: Generic categorization tab to tag articles with categories. Can be added to any dialogcatCloud
: Category Cloud component dialog definition.categoryRSSFeed
: Category RSS Feed component dialog definition.
Here's the categorization tab, RSS feed and category cloud dialogs.
The Categorization module provides example commands configured in /modules/categorization/commands
/categorization
:
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.
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.The sample listener configuration for CategegoryGeneratorCommand
is configured in /modules/observation/config/listenerConfigurations/generateCategories.
See Observation module for more.
Sample scheduler configurations for both commands are configured in /modules/scheduler/config/jobs/removeCategories
and /generateCategories
. See Scheduler module for more.
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.
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.
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:
The selected categories display in the Categories row.
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:
/pages/stkCategoryOverview
./components/features/stkCategoryOverview and /stkRelatedCategoriesLinkList
.Here's the overview page for the Family category
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.