Navigating the content tree

Umbraco: v3, v4

Navigation in the content node tree is normally done using xslt and xpath features - see the Navigating using XPath for more info on XPath. In Umbraco you also have the option to use build-in library functions to do certain node-fetching operations.

Think of the content nodes as a tree with a root node having one or more child nodes. All child nodes again may have one or more child nodes etc. Navigating around in the content tree is either absolute (using specific node references) or relative to the current node. The current node is decided by the context, so e.g. in xsl:for-each loops the current node (node() or .) is the node at the current iteration.

Starting node - currentPage

By default you might consider using current node (.) as the current page node, but that actually does not make sense in xslt macros. Instead use the currentPage parameter:

<xsl:param name="currentPage"/>
...
<xsl:value-of select="$currentPage/@id"/>

Navigating using XPath

Navigation in the content node tree is mainly done using xpath features. XPath is language for navigating and addressing parts of an xml document. All nodes can be addressing using xpath syntax, some construct gets really long and hard to read, but it is quite effective once you get the hang of it.

XPath expressions quickly gets a bit messy to read, but here is a few hints to get you started:

The expression results in a node or nodeset
The nodeset is built up bit by bit, from left to right in the expression
Most expression parts works on the nodeset generated so far using the current context node.

Some of the attributes and functions often used are the @level attribute of every node, and the position() function on a node. The @level node-attribute holds the descendant-level (integer) from the root - this is often used in navigation filters:

<table style="width:300px;">
<xsl:for-each select="$currentPage/node">
  <tr><td>
    <xsl:if test="position() mod 2 = 0">
      <xsl:attribute name="bgcolor">white</xsl:attribute>
    </xsl:if>
    <xsl:value-of select="@nodeName"/>
  </td></tr>
</xsl:for-each>
</table>

Position() returns the position of the current node in a node-set, e.g. when iterating in a for-each expression:

<xsl:for-each select="$currentPage/ancestor-or-self::node [@level=$level]/node [string(data [@alias='umbracoNaviHide']) != '1']">

Navigating using Umbraco library function

Umbraco offers by default a number of functions in the Umbraco.library extension. All extensions and their related functions can be inserted automatically when clicking the "Insert xslt:value-of" button in the xslt macro toolbar and the "Get extensions" button.

The Umbraco.library functions differs a bit from the XPath functionality because it specifically targets Umbraco tasks, e.g. looking up nodes given specific umbraco node-id's.

Some of the functions available are:

GetItem(int nodeID, String alias)

GetItem(String alias)

GetMedia(int MediaId, bool Deep)

GetMember(int MemberId)

GetCurrentMember()

GetXmlNodeCurrent()

GetXmlNodeById(string id)

GetXmlNodeByXPath(string xpathQuery)

GetXmlAll()

GetXmlDocument(string Path, bool Relative)

GetXmlDocumentByUrl(string Url)

QueryForNode(string id)

GetNodeFromLevel(string path, int level)

One of the mostly used functions is the GetXmlNodeById which returns a node in the content tree given a node id, e.g. from a node-picker datatype:

<xsl:for-each select="umbraco.library:GetXmlNodeById($source)/descendant::node"/>

This example fetches all childs nodes of type "node" of the content-node with id $source.

umbraco workbench