com.day.cq.tagging

Interface Tag

All Superinterfaces:

Adaptable

@ProviderType
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 Summary

Modifier and Type	Method and Description
java.util.Iterator<Resource>	find()
long	getCount()
java.lang.String	getDescription()
java.lang.String	getGQLSearchExpression(java.lang.String property) Returns the GQL query constraint for searching this tag.
long	getLastModified() Returns the date of last modification of the tag.
java.lang.String	getLastModifiedBy() Return the user id that last modified the Tag or null if this information is not available.
java.lang.String	getLocalizedTitle(java.util.Locale locale)
java.util.Map<java.util.Locale,java.lang.String>	getLocalizedTitlePaths()
java.util.Map<java.util.Locale,java.lang.String>	getLocalizedTitles()
java.lang.String	getLocalTagID()
java.lang.String	getName()
Tag	getNamespace()
Tag	getParent()
java.lang.String	getPath()
java.lang.String	getTagID()
java.lang.String	getTitle()
java.lang.String	getTitle(java.util.Locale locale)
java.lang.String	getTitlePath()
java.lang.String	getTitlePath(java.util.Locale locale)
java.lang.String	getXPathSearchExpression(java.lang.String property) Returns the jcr xpath query constraint for searching this tag.
boolean	isNamespace()
java.util.Iterator<Tag>	listAllSubTags()
java.util.Iterator<Tag>	listChildren()
java.util.Iterator<Tag>	listChildren(Filter<Tag> filter)

Methods inherited from interface org.apache.sling.api.adapter.Adaptable

adaptTo

Method Detail

getName

java.lang.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

java.lang.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

java.lang.String getLocalTagID()

Returns:

Returns the tag path below a namespace. If this tag represents a namespace, null is returned.

getPath

java.lang.String getPath()

Returns:

Returns the full absolute path of a tag or a tag namespace.

getTitle

java.lang.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

java.lang.String getTitle(java.util.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

java.lang.String getLocalizedTitle(java.util.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

java.util.Map<java.util.Locale,java.lang.String> getLocalizedTitles()

Returns:

Returns all available localized titles.

See Also:

getLocalizedTitle(Locale)

getDescription

java.lang.String getDescription()

Returns:

Returns an optional description for a tag. If none is available, null is returned.

getTitlePath

java.lang.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

java.lang.String getTitlePath(java.util.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

java.util.Map<java.util.Locale,java.lang.String> getLocalizedTitlePaths()

Returns:

Returns all available localized title paths.

See Also:

getTitlePath(Locale)

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

java.lang.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

java.util.Iterator<Tag> listChildren()

Returns:

Lists the direct child tags for both tag namespaces and tag containers.

listChildren

java.util.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

java.util.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

java.util.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:

TagManager.find(String), TagManager.find(String, String[])

getXPathSearchExpression

java.lang.String getXPathSearchExpression(java.lang.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

java.lang.String getGQLSearchExpression(java.lang.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