Making custom sections and trees inside Umbraco - Part I
This tutorial is for Umbraco 3! In Umbraco 4, the
possibilities for extending tree menus inside Umbraco, has been
expanded tremendously - take a look at these articles for more
info:
http://our.umbraco.org/wiki/reference/api-cheatsheet/tree-api---to-create-custom-treesapplications
http://www.geckonewmedia.com/blog/2009/8/3/how-to-create-a-custom-section-in-umbraco-4 (by Emanuel
Gaspar)
http://www.nibble.be/?p=71 (Tim Geyssens)
After digging through a lot of source code and some trial
and error I'm proud to present to you:
A little tutorial on how to make custom sections and trees for
Umbraco. This is an area where the Umbraco documentation is very
sparse, so in order to learn it, you have to piece things together
yourself.
A word of warning: As I just recently learnt how to do this,
there will be some areas where I don't have a clue at all, but I'll
update this article as I progress.
Let's start by defining what we want to archive:
- We want to add another item to the "Sections"-area of
Umbraco
- Once the item has been set up, we want to set up a tree menu
and connect it to custom .aspx files
- We also want to point one of the tree nodes
(pages) to an external site - in this case Google Analytics.
Setting up another item in 'Sections' in
Umbraco
Icons in the Sections-area must have a fixed size at 49 pixels
wide x 36 pixels high. They can be other sizes, but that would
probably look stupid as the other items have these dimensions. We
want an item called 'Extras', so fire up your favorite image
editing tool. If you haven't got any take a look at Paint.NET - it's free as
in free beer.
It's almost impossible to match the same style as the default
tray images, so if you're going to add new stuff like this, I
suggest you replace every tray item with new graphics so that it
has the same looks. Different looks makes it look unprofessional.
If you can't draw, you may consider finding a free graphics
library.
Once you're done, save the tray icon in the
'/umbraco/images/tray'-folder. You can choose
whatever file format you want, but the others are gifs, so that's
what I recommend.
Right, we got that one sorted out, so now we need to make
Umbraco aware of our new tray item. When I began exploring the
possibilities of adding a new tray icon, I thought I would find my
answers in an XML-file within the Umbraco folder structure, but no
- you need to add new items by modifying a few tables in the
database.
So, start your favorite SQL GUI tool .. I use
SQL Management Studio Express (SMS)
Find your umbraco-database and navigate to the table
'umbracoApp'
In that table you'll see different table columns:
- sortOrder - denotes the position
of your icon .. 0 is the lowest and will place
your icon first. As you can see from the image
below, I've placed my icon as number 9, so it'll be
last.
- appAlias - an umbraco alias
for your tray item, makes it independent from whatever language you
are using inside Umbraco - great if you need to access it
programmatically from ASP.NET code-behind
- appIcon - the name of your trayicon
with file extension.
- appName - the name of your
fourthcoming app, unsure where this shows up, but I guess it could
be the ALT or TITLE-text
- appInitWithTreeAlias - uncertain, I
think it will invoke a class method somewhere, because as you see,
the first item called content has 'content' written inside
appInitWithTreeAlias while the others have 'null'
(nothing).
Fig. 1.1 My additions to the table are inside the purple
box
Next we need to make an addition to the 'umbracoUser2App' table.
This table is responsible for managing whether or not a particular
user is allowed to see your icon.
I've marked my additions with a purple outline.
Table columns:
Once you have added the row above, reload Umbraco (may require a
log out) and you should be able to see your new menu item inside
umbraco! Click it and celebrate.
This concludes part I ... Tomorrow I'll show you how
to populate your new section with a tree menu and how
to add items to it.
Go to part II