Making custom sections and trees inside Umbraco - part II

Alright.. I'm ready for the second part of this tutorial series, I hope you are as well, and enjoyed the first one.

This time we are going to get our hands dirty in some C# code as we are going to populate our freshly created custom section with a treemenu .. after that I'll show you how to attach events to every tree node.

First let's set up some code to display the tree menu. To do this, we need our C# class to implement the interface ITree. What is an interface? Well, basically it's like defining a ruleset for your class. A ruleset of which fields, events, properties or methods your class MUST contain. If the interface is only partially implemented in your class, the compiler will throw an error.

With that in mind, let's take a look at the ITree interface (located in the umbraco.interface namespace)

http://www.umbraco.org/apiDocs/html/8a206c5a-1522-9835-f27e-b8192c2582ea.htm

As you can see from the link above, there are
2 public properties

and 2 public methods

Render()
RenderJS()

I'm uncertain what the properties app and id are used for, I guess it has something to do with identification. But the Render() and RenderJS()-methods are.. yes correct.. ment for rendering output to the browser. I'll come back to that, let's go ahead and implement our class in accordance with the interface. Once done, it should look somewhat similar to this:

using System;
using System.Collections.Generic;
using System.Text;
using umbraco;
using umbraco.interfaces;

namespace MyTestNamespace
{
    public class MyTree : ITree
    {
        private int _id;
        private string _app;

        public string app
        {
            set { _app = value; }
        }

        public int id
        {
            set { _id = value; }
        }

        public void Render(ref System.Xml.XmlDocument Tree)
        {
            
        }

        public void RenderJS(ref StringBuilder Javascript)
        {
            
        }

    }
}

Okay, let's start to fill out the missing spots, be sure to check the comment-lines in the source below as they'll explain what's going on:

using System;
using System.Collections.Generic;
using System.Text;
using System.Xml; // <--- I'm referencing System.Xml
using umbraco;
using umbraco.interfaces;

namespace MyTestNamespace
{
    public class MyTree : ITree
    {
        private int _id;
        private string _app;

        public string app
        {
            set { _app = value; }
        }

        public int id
        {
            set { _id = value; }
        }

        public void Render(ref System.Xml.XmlDocument Tree)
        {
            // attach to the current Tree
            XmlNode root = Tree.DocumentElement;
            XmlElement treeElement = Tree.CreateElement("tree");

            // internal node id, set this to a negative number
            // to avoid problems with existing node id's
            treeElement.SetAttribute("nodeID", "-2244");
            treeElement.SetAttribute("menu", "menu");

            // This will be the name of the tree node
            treeElement.SetAttribute("text", "Google Analytics");

            // You can also set the "action"-attribute to an internal umbracopage
            treeElement.SetAttribute("action", "javascript:gotoURL('http://www.google-analytics.com');");
            treeElement.SetAttribute("src", "test");

            // the icon shown when not clicked
            treeElement.SetAttribute("icon", "settingDataType.gif");
            
            // the icon shown when the current tree node is clicked on
            treeElement.SetAttribute("openIcon", "settingDataType.gif");
            root.AppendChild(treeElement);

            // if you need more nodes (pages), 
            // just copy the lines above and insert them again
            // - except for line 28 & 29

            }

        public void RenderJS(ref StringBuilder Javascript)
        {
            // the dashboard (right side of the screen) is inside an IFRAME,
            // so we need to append some javascript to the page.

            Javascript.Append(@"
				function gotoURL(url) {
				parent.right.document.location.href = url;
				}
			");
        }

    }
}

Once you've made something similar to the above, compile it and throw it in the bin-folder of your umbraco-powered website.

Next up, we're going to connect your newly created tree assembly with the rest of Umbraco. Again, open up your SQL Management Studio. Find the database associated with your Umbraco installation and open the UmbracoAppTree-table. You should then end up with an overview of rows and columns. Make a copy of an existing row or make your own, fx. similar to this:

treeSilent	treeInitialize	treeSortOrder	appAlias	treeAlias	treeTitle	treeIconClosed	treeIconOpened	treeHandlerAssembly	treeHandlerType
false	true	0	shop	shop	Shop	folder.gif	folder_o.gif	MyTestNamespace	MyTree

Since no actual documentation exist on the db-layout it's guessing time again. Here's what I imagine that the meaning of the different cells are:

treeSilent - possible values: true or false
- treeSilent decides whether or not to show the top node inside the nodetree
treeInitialize - possible values: true or false
- If treeInitialize is set it will display the tree item once the node tree is rendered
treeSortOrder - values: integer
- the position of a node among nodes on the same level and with the same parent
appAlias / treeAlias - value: a string without spaces
- internal Umbraco reference to the treenode - should be unique for each instance.
treeTitle - value: string
- the visible name of the tree node
treeIconClosed / treeIconOpened - value: string w/o spaces
- filename of the icons shown to the left of the node title in either closed state or opened state
treeHandlerAssembly (IMPORTANT!) - pos. value: string w/o spaces
- the name of the assembly you're loading the tree nodes from - in this tutorial it's MyTestNamespace
treeHandlerType (IMPORTANT!) - pos. value: string w/o spaces
- the class name of your piece of code

Once you've made your changes you should be able to see your menu inside Umbraco. You may have to log out and log in again.

Final notes: The outputted dll-file should have the same name as the namespace.

Happy Coding!

In the next installment I'll show you how to add menus programmatically via the API in the new Umbraco 4. See you then!