@sitevision/api 2.0.0-alpha.0 → 2.0.0-alpha.1

package/hidden/senselogic/sitevision/api/node/NodeTreeUtil/index.d.ts

@@ -1,232 +0,0 @@
-import Node from "../../../../../javax/jcr/Node";
-
-import Filter from "../../base/Filter";
-
-/**
- * Node tree utility interface.
- *
- * <p>
- *    An instance of the Sitevision class implementing this interface can be obtained via
- *    {@link senselogic.sitevision.api.Utils#getNodeTreeUtil()}.
- *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
- * </p>
- * @author Magnus Lövgren
- */
-
-interface NodeTreeUtil {
-  /**
-   * Gets a node relative to another node.
-   *
-   * <p>
-   *    <em>
-   *       Note! This is mere a convenience alias for {@link javax.jcr.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.
-   *    </em>
-   * </p>
-   * @param aNode the node
-   * @param aRelPath the relative path (of <code>aNode</code>) to the node to retrieve
-   * @return the node at <code>aRelPath</code>, or <code>null</code> if no such node could be retrieved
-   * @since Sitevision 4.0
-   */
-  getNode(aNode: Node, aRelPath: java.lang.String): Node;
-
-  /**
-   * Gets the parent of a node.
-   *
-   * <p>
-   *    <em>
-   *       Note! This is mere a convenience alias for {@link javax.jcr.Item#getParent()} but unlike the original,
-   *       this method returns null instead of throwing an exception if no parent node could be retrieved.
-   *    </em>
-   * </p>
-   * @param aNode the node
-   * @return the parent node of <code>aNode</code>, or <code>null</code> if no parent could be retrieved
-   * @since Sitevision 4.0
-   */
-  getParent(aNode: Node): Node;
-
-  /**
-   * Check if a given page tree node is a descendant of another page tree node.
-   * @param aDescendantNode the presumed descendant page tree <code>Node</code> (e.g. "child node")
-   * @param aParentNode the presumed parent page tree <code>Node</code> of the descendant
-   * @return <code>true</code> if <code>aDescendantNode</code> is a descendant of <code>aParentNode</code>, <code>false</code> otherwise
-   */
-  isDescendantOf(aDescendantNode: Node, aParentNode: Node): boolean;
-
-  /**
-   * Find a portlet with a specific name on a page node.
-   *
-   * <p>
-   *    The <em>name</em> of the portlet is determined by the <em>displayName</em> property.
-   * </p>
-   * @param aPageNode the page node that has content, typically a sv:page or sv:article
-   * @param aPortletName the name of the sv:portlet that should be found
-   * @return the first occurrence of a sv:portlet with name <code>aPortletName</code>, or <code>null</code> if no such portlet can be found or if <code>aPageNode</code> is not a page node
-   * @since Sitevision 2.6
-   * @see #findPortletsByName(Node,String)
-   */
-  findPortletByName(aPageNode: Node, aPortletName: java.lang.String): Node;
-
-  /**
-   * Find all portlets with a specific name on a page node.
-   *
-   * <p>
-   *    The <em>name</em> of the portlet is determined by the <em>displayName</em> property.
-   * </p>
-   * @param aPageNode the page node that has content, typically a sv:page or sv:article
-   * @param aPortletName the name of the sv:portlet that should be found
-   * @return all occurrences of portlets with name <code>aPortletName</code>. If no such portlets can be found or if <code>aPageNode</code> is not a page node, an empty <code>List</code> is returned
-   * @since Sitevision 2.6
-   * @see #findPortletByName(Node,String)
-   */
-  findPortletsByName(
-    aPageNode: Node,
-    aPortletName: java.lang.String
-  ): unknown[];
-
-  /**
-   * Find all portlets with a specific name on a page node and applies a node filter to the result.
-   *
-   * <p>
-   *    The <em>name</em> of the portlet is determined by the <em>displayName</em> property.
-   * </p>
-   *
-   * <p>
-   *    <em>Tip!</em> {@link senselogic.sitevision.api.node.NodeFilterUtil} can be used to create a node filter.
-   * </p>
-   * @param aPageNode the page node that has content, typically a sv:page or sv:article
-   * @param aPortletName the name of the sv:portlet that should be found
-   * @param aNodeFilter a node filter to refine the result of all portlets with specified name
-   * @return all occurrences of portlets with name <code>aPortletName</code> that also applies to the <code>aNodeFilter</code> filter. If no such portlets can be found or if <code>aPageNode</code> is not a page node, an empty <code>List</code> is returned
-   * @since Sitevision 3.6.2
-   */
-  findPortletsByName(
-    aPageNode: Node,
-    aPortletName: java.lang.String,
-    aNodeFilter: Filter
-  ): unknown[];
-
-  /**
-   * Find all portlets of a specific type on a page node.
-   *
-   * <p>
-   *    The <em>type</em> of the portlet is determined by the <em>portletName</em> property. This is typically
-   *    the value that is specified in the &lt;portlet-name&gt; element of the portlet in <code>portlet.xml</code>.
-   * </p>
-   * <p>
-   *    Types for some common portlets:
-   * </p>
-   * <ul>
-   *    <li>
-   *       The Sitevision <em>Text</em> portlet type: <code>text</code>
-   *    </li>
-   *    <li>
-   *       The Sitevision <em>Image</em> portlet type: <code>image</code>
-   *    </li>
-   * </ul>
-   * @param aPageNode the page node that has content, typically a sv:page or sv:article
-   * @param aPortletType the type of sv:portlet that should be found
-   * @return all occurrences of portlets of type <code>aPortletType</code>. If no such portlets can be found or if <code>aPageNode</code> is not a page node, an empty <code>List</code> is returned
-   * @since Sitevision 3.6.2
-   */
-  findPortletsByType(
-    aPageNode: Node,
-    aPortletType: java.lang.String
-  ): unknown[];
-
-  /**
-   * Find all portlets with a specific type on a page node and applies a node filter to the result.
-   *
-   * <p>
-   *    The <em>type</em> of the portlet is determined by the <em>portletName</em> property. This is typically
-   *    the value that is specified in the &lt;portlet-name&gt; element of the portlet in <code>portlet.xml</code>.
-   * </p>
-   *
-   * <p>
-   *    Types for some common portlets:
-   * </p>
-   * <ul>
-   *    <li>
-   *       The Sitevision <em>Text</em> portlet type: <code>text</code>
-   *    </li>
-   *    <li>
-   *       The Sitevision <em>Image</em> portlet type: <code>image</code>
-   *    </li>
-   * </ul>
-   *
-   * <p>
-   *    <Strong>Tip!</Strong> {@link senselogic.sitevision.api.node.NodeFilterUtil} can be used to create a node filter.
-   * </p>
-   * <p>
-   *    Below is a <strong>Velocity example</strong> 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 <em>logo</em>.
-   * </p>
-   * <pre><code>    <em>## Create a filter that matches nodes that has a displayName that contains "logo"</em>
-   *    #set ($nodeFilterUtil = $sitevisionUtils.NodeFilterUtil)
-   *    #set ($containsLogoFilter = $nodeFilterUtil.getContainsStringPropertyFilter('displayName', 'logo'))
-   *
-   *    <em>## Extract all matching Image portlets from the page</em>
-   *    #set ($logoImagePortlets = $nodeTreeUtil.findPortletsByType($thePage, 'image', $containsLogoFilter))
-   *    #if (!$logoImagePortlets.isEmpty())
-   *       <em>## Handle matching image portlets</em>
-   *       ...
-   *    #end</code></pre>
-   * <p>
-   *    Below is another <strong>Velocity example</strong>. A node filter is applied to only return the Image portlets that uses
-   *    images that has a width between 24px and 132px <em>(an Image portlet has a 'image' property that can be resolved as a sv:image
-   *    Node and such node has a 'width' property)</em>.
-   * </p>
-   * <pre><code>    <em>## Create a filter that matches nodes that has a nested width between [24..132]</em>
-   *    #set ($nodeFilterUtil = $sitevisionUtils.NodeFilterUtil)
-   *    #set ($imageWidthFilter = $nodeFilterUtil.getRangeNestedIntPropertyFilter('image', 'width', 24, 132))
-   *
-   *    <em>## Extract all Image portlets that uses an "appropriate" image</em>
-   *    #set ($foundImagePortlets = $nodeTreeUtil.findPortletsByType($thePage, 'image', $imageWidthFilter))
-   *    #if (!$foundImagePortlets.isEmpty())
-   *       <em>## Handle matching image portlets</em>
-   *       ...
-   *    #end
-   * </code></pre>
-   * @param aPageNode the page node that has content, typically a sv:page or sv:article
-   * @param aPortletType the type of sv:portlet that should be found
-   * @param aNodeFilter a node filter to refine the result of all portlets of specified type
-   * @return all occurrences of portlets of type <code>aPortletType</code> that also applies to the <code>aNodeFilter</code> filter. If no such portlets can be found or if <code>aPageNode</code> is not a page node, an empty <code>List</code> is returned
-   * @since Sitevision 3.6.2
-   */
-  findPortletsByType(
-    aPageNode: Node,
-    aPortletType: java.lang.String,
-    aNodeFilter: Filter
-  ): unknown[];
-
-  /**
-   * Returns a top-down list of all web nodes from the site page down to a specified page tree node.
-   *
-   * <p>
-   * 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).
-   * </p>
-   *
-   * <p>
-   * <em>Note!</em> 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 <em>not</em>
-   * considered to be a web node by this method.
-   * </p>
-   *
-   * <p>
-   *    <em>Tip! If you should render a linked "path to this page", consider using the <code>renderWebPathNodes</code>
-   *    utility of {@link senselogic.sitevision.api.render.OutputUtil}.</em>
-   * </p>
-   * @param aDescendantNode a page tree node that is a descendant/child of the site page, typically a sv:page or sv:article
-   * @return a top-down list of the web nodes that are in the tree path from the site page node downto <code>aDescendantNode</code> (the site page node and the descendant node are both included in the list). An empty list will be returned if <code>aDescendantNode</code> is <code>null</code> or not a descendant of the site page.
-   * @since Sitevision 2.6.1_06
-   * @see senselogic.sitevision.api.render.OutputUtil#renderWebPathNodes(javax.jcr.Node, senselogic.sitevision.api.render.LinkRenderer, String)
-   */
-  getWebPathNodes(aDescendantNode: Node): unknown[];
-}