Package 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 {base.path}/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
{base.path}/dam/fruit/apple/braeburn

Shorter example: color/red

namespace
default
tag local ID
color/red
container tag
color
leaf tag
red
absolute tag path
{base.path}/default/color/red

Simplest example: sky

namespace
default
tag local ID
sky
container tag
(none)
leaf tag
sky
absolute tag path
{base.path}/default/sky

Namespace example: dam:

namespace
dam
tag local ID
(none)
container tag
(none)
leaf tag
(none, the namespace)
absolute tag path
{base.path}/dam

  • Method Details

    • getName

      String getName()
      Returns:
      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:
      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:
      Returns the tag path below a namespace. If this tag represents a namespace, null is returned.

    • getPath

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

    • getTitle

      String getTitle()
      Returns:
      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)
      Parameters:
      locale - given locale
      Returns:
      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)
      Parameters:
      locale - given locale
      Returns:
      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:
      Returns all available localized titles.
      See Also:

    • getDescription

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

    • getTitlePath

      String getTitlePath()
      Returns:
      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)
      Parameters:
      locale - given locale
      Returns:
      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:
      Returns all available localized title paths.
      See Also:

    • getCount

      long getCount()
      Returns:
      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:
      Returns true if this tag object refers to a tag namespace.

    • getNamespace

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

    • getParent

      Tag getParent()
      Returns:
      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()
      Returns:
      Lists the direct child tags for both tag namespaces and tag containers.

    • listChildren

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

    • listAllSubTags

      Iterator<Tag> listAllSubTags()
      Returns:
      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:
      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:

    • 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":"{base.path}/default/c" OR "cq:tags":"c/b" OR "cq:tags":"{base.path}/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