Category Field documentation for the dotCMS Content Management System

Category fields allow users to assign one or more Category values to a content item, from a top-level Category you choose.

Each top-level Category contains a list of Sub-Categories which may be selected within that Category. Category fields will only allow you to select from Categories which have already been created. For more information, please see the Adding New Categories documentation.

Steps to Add a Category Field

Perform the following steps to add a category field to a Content Type:

  1. Select the Content Types tab to display a list of Content Types.
  2. Select the title of the Content Type you wish to add the category field to.
  3. Click the +Add New Field button.
  4. Select Category from the Display Type selection box.
  5. Use the Category select box to choose the desired category.
  6. Fill out the other values for the new field as desired.
  7. Save the category field, and position the field in the Content Type field order as desired.

To verify the operation of the category field, select the Content Search tab, and add a new piece of content of the same Content Type.

Advantages and Limitations of Using Categories in Content

  • Each category field will allow content contributors to select from only one top-level category.
    • If you wish for content contributors to be able to select from multiple categories on a single piece of content, you must add multiple category fields to that content type.
  • Category fields always allow content contributors to select multiple category labels for a single piece of content.
    • If you wish to limit content contributors to only select a single label for each piece of content, consider using a Select field instead, or using a Custom Field which displays the values of the Category using a Javascript pull-down list control.
  • You may only assign each Category field to a single Category field on the same Content Type.
    • If you would like to have two different Category fields which provide the same values to choose from, consider duplicating the Category (so you have two Categories with the same values but different names and keys), or using a Custom Field to pull the category values and display them in a single-select or multi-select Javascript control.

For more information on Categories, please see the Categories documentation.

How Category Permissions affect Category Fields

Categories have permissions, and the permissions on a category must be set to be viewable by any content contributors who will add content of the appropriate Content Type.

  • If a content contributor does not have view permission to the Category specified in the Category field, they will not be able to select a value for that field when adding or editing content.
    • If the Category field is Required, this means that the user will not be able to add new content, since they will not be able to add a value for the required Category field.
  • If a user does not have permission to view any Sub-Categories within a Category, they will not be able to select those Sub-Categories on any content item with a Category field that uses that Category (but they will be able to select other Sub-Categories that they do have view permissions for).