Creating a custom Umbraco section

In this tutorial i will show you how to build a custom section and bind a App Plugin.

First of all every section in Umbraco is called an application, so sections and applications is basically the same thing

 

The following image shows the result.

 

It's important to understand the anatonmy between the 3 main "Objects"

 

  1. Section
  2. TreeController
  3. (your custom) App Plugin

 

The following image show the connection between them.

 

 

...so let's start coding

The first thing we’ll need to do is to create the application. So you create a Plugin under thge "App_Plugin" order and register ist.

For this w’ll need to create a class that implements the IApplication-interface so that Umbraco will initialize this class on start up.

 

Create a cs class in your project  and name it "Section.cs" . you can name and place it how you want. i prefere to create a Folder "Classes" under the App Root to save my Section class.

[Application("ExampleSection", "Example Section", "icon-users", 8)]
    public class MyExampleSection : IApplication
    {
    }

 

  • Application name = Example Section
  • Application alias = ExampleSection
  • icon = icon-user
  • sort order = 8 

 

This cs class will create or change at run time the applications.config file which is located under YourProject/Config/Applications.config

 

 

 

After declaring our section/application we have to create the Tree.

An application without a tree is not worth anything

 

This part contains some new concepts for V7.

Let's start with creating a new class that inherits from Umbraco.Web.Trees.TreeController, make sure to suffix the class name with “Controller” ie. CustomSectionTreeController and save it under the "Controllers" folder.

 

Here's the code for the TreeController. Let's analyse it.

// name = section it belongs to
    // alias the tree alias
    // name = and it's name
    [Tree("ExampleSection", "myTree", "My Tree")]
    [PluginController("MyPackage")]
    public class MyCustomTreeController : TreeController
    {
        protected override TreeNodeCollection GetTreeNodes(string id, FormDataCollection queryStrings)
        {
            //check if we're rendering the root node's children
            if (id == Constants.System.Root.ToInvariantString())
            {
                var tree = new TreeNodeCollection
            {
                CreateTreeNode("1",id, queryStrings, "My Node 1"), 
                CreateTreeNode("2",id, queryStrings, "My Node 2"), 
                CreateTreeNode("3",id, queryStrings, "My Node 3")
            };
                return tree;
            }
            //this tree doesn't suport rendering more than 1 level
            throw new NotSupportedException();
        }

        protected override MenuItemCollection GetMenuForNode(string id, FormDataCollection queryStrings)
        {
            var menu = new MenuItemCollection();
            var m = new MenuItem("create", "Create");
            menu.Items.Add(m);
            return menu;
        }
    }

 

We have to add 2 attributes to your TreeController.

The first one works like our Section Class and creates or changes the trees.config at runtime, file which is located too under the Config folder

[Tree("AppName", "TreeAlias", "TreeName")]
  • AppName = Section it belongs to
  • TreeAlias = the tree alias 
  • TreeName = the tree name

 

This is how it should look after starting your project

 

 

[PluginController("MyPackage")]

This attribute tells Umbraco that this class is part of a plugin, and it also tells Umbraco the name of that plugin. This will make Umbraco look for views inside the /App_Plugin/{NameOfApplication}/-folder and not in the folder of the core-views which is the default.

In our case the folder structure should look like  YourProject/App_Plugin/MyPackage

 

The result should now

and the context menu...

 

 

 

Displaying our new section

To display our new section we need to give the current user access to it. Go to the users-section and open the edit-view for the current logged on user. In the bottom, check the checkbox for [ExampleSection] and hit save. Now you’ll probably need to refresh the page using F5 to show the new section in the left side bar.

 

Making the [CustomSection]-text look better

Since Umbraco can’t find any language translation for our section it will use the brackets and the application name. To make this nicer, open the /umbraco/config/lang/en.xml-field and look for the <area alias=”sections”>-element. Inside that element, just add:

<key alias="ExampleSection">My First Section</key>

 

At least i will show you a diagramm which should give you an overview of the relations

 

Author

Caglar Tasci

Beauty is more important in computing than anywhere else in technology because software is so complicated. Beauty is the ultimate defence against complexity. — David Gelernter

comments powered by Disqus