Interface Tag
-
- All Superinterfaces:
Adaptable
public interface Tag extends Adaptable
ATag
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 theTagManager
, by either resolving an existing tag or creating a new one:
For the JCR-based implementation, which maps tags onto JCRTag tag = tagManger.resolve("my/tag"); // for existing tags Tag tag = tagManger.createTag("my/tag"); // for new tags
Node
s, you can directly use Sling's apaptTo mechanism if you happen to have the resource (eg. such as{base.path}/default/my/tag
):
(Note: adapting fromTag tag = resource.adaptTo(Tag.class);
Node
to a tag is not possible directly, sinceNode
does not implement theAdaptable.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 genericplanet
and the more specificearth
). 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 withfruit
as well, ie. searching for content just tagged withfruit
would find the ones withfruit/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 withplanet
is not forbidden if it has sub-tags likeplanet/earth
andplanet/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
andapple
- 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
All Methods Instance Methods Abstract Methods Modifier and Type Method 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 ornull
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)
-
-
-
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:
- country-specific title "de_CH"
- language title "de"
- default tag title
null
, this will return the same asgetTitle()
. If you only want localized titles (andnull
if no localization exists), usegetLocalizedTitle(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:
- country-specific title "de_CH"
- language title "de"
null
null
. If a fallback to the defaultgetTitle()
is desired, usegetTitle(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:
- country-specific title path "de_CH"
- language title path "de"
- default tag title path
null
, this will return the same asgetTitlePath()
.
-
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 ornull
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. Returnsnull
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 likerelative/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 tocq:tags
property, e.g.cq:tags
orrelative/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 tocq:tags
property, e.g.cq:tags
orrelative/path/@cq:tags
- Returns:
- a GQL (org.apache.jackrabbit.commons.query.GQL) expression
-
-