senselogic.sitevision.api.tag

Interface TagUtil

@Requireable(value="TagUtil")
public interface TagUtil

Tag utility interface for tree nodes.

This sv:tag utility operates on taggable nodes of type: sv:page, sv:article, sv:sitePage, sv:collaborationGroupPage, sv:file and sv:image.

Related: Use NodeResolverUtil.getTagsResolver() to resolve sv:tag's from other node types (e.g. sv:timelineEntry, sv:comment, sv:tagGroup etc). Use MetadataUtil to set tag metadata.

Since:

Sitevision 9.1

Author:

Karl Eklöf

Method Summary

Modifier and Type	Method and Description
void	addTag(Node aTaggableNode, Node aTagNode) Adds a sv:tag to a Node.
void	addTags(Node aTaggableNode, Node... aTagNodes) Adds multiple sv:tag to a Node.
Node	getOrCreateTagByName(String aTagName) Gets or creates a sv:tag Node by name.
Node	getTagByName(String aTagName) Gets a sv:tag Node by name.
List<Node>	getTags(Node aTaggableNode) Gets all sv:tag's for a Node.
boolean	removeTag(Node aTaggableNode, Node aTagNode) Removes a sv:tag from a Node.

Method Detail

getTagByName

Node getTagByName(String aTagName)
           throws IllegalArgumentException

Gets a sv:tag Node by name.

Parameters:

aTagName - the tag name. Must not be null, whitespace-only or shebang-only

Returns:

a sv:tag or null if no tag with aTagName could be fond

Throws:

IllegalArgumentException - if aTagName is invalid

getOrCreateTagByName

Node getOrCreateTagByName(String aTagName)
                   throws IllegalArgumentException,
                          RepositoryException

Gets or creates a sv:tag Node by name.

Permission note: Current user must be authenticated (i.e. non-anonymous).

Parameters:

aTagName - the tag name. Must not be null, whitespace-only or shebang-only

Returns:

the sv:tag for aTagName

Throws:

IllegalArgumentException - if aTagName is invalid

RepositoryException - if current user is anonymous or the sv:tag could not be found or created

addTag

void addTag(Node aTaggableNode,
            Node aTagNode)
     throws IllegalArgumentException,
            RepositoryException

Adds a sv:tag to a Node.

Permission note: Current user must have WRITE permission on the taggable Node that is mutated. Note that members of a sv:collaborationGroup is also allowed to add tags for the group files.

Versioning note: Mutation of the taggable Node is always executed in the OFFLINE version. In other words - if you mutate the sv:tag entries on a sv:page, you must also publish the sv:page for changes to affect the ONLINE/published version.

Parameters:

aTaggableNode - a taggable node (sv:page, sv:article, sv:sitePage, sv:collaborationGroupPage, sv:file or sv:image)

aTagNode - a sv:tag

Throws:

IllegalArgumentException - if aTaggableNode or aTagNode is null or an unsupported type

RepositoryException - if mutation is not allowed or fails

addTags

void addTags(Node aTaggableNode,
             Node... aTagNodes)
      throws IllegalArgumentException,
             RepositoryException

Adds multiple sv:tag to a Node.

Permission note: Current user must have WRITE permission on the taggable Node that is mutated. Note that members of a sv:collaborationGroup is also allowed to add tags for the group files.

Versioning note: Mutation of the taggable Node is always executed in the OFFLINE version. In other words - if you mutate the sv:tag entries on a sv:page, you must also publish the sv:page for changes to affect the ONLINE/published version.

Server-side Javascript example:

    const tagUtil = require('TagUtil');
    ...
    let tags = [];
    tags.push(tagUtil.getOrCreateTagByName('mytag'));
    tags.push(tagUtil.getOrCreateTagByName('myothertag'));

    tagUtil.addTags(pageNode, tags);

Parameters:

aTaggableNode - a taggable node (sv:page, sv:article, sv:sitePage, sv:collaborationGroupPage, sv:file or sv:image)

aTagNodes - a var-args array of sv:tag nodes

Throws:

IllegalArgumentException - if aTaggableNode is null or an unsupported type, or if or aTagNodes is null, empty or contains an unsupported type

RepositoryException - if mutation is not allowed or fails

removeTag

boolean removeTag(Node aTaggableNode,
                  Node aTagNode)
           throws IllegalArgumentException,
                  RepositoryException

Removes a sv:tag from a Node.

Permission note: Current user must have WRITE permission on the taggable Node that is mutated. Note that members of a sv:collaborationGroup is also allowed to remove tags for the group files.

Versioning note: Mutation of the taggable Node is always executed in the OFFLINE version. In other words - if you mutate the sv:tag entries on a sv:page, you must also publish the sv:page for changes to affect the ONLINE/published version.

Parameters:

aTaggableNode - a taggable node (sv:page, sv:article, sv:sitePage, sv:collaborationGroupPage, sv:file or sv:image)

aTagNode - a sv:tag

Returns:

true if aTagNode was removed from aTaggableNode, false otherwise

Throws:

IllegalArgumentException - if aTaggableNode or aTagNode is null or an unsupported type

RepositoryException - if mutation is not allowed or fails

getTags

List<Node> getTags(Node aTaggableNode)
            throws IllegalArgumentException

Gets all sv:tag's for a Node.

Version note! This method executes in current version, i.e. it will return the list of sv:tag's in current version (OFFLINE_VERSION or ONLINE_VERSION).

Parameters:

aTaggableNode - a taggable node (sv:page, sv:article, sv:sitePage, sv:collaborationGroupPage, sv:file or sv:image)

Returns:

a list of sv:tag nodes for aTaggableNode

Throws:

IllegalArgumentException - if aTaggableNode is null or an unsupported type