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 :

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 com.day.cq.tagging package:

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):

@Reference
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);

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);

Deleting Tags deleting-tags

tagManager.deleteTag(tag);

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:

http://localhost:4502/system/console/configMgr/com.day.cq.tagging.impl.TagGarbageCollector

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

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

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, jcr:title.fr 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:

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

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:

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.