Umbraco – The Ucomponent Multi-Node Tree Picker Guide
21 October 2011
Posted by: james
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:
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:
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.
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.
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.
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 my ProjectGroupPage which are using the ProjectItem DocType.
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. If idNodePicker 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.
And now we are able to display my project items on the homepage, while keeping the content dynamic.