Building Tagging into an AEM Application
For the purpose of 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, as well as to which content tags have been applied.
- Using Tags for information about tagging content.
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:
- 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
To retrieve a TagManager instance, you need to 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
A Tag can be retrieved through the TagManager , by either resolving an existing tag or creating a new 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 (e.g. such as /etc/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.
Tagging on the Client Side
CQ.tagging.TagInputField is a form widget 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 is a background service that cleans up the tags that are hidden and unused. Hidden and unused tags are tags below /etc/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 (i.e. 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, e.g. through the page properties dialog.
The tag garbage collector runs by default once a day. This can be configured at:
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.