Adding New Categories

Last Updated: Aug 9, 2021
documentation for the dotCMS Content Management System

Categories are fixed lists of labels that can be assigned to fields in Content Type.  Each parent and child category has it's own permissions and therefore is visible or “usable” based upon a content contributor's role permissions.  For more information, please refer to our Category Permissions documentation.

To add a new category to the system first click on the Content Types tab and select “Categories” from the drop down menu.

The Category Manager

On the backend of dotCMS lists all Top Level categories currently in the system and allows users to perform the following actions:

Edit an existing Category
  1. Click the title of the Category to view it's “child” Categories.
  2. Click the Properties tab.
Add a new parent Category
  1. Select Content Model -> Categories to view the top-level Categories.
  2. Click the +Add button.
  3. Enter the Category Name, Key (optional), and Keywords (optional), of the new parent Category.
Add child Categories to an existing parent Category
  1. Click the title of a Category to view “child” Categories assigned to it.
  2. Click the +Add button to add new child Categories.
Delete a category
  1. Select the checkbox to the left of the Category or Categories to be deleted.
  2. Click the purple menu button on the top left of the screen.
  3. Select Delete from the Action menu.
Re-order Categories
  1. Change the numbers in the “Sort Order” column.
  2. Click the Reorder button.

Category Properties

All Categories (both top-level Categories and child Categories) has the following properties:

Category NameRequiredNot UniqueName of the Category.
Category Unique KeyOptionalUniqueValue that can be used to reference the category dynamically when searching for content labeled by as specific category type. Note: Since Category Names may not be unique, it is best practice to refer to the Category Unique Key instead of the Name when calling a category name with Velocity code.
KeywordsOptionalNot UniqueDescriptive keywords assigned to the category for back-end searching.

Creating Child Categories

After you have saved a parent Category, click the name of that parent Category to begin adding “child” Categories under the parent.

When you create a Category Field in a Content Type, you select a top level Category for that field, and the “child” Categories are the Category selections that content contributors will see when editing content of that Content Type.

Creating Category Hierarchies

You may create any number of levels of Categories under a single Category, creating a hierarchy of Categories as deep as you wish. Whenever a content contributor selects a Category, they may select any child Category or deeper nested Category within the selected top-level Category. For more information, please see the Adding a Category Field to a Content Type documentation.

The example below shows three “child” categories (Consulting, Research, Training), that have been added to the “Product Types” parent category.

Note: Although you can create as many levels of Categories as you wish, for usability purposes it is not recommended to nest Categories more than 3 or 4 levels deep.

On this page


We Dig Feedback

Selected excerpt: