Tagging

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.

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.

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

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.

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.

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:

• The Host Tag Storage field must be set to a specific Host.
  • It can not be set to All Hosts.
• The Content Type must have a Tag field.
• The Content Type must have a Host/Folder field.
  • This defines which Host both the content AND the content Tag(s) will be stored on.

Note:

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

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:

• The Host's own Tag Repository.
• Any Tag Repositories shared with another Host.
• The Global (All Sites) Tag Repository.
• Any Persona Key Tags that match the typed text.
• Any Personas with associated tags that match the typed text.

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($tagContentType="news")

## Set the number of tags to display in the cloud
#set($numOfTags=20)

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

## 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>
      #end
  </div>
</div>

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.