Last Updated: Apr 13, 2022
documentation for the dotCMS Content Management System

Tags are a method of labeling content with one or more terms so that content can be found and extracted dynamically for display on a page.

  • Tags may be single words, or phrases of multiple words separated by spaces.
  • Multiple tags on the same content are entered into the same field separated by a comma followed by a space.
    • e.g. Tag1, Tag2 as opposed to Tag1,Tag2.

Tags may be entered by any content creator on any content which contains a Tag field. There are no limitations to what Tags a content creator may add to a piece of content; creators may select from existing Tags, or type in new Tags, creating a new Tag in the process.

Please see the following sections for more information:

Tags, Categories, and Relationships

Since content contributors can Tag content with any words of their choice, Tags alone cannot be used to reliably pull particular types of dynamic content, since you can not know in advance what Tags will be created.

When content contributors need to be limited to a fixed set of labels, or when content contributions are dependent on pre-existing content, Categories or Relationships usually offer better options for labeling and aggregating data. In many cases, tagging is used in combination with categories and/or relationships on the same Content Type.

Another alternative to using pre-defined Categories or Relationships is queries which perform a dynamic pull of Tags which have been created on Content. For more information, please see Tag Clouds, below.

Tag Fields

When users need to find content by keyword search, a Tag field should be added to the Content Type. Tag fields assist in the consistent use of labels by suggesting terms as a content contributor types into a Tag field.

As content is entered, a pool of auto-displayed suggested Tags help keep Tags consistent and ensure different content contributors use the same naming conventions. Users may select tags from the suggested list (using the mouse or keyboard), or may continue typing to create a new tag which has not yet been used.

The Tags field and Suggested Tags popup

Note: The suggested tags shows both tags previously entered into content, and Persona tags, with the Persona tags at the top of the list. This enables you to easily tag content which is of interest to your defined Personas, without knowing which individual tags are associated with each individual Persona. For more information on Personas and personalized content, please see the Personalization documentation section.

Tag Repositories

Tag Repositories are collections of Tags that are used by one or more Hosts. Tag Repositories enable multi-tenant dotCMS installations to ensure that, when content contributors add content with a Tag field, they are not overwhelmed with suggested Tags from all hosts managed by a dotCMS instance.

The Tag Manager

Tag Repositories can be managed from the Tag Manager, which can be accessed from the Content Types drop down menu. Each individual Host has its own Tag Storage field where a specific Tag Repository can be defined.

Selecting the Tag Manager

Webmasters with access to the Tag Manager can delete, edit, import and export Tags on any Tag Repository.

The Tag Manager

The Global Tag Repository

In addition to the Tag Repositories on each individual host, there is also a Global Tag Repository available to All Hosts on a dotCMS instance. This is the default location for all new Tags entered by users into Tag fields in Content.

To display the Tags in the Global Tag Repository, check the Show Global Tags box in the Tag Manager.

The Show Global Tags checkbox

Using Tag Repositories

Since there can multiple Tag Repositories, there are several different ways a Host's Tags can be stored, and the same site can store and access Tags from multiple different Tag Repositories. Each Site can:

  1. Have its own Tag Repository.
  2. Use the Tag Repository of another Host.
    • When the Tag Storage field of one Host is set to a second Host, all tags created on the first Host will be stored in the second Host's tag repository, but the content will still be stored on the first Host.
  3. Store Tags and Content on another Host.
    • When the Content Type Host or Folder field) is set to a second Host, the both the Content and Tags for that content are stored on the second Host.
  4. Store all tags in the Global (All Sites) Tag Repository.
    • This is the default behavior.
    • When the Tag Storage field of a Host is set to All Hosts, all tags for the Host will be stored in the Global Tag Repository.

The Tag Storage field

Note: A Host will only be available in the Tag Storage field list if the site is started.

Important Note: Global vs. Host-Specific Tags

Only Content Types that have both a Tag field and a Host/Folder field can save or utilize Tags in a given Tag Repository (other than the Global Tag Repository, which is always available to all Hosts).

To save content to a the Tag Repository of a specific Host, the following conditions must be met:


  • If any of these conditions are not met, then the Tags will automatically be stored in the Global Tag Repository.
    • So to intentionally keep Tag storage centralized, simply leave all host Tag Storage fields set to All Hosts.

Content Tag location

Matching Tags

When a content contributor types into a Tag field on a given Host, the typed text will be matched to all Tags that are available on that Host. This includes all of the following locations:

Tag Clouds

Tag clouds are a popular feature in many web sites which can be used to display the most popular Tag words associated with multiple pieces of content. The following ElasticSearch aggregations query can be used to retrieve a list of tags to display in a Tag cloud:

## Set the tagContentType to the Velocity variable name of the Content Type to generate the Tag Cloud for

## Set the number of tags to display in the cloud

## Set the ES query string (using ES Aggregates)
        "query": {
            "query_string": {
                "query": "+contenttype:$tagContentType"
        "aggs" : {
            "tag" : {
                "terms" : {
                    "field": "tags",
                    "size" : $numOfTags

## Retrieve and display each of the tags retrieved by the query

#set($results = $estool.search($render.eval($esQuery)))
#set($tagCloud = $json.generate($results.response))

<div class="nav-collapse">
  <div id="topicMenu" class="tagCloud main-nav">
      #foreach($tag in $tagCloud.aggregations.asMap.tag.buckets)
          <a href="/$tagContentType/?tag=$tag.key">$tag.key ($tag.docCount)</a>

The Tags returned from this query may then be processed and displayed in whatever manner you wish to create a Tag cloud, Tag list, or other Tag display.

For more information on performing aggregation queries, please see the Elasticsearch Aggregations documentation.

Troubleshooting Tags

When a content contributor types into a Tag field, there are two possible problems you may encounter:

If a tag you do expect to match does not display in the selection list:

  • Make sure you have selected the correct Host in the Host selection list.
  • Check to make sure that the tag exists in the appropriate source (where you expect it to be found) from the above list.
  • If necessary, add or move the Tag you expect to match, to ensure it matches as expected on the given Host.
    • Note: To move a Tag, you must delete it from one Tag Repository and add it to another.

If a Tag which you do not expect to match does display in the selection list:

  • Make sure you have selected the correct Host in the Host selection list.
  • Check each of the above sources, in order, to determine where the tag is located.
    • Open the Tag Manager, check the Show Global Tags box, and search for the Tag.
    • Open the Content tab, and select each Persona Content Type in turn.
      • For each Persona Content Type, open each Persona listed, and view the Key Tag and Other Tags fields.
  • If necessary, delete or move the matching Tag to ensure the Tag does not match on the given Host.
    • Note: To move a Tag, you must delete it from one Tag Repository and add it to another.

On this page


We Dig Feedback

Selected excerpt: