com.day.cq.tagging
Interface Tag

All Superinterfaces:
Adaptable

public interface Tag
extends Adaptable

A Tag is a keyword or label that can be assigned to any content. Multiple tags can be assigned to a content element, which allows to classify them by several different categorizations at the same time, as opposed to a single hierarchical model. Tags became popular with the wave of Web 2.0 websites, but the CQ5 tagging model goes even further in flexibility by offering both namespaces, hierarchical tags and the ability to restrict users to use only predefined tags.

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 = tagManger.resolve("my/tag"); // for existing tags
 
 Tag tag = tagManger.createTag("my/tag"); // for new tags
 
For the JCR-based implementation, which maps tags onto JCR Nodes, you can directly use Sling's apaptTo mechanism if you happen to have the resource (eg. such as /etc/tags/default/my/tag):

 Tag tag = resource.adaptTo(Tag.class);
 
(Note: adapting from Node to a tag is not possible directly, since Node does not implement the Adaptable.adaptTo(Class) method).
These conversions are vice-versa, you can get the node and resource back from a tag by calling:

 Node node = tag.adaptTo(Node.class);
 
 Resource node = tag.adaptTo(Resource.class);
 

Overview of Tagging concepts

A tag can be a simple word (eg. beautiful) or represent a hierarchical taxonomy (eg. planet/earth, meaning both the generic planet and the more specific earth). Tags are typically identified by strings, either by a so-called short tag ID (typical case) or an absolute path to the tag (a rather rare case). A tag has meta information such as a title (that should be displayed in UIs instead of the tag ID, if present) and a description.

Furthermore, container tags (or super-tags) in a taxonomy serve as the sub-summation of all sub-tags, eg. content tagged with fruit/banana is considered to be tagged with fruit as well, ie. searching for content just tagged with fruit would find the ones with fruit/banana as well.

Finally, namespaces allow to group things. The most typical use-case is to have a namespace per (web)site (eg. public, internal, portal, etc.) or for larger applications (eg. wcm, dam, collab) - but you are free to use namespaces for whatever you need. Namespaces are used in the UI to only show the subset of tags (ie. tags of a certain namespace) that is applicable for the current content.

Tagging Terminology

A tag ID is either a shorthand or an absolute path refering to a tag. It must be resolved to an absolute tag path. A tag is contained within a certain namespace (which is default if no namespace is given in the tag ID). The part after the namespace is called the local tag ID and can be a path itself. container tags have sub-tags that represent a hierarchical order in the taxonomy. They can be used as tags (an actually referenced tag) like any other tag below a namespace (eg. tagging something with planet is not forbidden if it has sub-tags like planet/earth and planet/mars for example).

Examples of Tag IDs

Fully qualified tag ID: dam:fruit/apple/braeburn

namespace
dam
tag local ID
fruit/apple/braeburn
container tags
fruit and apple
leaf tag
braeburn
absolute tag path
/etc/tags/dam/fruit/apple/braeburn

Shorter example: color/red

namespace
default
tag local ID
color/red
container tag
color
leaf tag
red
absolute tag path
/etc/tags/default/color/red

Simplest example: sky

namespace
default
tag local ID
sky
container tag
(none)
leaf tag
sky
absolute tag path
/etc/tags/default/sky

Namespace example: dam:

namespace
dam
tag local ID
(none)
container tag
(none)
leaf tag
(none, the namespace)
absolute tag path
/etc/tags/dam


Method Summary
 Iterator<Resource> find()
          Returns all nodes tagged with this tag.
 long getCount()
          Returns the usage count of the tag, which can be used for tag cloud and other visualisations.
 String getDescription()
          Returns an optional description for a tag.
 String getGQLSearchExpression(String property)
          Returns the GQL query constraint for searching this tag.
 long getLastModified()
          Returns the date of last modification of the tag.
 String getLastModifiedBy()
          Return the user id that last modified the Tag or null if this information is not available.
 String getLocalizedTitle(Locale locale)
          Returns a localized title for the given locale, if available.
 Map<Locale,String> getLocalizedTitlePaths()
          Returns all available localized title paths.
 Map<Locale,String> getLocalizedTitles()
          Returns all available localized titles.
 String getLocalTagID()
          Returns the tag path below a namespace.
 String getName()
          Returns the node name, ie. either the name of the namespace if this Tag represents a tag namespace, the name of the part of a taxonomy (eg.
 Tag getNamespace()
          Returns the tag namespace inside which this tag resides as tag object.
 Tag getParent()
          Gets the parent of this tag.
 String getPath()
          Returns the full absolute path of a tag or a tag namespace.
 String getTagID()
          Returns the short tag ID.
 String getTitle()
          Returns a title that should be displayed instead of the tag name or tag id.
 String getTitle(Locale locale)
          Returns a localized title for the given locale, if available.
 String getTitlePath()
          Returns the title variant of the tag ID: a path made up of the single titles of the namespace and all tags leading to this tag.
 String getTitlePath(Locale locale)
          Returns the localized title variant of the tag ID: a path made up of the single titles of the namespace and all tags leading to this tag.
 String getXPathSearchExpression(String property)
          Returns the jcr xpath query constraint for searching this tag.
 boolean isNamespace()
          Returns true if this tag object refers to a tag namespace.
 Iterator<Tag> listAllSubTags()
          Lists all sub-tags, ie. children, grand-children and so on.
 Iterator<Tag> listChildren()
          Lists the direct child tags for both tag namespaces and tag containers.
 Iterator<Tag> listChildren(Filter<Tag> filter)
          Lists the child tags for both tag namespaces and tag containers, but only those included by a filter.
 
Methods inherited from interface org.apache.sling.api.adapter.Adaptable
adaptTo
 

Method Detail

getName

String getName()
Returns the node name, ie. either the name of the namespace if this Tag represents a tag namespace, the name of the part of a taxonomy (eg. "fruit" in "fruit/apple") or the name of the tag itself.


getTagID

String getTagID()
Returns the short tag ID. If namespace is default, it will be left out. If this tag represents a namespace, null is returned.


getLocalTagID

String getLocalTagID()
Returns the tag path below a namespace. If this tag represents a namespace, null is returned.


getPath

String getPath()
Returns the full absolute path of a tag or a tag namespace.


getTitle

String getTitle()
Returns a title that should be displayed instead of the tag name or tag id. If no separate title is available, the tag name is returned.


getTitle

String getTitle(Locale locale)
Returns a localized title for the given locale, if available. Given a locale such as "de_CH", this will return in this order based on availability:
  1. country-specific title "de_CH"
  2. language title "de"
  3. default tag title
If locale is null, this will return the same as getTitle(). If you only want localized titles (and null if no localization exists), use getLocalizedTitle(Locale).


getLocalizedTitle

String getLocalizedTitle(Locale locale)
Returns a localized title for the given locale, if available. Given a locale such as "de_CH", this will return in this order based on availability:
  1. country-specific title "de_CH"
  2. language title "de"
  3. null
If no localization is found, this returns null. If a fallback to the default getTitle() is desired, use getTitle(Locale) instead.


getLocalizedTitles

Map<Locale,String> getLocalizedTitles()
Returns all available localized titles.

See Also:
getLocalizedTitle(Locale)

getDescription

String getDescription()
Returns an optional description for a tag. If none is available, null is returned.


getTitlePath

String getTitlePath()
Returns the title variant of the tag ID: a path made up of the single titles of the namespace and all tags leading to this tag.


getTitlePath

String getTitlePath(Locale locale)
Returns the localized title variant of the tag ID: a path made up of the single titles of the namespace and all tags leading to this tag. Given a locale such as "de_CH", this will return in this order based on availability:
  1. country-specific title path "de_CH"
  2. language title path "de"
  3. default tag title path
If locale is null, this will return the same as getTitlePath().


getLocalizedTitlePaths

Map<Locale,String> getLocalizedTitlePaths()
Returns all available localized title paths.

See Also:
getTitlePath(Locale)

getCount

long getCount()
Returns the usage count of the tag, which can be used for tag cloud and other visualisations. An implementation does not have to ensure a completely exact number, so caching is possible.


getLastModified

long getLastModified()
Returns the date of last modification of the tag.

Returns:
utc millis of the last modification date

getLastModifiedBy

String getLastModifiedBy()
Return the user id that last modified the Tag or null if this information is not available.

Returns:
user id or null

isNamespace

boolean isNamespace()
Returns true if this tag object refers to a tag namespace.


getNamespace

Tag getNamespace()
Returns the tag namespace inside which this tag resides as tag object.


getParent

Tag getParent()
Gets the parent of this tag. This could be either a tag container, a tag namespace or null if this object is a tag namespace.


listChildren

Iterator<Tag> listChildren()
Lists the direct child tags for both tag namespaces and tag containers.


listChildren

Iterator<Tag> listChildren(Filter<Tag> filter)
Lists the child tags for both tag namespaces and tag containers, but only those included by a filter.


listAllSubTags

Iterator<Tag> listAllSubTags()
Lists all sub-tags, ie. children, grand-children and so on. Note that the returned list might not be in order.


find

Iterator<Resource> find()
Returns all nodes tagged with this tag. These are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag. Returns null in case of errors.

See Also:
TagManager.find(String), TagManager.find(String, String[])

getXPathSearchExpression

String getXPathSearchExpression(String property)
Returns the jcr xpath query constraint for searching this tag. This will return something like relative/path/@cq:tags = "tag:id" or relative/path/@cq:tags = "tag:previous/id" considering child tags and different tag ids because of moved or merged tags.

Parameters:
property - relative path to cq:tags property, e.g. cq:tags or relative/path/@cq:tags
Returns:
an xpath expression to be used inside a constraint (//*[...])

getGQLSearchExpression

String getGQLSearchExpression(String property)
Returns the GQL query constraint for searching this tag. This will return something like "cq:tags":"c" OR "cq:tags":"/etc/tags/default/c" OR "cq:tags":"c/b" OR "cq:tags":"/etc/tags/default/c/b" considering child tags and different tag ids because of moved or merged tags.

Parameters:
property - relative path to cq:tags property, e.g. cq:tags or relative/path/@cq:tags
Returns:
a GQL (org.apache.jackrabbit.commons.query.GQL) expression


Copyright © 2011-2013 Adobe Systems Incorporated. All Rights Reserved.