senselogic.sitevision.api.node

Interface NodeTreeUtil

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

Node tree utility interface.

An instance of the Sitevision class implementing this interface can be obtained via Utils.getNodeTreeUtil(). See Utils for how to obtain an instance of the Utils interface.

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
Node	findPortletByName(Node aPageNode, String aPortletName) Find a portlet with a specific name on a page node.
List<Node>	findPortletsByName(Node aPageNode, String aPortletName) Find all portlets with a specific name on a page node.
List<Node>	findPortletsByName(Node aPageNode, String aPortletName, Filter<Node> aNodeFilter) Find all portlets with a specific name on a page node and applies a node filter to the result.
List<Node>	findPortletsByType(Node aPageNode, String aPortletType) Find all portlets of a specific type on a page node.
List<Node>	findPortletsByType(Node aPageNode, String aPortletType, Filter<Node> aNodeFilter) Find all portlets with a specific type on a page node and applies a node filter to the result.
Node	getNode(Node aNode, String aRelPath) Gets a node relative to another node.
Node	getParent(Node aNode) Gets the parent of a node.
List<Node>	getWebPathNodes(Node aDescendantNode) Returns a top-down list of all web nodes from the site page down to a specified page tree node.
boolean	isDescendantOf(Node aDescendantNode, Node aParentNode) Check if a given page tree node is a descendant of another page tree node.

Method Detail

getNode

Node getNode(Node aNode,
             String aRelPath)

Gets a node relative to another node.

Note! This is mere a convenience alias for Node.getNode(String) but unlike the original, this method returns null instead of throwing an exception if no node could be retrieved at a specified path.

Parameters:

aNode - the node

aRelPath - the relative path (of aNode) to the node to retrieve

Returns:

the node at aRelPath, or null if no such node could be retrieved

Since:

Sitevision 4.0

getParent

Node getParent(Node aNode)

Gets the parent of a node.

Note! This is mere a convenience alias for Item.getParent() but unlike the original, this method returns null instead of throwing an exception if no parent node could be retrieved.

Parameters:

aNode - the node

Returns:

the parent node of aNode, or null if no parent could be retrieved

Since:

Sitevision 4.0

isDescendantOf

boolean isDescendantOf(Node aDescendantNode,
                       Node aParentNode)

Check if a given page tree node is a descendant of another page tree node.

Parameters:

aDescendantNode - the presumed descendant page tree Node (e.g. "child node")

aParentNode - the presumed parent page tree Node of the descendant

Returns:

true if aDescendantNode is a descendant of aParentNode, false otherwise

findPortletByName

Node findPortletByName(Node aPageNode,
                       String aPortletName)

Find a portlet with a specific name on a page node.

The name of the portlet is determined by the displayName property.

Parameters:

aPageNode - the page node that has content, typically a sv:page or sv:article

aPortletName - the name of the sv:portlet that should be found

Returns:

the first occurrence of a sv:portlet with name aPortletName, or null if no such portlet can be found or if aPageNode is not a page node

Since:

Sitevision 2.6

See Also:

findPortletsByName(Node,String)

findPortletsByName

List<Node> findPortletsByName(Node aPageNode,
                              String aPortletName)

Find all portlets with a specific name on a page node.

The name of the portlet is determined by the displayName property.

Parameters:

aPageNode - the page node that has content, typically a sv:page or sv:article

aPortletName - the name of the sv:portlet that should be found

Returns:

all occurrences of portlets with name aPortletName. If no such portlets can be found or if aPageNode is not a page node, an empty List is returned

Since:

Sitevision 2.6

See Also:

findPortletByName(Node,String)

findPortletsByName

List<Node> findPortletsByName(Node aPageNode,
                              String aPortletName,
                              Filter<Node> aNodeFilter)

Find all portlets with a specific name on a page node and applies a node filter to the result.

The name of the portlet is determined by the displayName property.

Tip! NodeFilterUtil can be used to create a node filter.

Parameters:

aPageNode - the page node that has content, typically a sv:page or sv:article

aPortletName - the name of the sv:portlet that should be found

aNodeFilter - a node filter to refine the result of all portlets with specified name

Returns:

all occurrences of portlets with name aPortletName that also applies to the aNodeFilter filter. If no such portlets can be found or if aPageNode is not a page node, an empty List is returned

Since:

Sitevision 3.6.2

findPortletsByType

List<Node> findPortletsByType(Node aPageNode,
                              String aPortletType)

Find all portlets of a specific type on a page node.

The type of the portlet is determined by the portletName property. This is typically the value that is specified in the <portlet-name> element of the portlet in portlet.xml.

Types for some common portlets:

• The Sitevision Text portlet type: text
• The Sitevision Image portlet type: image

Parameters:

aPageNode - the page node that has content, typically a sv:page or sv:article

aPortletType - the type of sv:portlet that should be found

Returns:

all occurrences of portlets of type aPortletType. If no such portlets can be found or if aPageNode is not a page node, an empty List is returned

Since:

Sitevision 3.6.2

findPortletsByType

List<Node> findPortletsByType(Node aPageNode,
                              String aPortletType,
                              Filter<Node> aNodeFilter)

Find all portlets with a specific type on a page node and applies a node filter to the result.

The type of the portlet is determined by the portletName property. This is typically the value that is specified in the <portlet-name> element of the portlet in portlet.xml.

Types for some common portlets:

• The Sitevision Text portlet type: text
• The Sitevision Image portlet type: image

Tip! NodeFilterUtil can be used to create a node filter.

Below is a Velocity example that demonstrates how to extract all Image portlets from the content of a specified page. A node filter is applied to only return the Image portlets that has a display name that contains the word logo.

    ## Create a filter that matches nodes that has a displayName that contains "logo"
    #set ($nodeFilterUtil = $sitevisionUtils.NodeFilterUtil)
    #set ($containsLogoFilter = $nodeFilterUtil.getContainsStringPropertyFilter('displayName', 'logo'))

    ## Extract all matching Image portlets from the page
    #set ($logoImagePortlets = $nodeTreeUtil.findPortletsByType($thePage, 'image', $containsLogoFilter))
    #if (!$logoImagePortlets.isEmpty())
       ## Handle matching image portlets
       ...
    #end

Below is another Velocity example. A node filter is applied to only return the Image portlets that uses images that has a width between 24px and 132px (an Image portlet has a 'image' property that can be resolved as a sv:image Node and such node has a 'width' property).

    ## Create a filter that matches nodes that has a nested width between [24..132]
    #set ($nodeFilterUtil = $sitevisionUtils.NodeFilterUtil)
    #set ($imageWidthFilter = $nodeFilterUtil.getRangeNestedIntPropertyFilter('image', 'width', 24, 132))

    ## Extract all Image portlets that uses an "appropriate" image
    #set ($foundImagePortlets = $nodeTreeUtil.findPortletsByType($thePage, 'image', $imageWidthFilter))
    #if (!$foundImagePortlets.isEmpty())
       ## Handle matching image portlets
       ...
    #end
 

Parameters:

aPageNode - the page node that has content, typically a sv:page or sv:article

aPortletType - the type of sv:portlet that should be found

aNodeFilter - a node filter to refine the result of all portlets of specified type

Returns:

all occurrences of portlets of type aPortletType that also applies to the aNodeFilter filter. If no such portlets can be found or if aPageNode is not a page node, an empty List is returned

Since:

Sitevision 3.6.2

getWebPathNodes

List<Node> getWebPathNodes(Node aDescendantNode)

Returns a top-down list of all web nodes from the site page down to a specified page tree node.

This method traverses the site page tree and returns a list of all web nodes, from the site page to a descendant. The tree traversal will use a maximum tree depth of 50. If the specified node is deeper down in the tree than that, an incomplete list will be returned (top nodes will be missing).

Note! Mentioned "web nodes" are by this method considered to be all child nodes of the site page node you can see in the Sitevision editor Navigator that are accessible from the location bar of a browser (e.g. pages and articles but not folders and archives). File and image nodes are also recognized as web nodes - even if they are in the "site global" archive (i.e. in the site tree, not actually in the site page tree). In other words, though they are accessible from the location bar of a browser - a portlet node or layout node is not considered to be a web node by this method.

Tip! If you should render a linked "path to this page", consider using the renderWebPathNodes utility of OutputUtil.

Parameters:

aDescendantNode - a page tree node that is a descendant/child of the site page, typically a sv:page or sv:article

Returns:

a top-down list of the web nodes that are in the tree path from the site page node downto aDescendantNode (the site page node and the descendant node are both included in the list). An empty list will be returned if aDescendantNode is null or not a descendant of the site page.

Since:

Sitevision 2.6.1_06

See Also:

OutputUtil.renderWebPathNodes(javax.jcr.Node, senselogic.sitevision.api.render.LinkRenderer, String)