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

      • 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