Umbraco – The Ucomponent Multi-Node Tree Picker Guide

by - Sunday, October 21, 2012

A look at the Ucomponent Multi-Node Tree Picker - an Umbraco package that allows the content manager to create relationships between content nodes.

What is the Ucomponent Multi-Node Tree Picker for Umbraco?

The Tree Picker is an Umbraco package that gives the user an easy way to select nodes or media items from a selected tree node. You can ‘drag and drop’ the content that you want to use, and your developer will handle it with a few lines of XSLT.

A real world example of where the Node Picker is useful.

Within the sport section on a news website, there will be a menu of all the sports which link off to their own sections and articles.

For example, in the Football section, the main story may be an article about that day’s big game, so, with the Multi-node tree picker you can select the related articles from the content tree and display them on the same page as the main article by simply ‘dragging and dropping’ them.

The related articles in this case may be links to the teams playing and their recent news. So now on the page, we have the main article and article links related to that listed all on the same page.

How do you set up the Multi-Node Tree Node Picker?

After downloading the picker from here, install the package in the ‘Packages’ section on the ‘Developers’ page.

The next step is to create a ‘Data Type’. Give it a name like ‘Multiple Nodes’ so the title is descriptive of what it is.

Underneath the Name box, is the ‘Render Control’ dropdown list. Select the item titled ‘uComponents: Multi-Node Tree Picker’ and wait for the settings to appear below the dropdown – see the screenshot below:

Data -type -settings

The screen grab above shows the settings we chose on one particular project. Some of the options are quite self-explanatory but below we have added a brief description to some ideal options when choosing your settings.

The ‘Start Node ID’ is where you want start of your selection tree to be. Here above, we have selected ‘Projects.’ This will then only allow me to choose the child nodes of projects and any children of those children. This also means that the parent and adjacent nodes of ‘Project’ aren’t accessible.

‘Data as CSV or XML’ is an important option here. You want to choose the XML option as we will be using XSLT’s later on to select the picked nodes.

Saving these settings will not set it in stone, you can change these whenever you want, just access it via the ‘Data Types’ dropdown list.

So how do you use it?

Our site sumac is maintained using Umbraco. One part of the site requires the use of the Multi-node Tree Picker. On the homepage there is a ‘Recent Projects’ area where there are nine recent project items linking to their respective project pages. See the screenshot below:

Recent -projects

Screenshot of Sumac homepage with the project items

We needed a way to choose exactly which items we wanted to display in this section with ease and avoiding hard coding them into the mark-up. Sure that would have worked, but we didn’t want to have to change the mark up every time we had a new project to display.

So we looked around and found the Tree Picker.

After completing the initial installation and settings, we opened up the Homepage Doc Type and created a new property. This is the exact same method as what you would do to create a standard built in Umbraco property.

Multi -node -doc -type -settings

In the ‘Type’ dropdown list select the title of the data type you assigned the Node picker when setting up the package. The picker can be mandatory or voluntary; this all depends on whether you insist on there being nodes selected.

When saved, open the ‘Content’ tab and view the node created using the Doc type containing the Node Picker property.

Drag -drop -capture

This above is what the interface of the Node picker looks like. It is a simple ‘drag and drop’ system where you pick the nodes from the tree and drag them across to the other side.  If you decide you do not want a particular node to be selected, you simply click on the cross to the right of the node.

Creating the Macro

We now need to be able to select the chosen nodes using XSLT. The resulting macro will then be placed in the homepage template, linking through the items, displaying them on the homepage.

Create a new XSLT file and a macro.

Here is my full XSLT page here. Take a look at this because below we explain how it all works.

The 1st thing we need to do is target the nodes that have been selected using the Tree Picker. So we have to use a for-each which will get the ID’s of the picked nodes. This is done using XPath.

<xsl:for-each select=”$currentPage/ancestor-or-self::*/Home/projectsToDisplayOnHomepage/MultiNodePicker/nodeId”>

We now need to save the contents of the for-each in a variable to use later. The select=“.” represents all the matched nodes in the for-each selection.

<xsl:variable name=”idProject” select=”.”/>

After saving the NodeId’s in a variable, we now have to target my project items within myProjectGroupPage which are using the ProjectItem DocType.

<xsl:for-each select=”$currentPage/ancestor-or-self::*/Home/ProjectGroupPage/ProjectItem”>

Then we created a variable named idNodePicker which gets the @id of the ProjectItem’s. The node ID is unique, so there will not ever be any confusion over nodes having the same ID’s.

<xsl:variable name=”idNodePicker” select=”@id”/>

Finally to get only the nodes that are selected in the Tree Picker, an if test needs to be used. IfidNodePicker is equal to idProject then select them and their properties.

<xsl:if test=”$idNodePicker = $idProject”>

For one last final action, we need to place the macro on the template.

Macro -on -homepage

And now we are able to display my project items on the homepage, while keeping the content dynamic.

4 Comments

Umbraco Developer London says:
Very thorough guide, thanks! A follow-up post using the razor syntax would be really nice. Look out for one on my blog soon.
2 February 2012 at 17:44

Hannah says:
Hi
Thank you for this guide!
Just a quick question as i’m not up to scratch on xslt yet.where you have this line:
I’ve notices your projects on your website are under /work/
My projects are stored Home/Our Work/Project 1 etc
How would i adapt that line of xslt to get it to feed through?
I’ve tried /Home/Our-Work/Project
as my document type is : Project.
I’ve also tried our-work, OurWork and nothing is working. I have the datatype alias down correctly.
Would appreciate your help as i’ve followed this guide and haven’t found anything else on the web that achieves what i want.
Thanks
30 August 2012 at 12:40

Martyn says:
Hannah, James in on holiday at the moment but I’ll ask him to respond when he gets back. OK?
30 August 2012 at 14:11

James says:
Hello Hannah
It seems that your Document Type alias’s maybe aren’t correct.
Sumacs projects are contained within the ‘Work’ folder with the Document Type alias of ‘Project Group Page’ (ProjectGroupPage – spaces need to be removed between words). The name of the folder is ‘Work’ but the Document Type is different. The Document Types is what we need to use to construct the XSL paths.
Take the following XPath for example – /Home/ProjectGroupPage/ProjectItem/
This matches this URL path – /work/the-future-is-social/
In this case, ‘home has a Document Type of ‘home’, ‘work’ has a Document Type of ‘ProjectGroupPage’ and ‘the-future-is-social’ has a Document Type of ‘ProjectItem’.
So for your XSL to work, you would have to change ‘Home/Our Work/Project 1′ into the respected Document Types for each of the folders and items.
This should do the trick, but if I’m off the mark just get back to me and I can try to sort this out.
James
12 September 2012 at 11:34

Send us a comment on this article