For the purpose of programmatically working with tags or extending tags within a custom AEM application, this document describes use of the
that interacts with the
For related information regarding tagging:
The implementation of the tagging framework in AEM allows management of tags and tag content using the JCR API. TagManager
ensures that tags entered as values on the cq:tags
string array property are not duplicated, it removes TagID
s pointing to non-existing tags and updates TagID
s 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.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);
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 /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 the tags of a Resource:
Tag[] tags = tagManager.getTags(resource);
// Setting tags to a Resource:
tagManager.setTags(resource, 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:
com.day.cq.commons.RangeIterator
tagManager.deleteTag(tag);
It is possible to use the replication service (Replicator
) with tags because tags are of type nt:hierarchyNode
:
replicator.replicate(session, replicationActionType, tagPath);
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 (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:
http://<host>:<port>/system/console/configMgr/com.day.cq.tagging.impl.TagGarbageCollector
The search for tags and the tag listing work as follows:
TagID
searches for the tags that have the property cq:movedTo
set to TagID
and follows through the cq:movedTo
TagID
s.cq:movedTo
property.A tag title
can be defined in different languages. A language sensitive property is then added to the tag node. This property has the format jcr:title.<locale>
, e.g. jcr:title.fr
for the French translation. <locale>
must be a lower case ISO locale string and use underscore (_
) instead of hyphen/dash (-
), for example: de_ch
.
For example 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/wknd/en/products/jcr:content
. The translation is referenced from the tag node.
The server-side API has localized title
-related methods:
com.day.cq.tagging.Tag
getLocalizedTitle(Locale locale)
getLocalizedTitlePaths()
getLocalizedTitles()
getTitle(Locale locale)
getTitlePath(Locale locale)
com.day.cq.tagging.TagManager
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.
For tagging, localization depends on the context as tag titles
can be displayed in the page language, in the user language or in any other language.
The following procedure describes how to add a new language (e.g. Finnish) to the Tag Edit dialog:
languages
of the node /content/cq:tags
.fi_fi
, which represents the Finnish locale, and save the changes.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 needs to be one of the AEM recognized languages, i.e. it needs to be available as a node below /libs/wcm/core/resources/languages
.