Building Tagging into an AEM Application building-tagging-into-an-aem-application

For programmatically working with tags or extending tags within a custom AEM application, this page describes use of the

That interacts with the

For related information regarding tagging, see :

  • Administering Tags for information about creating and managing tags, and to which content tags have been applied.
  • Using Tags for information about tagging content.

Overview of the Tagging API overview-of-the-tagging-api

The implementation of the tagging framework in AEM allows management of tags and tag content using the JCR API . The TagManager ensures that tags entered as values on the cq:tags string array property are not duplicated, it removes TagIDs pointing to non-existing tags and updates TagIDs for moved or merged tags. TagManager uses a JCR observation listener that reverts any incorrect changes. The main classes are in the package:

  • JcrTagManagerFactory - returns a JCR-based implementation of a TagManager. It is the reference implementation of the Tagging API.
  • TagManager - allows for resolving and creating tags by paths and names.
  • Tag - defines the tag object.

Getting a JCR-based TagManager getting-a-jcr-based-tagmanager

To retrieve a TagManager instance, you must have a JCR Session and to call getTagManager(Session):

JcrTagManagerFactory jcrTagManagerFactory;

TagManager tagManager = jcrTagManagerFactory.getTagManager(session);

In the typical Sling context, you can also adapt to a TagManager from the ResourceResolver:

TagManager tagManager = resourceResolver.adaptTo(TagManager.class);

Retrieving a Tag object retrieving-a-tag-object

A Tag can be retrieved through the TagManager, by either resolving an existing tag or creating one:

Tag tag = tagManager.resolve("my/tag"); // for existing tags

Tag tag = tagManager.createTag("my/tag"); // for new tags

For the JCR-based implementation, which maps Tags onto JCR Nodes, you can directly use Sling’s adaptTo mechanism if you have the resource (for example, such as /content/cq:tags/default/my/tag):

Tag tag = resource.adaptTo(Tag.class);

While a tag may only be converted *from *a resource (not a node), a tag can be converted *to *both a node and a resource :

Node node = tag.adaptTo(Node.class);
Resource node = tag.adaptTo(Resource.class);
Directly adapting from Node to Tag is not possible, because Node does not implement the Sling Adaptable.adaptTo(Class) method.

Getting and Setting Tags getting-and-setting-tags

// Getting the tags of a Resource:
Tag[] tags = tagManager.getTags(resource);

// Setting tags to a Resource:
tagManager.setTags(resource, tags);

Searching for Tags searching-for-tags

// Searching for the Resource objects that are tagged with the tag object:
Iterator<Resource> it = tag.find();

// Retrieving the usage count of the tag object:
long count = tag.getCount();

// Searching for the Resource objects that are tagged with the tagID String:
 RangeIterator<Resource> it = tagManager.find(tagID);
The valid RangeIterator to use is:

Deleting Tags deleting-tags


Replicating Tags replicating-tags

It is possible to use the replication service ( Replicator) with tags because tags are of type nt:hierarchyNode:

replicator.replicate(session, replicationActionType, tagPath);

Tagging on the Client Side tagging-on-the-client-side

The form widget CQ.tagging.TagInputField is for entering tags. It has a popup menu for selecting from existing tags, includes auto-completion and many other features. Its xtype is tags.

The Tag Garbage Collector the-tag-garbage-collector

The tag garbage collector is a background service that cleans up the tags that are hidden and unused. Hidden and unused tags are tags below /content/cq:tags that have a cq:movedTo property and are not used on a content node - they have a count of zero. By using this lazy deletion process, the content node (that is, the cq:tags property) does not have to be updated as part of the move or the merge operation. The references in the cq:tags property are automatically updated when the cq:tags property is updated, for example, through the page properties dialog.

The tag garbage collector runs by default once a day. You can configure it at:


Tag Search and Tag Listing tag-search-and-tag-listing

The search for tags and the tag listing work as follows:

  • The search for TagID searches for the tags that have the property cq:movedTo set to TagID and follows through the cq:movedTo TagIDs.

  • The search for tag Title only searches the tags that do not have a cq:movedTo property.

Tags in Different Languages tags-in-different-languages

As described in the documentation for administering tags, in the section Managing Tags in Different Languages, a tag titlecan be defined in different languages. A language sensitive property is then added to the tag node. This property has the format jcr:title.<locale>, for example, for the French translation. The <locale> must be a lower case ISO locale string and use “_” instead of “-”, for example: de_ch.

When the Animals tag is added to the Products page, the value stockphotography:animals is added to the property cq:tags of the node /content/geometrixx/en/products/jcr:content. The translation is referenced from the tag node.

The server-side API has localized title-related methods:


    • getLocalizedTitle(Locale locale)
    • getLocalizedTitlePaths()
    • getLocalizedTitles()
    • getTitle(Locale locale)
    • getTitlePath(Locale locale)

    • canCreateTagByTitle(String tagTitlePath, Locale locale)
    • createTagByTitle(String tagTitlePath, Locale locale)
    • resolveByTitle(String tagTitlePath, Locale locale)

In AEM, the language can be obtained either from the page language or from the user language:

  • to retrieve the page language in a JSP:

    • currentPage.getLanguage(false)
  • to retrieve the user language in a JSP:

    • slingRequest.getLocale()

The currentPage and slingRequest are available in a JSP through the <cq:definedObjects> tag.

For tagging, localization depends on the context as tag titlescan be displayed in the page language, in the user language, or in any other language.

Adding a New Language to the Edit Tag Dialog adding-a-new-language-to-the-edit-tag-dialog

The following procedure describes how to add a language (Finnish) to the Tag Edit dialog:

  1. In CRXDE, edit the multi-value property languages of the node /content/cq:tags.

  2. Add fi_fi - which represents the Finnish locale - and save the changes.

The new language (Finnish) is now available in the tag dialog of the page properties and in the Edit Tag dialog when editing a tag in the Tagging console.

The new language must be one of the AEM recognized languages. That is, it must be available as a node below /libs/wcm/core/resources/languages.
Installing tagging related out-of-the-box content via an official update package (including Service Packs, Security Service Packs, Extended Feature Packs, Cumulative Feature Packs, patches and the like), resets the languages property of the /content/cq:tags node to default. Therefore, it is necessary to add it from the properties before installation.