Umbraco Action Handlers 101

Kevin — Thu, 14 Feb 2008 02:12:00 GMT

Something I have done a few times in Sitecore is to have new news articles or blog posts automatically organize themselves within year/month folders in my content tree. The URL to a specific news article might be /news/2008/02/ActionHandler.aspx for instance. When I create the ActionHandler content item, the 2008 folder and the 02 folder would be created automatically if they did not already exist and my posting would be placed under these folders for me. In Sitecore, I do this with an event handler for item:creating. Tonight, I set out to do the same thing with Umbraco.

First, let me present an example of what I want to see when I'm done...

I want to be able to right-click on "Blog" and create a new document of type "BlogPost". Given today's date, I want a year folder and a month folder to be created (if they don't already exist) and my new post moved into the proper folder automatically.

A bit of research uncovered Umbraco's concept of Action Handlers. Basically, these are your own classes you can use to perform custom actions when certain events occur in Umbraco's content editor. They just have to implement the umbraco.BusinessLogic.Actions.IActionHandler interface and exist in an assembly in the Umbraco bin folder.

So, I set out to implement my DateFolderActionHandler class... I created a new class library project, added references to Umbraco's businesslogic.dll, cms.dll, and interfaces.dll, and added a class that implements IActionHandler. Visual Studio was kind enough to fill in a skeleton implementation for me - here's what it looked like:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using umbraco.BusinessLogic.Actions;

using umbraco.BusinessLogic.console;

using umbraco.cms.businesslogic.web;

namespace Demo

    class DateFolderActionHandler : IActionHandler

        #region IActionHandler Members

        public bool Execute(Document documentObject, umbraco.interfaces.IAction action)

            throw new NotImplementedException();

        public string HandlerName()

            throw new NotImplementedException();

        public umbraco.interfaces.IAction[] ReturnActions()

            throw new NotImplementedException();

        #endregion

The first method that grabbed my attention was HandlerName() - all I have to do is return a string! I did some digging with Reflector and it doesn't appear to be used for anything important, so return anything you want from this method. I used "DateFolderActionHandler" - the name of my class.

Next up - ReturnActions(). This appears to return a list of actions your handler wants to be notified of. The actions you can choose from are members of the umbraco.BusinessLogic.Actions namespace. My handler needs to execute when a new content item is created, so I'm using ActionNew(). ReturnActions() now looks like this:

public umbraco.interfaces.IAction[] ReturnActions()

    return new umbraco.interfaces.IAction[] { new umbraco.BusinessLogic.Actions.ActionNew() };

Last to implement is the Execute() method. I'm guessing Execute() gets called when one of the actions you have subscribed to occurs. The Document must be the content item that was acted upon and the IAction must be the action that was triggered. In my case, I am only subscribing to ActionNew so I don't have to check the action, but I will in this example to demonstrate how it's done.

// Not interested in anything but "create" events.

if (action.Alias != "create") return true;

My action handler will be called for every new content item that is created, so the first thing I will want to do is verify that this document is one that I'm interested in. I checked the content type like this:

// Not interested if the item being added is not a blog post.

if (documentObject.ContentType.Alias != "BlogPost") return true;

Note that I am returning true on both of these cases. My assumption was that the return value from Execute() indicated if the action should be allowed to continue or not. After playing around with returning false (and peeking at the code with Reflector), it appears the return value is just ignored. Shame on Umbraco - there does not appear to be any way to cancel an action! Even throwing an exception here doesn't keep the action from happening. Anyway - I will continue to return true when I want the action to complete and false if I don't in hopes that it will someday make a difference. :)

So if my code is still executing, I know I have a new document that I'm interested in placing in date folders. I want a folder for the year and a folder for the month, so I'll start with the current date.

string year = DateTime.Now.ToString("yyyy");

string month = DateTime.Now.ToString("MM");

As I mentioned at the start of this article, I expect the new document to be created as a child of "Blog". The year folder should also exist as a child of "Blog". My first task is to check if that already exists. Here's the code I used:

Document yearDocument = null;

foreach (IconI child in documentObject.Parent.Children)

    if (child.Text == year)

        yearDocument = new Document(child.Id);

        break;

(note - I have no idea why the members of documentObject.Parent.Children are of type "IconI". Maybe someone that knows Umbraco better can answer that?)

What this does is get the new item's parent's children (children of "Blog") and loops through them looking for one whose name matches the current year. If we make it through this loop and yearDocument is still null, we know the folder doesn't exist and needs to be created. Here is how I handle that:

// If the year folder doesn't exist, create it.

if (yearDocument == null)

    yearDocument = Document.MakeNew(year, DocumentType.GetByAlias("YearFolder"), documentObject.User, documentObject.Parent.Id);

The Document.MakeNew() call creates a new content item named for the current year, using the document type "YearFolder", created by the same user that created the blog post, underneath the parent of the blog post ("Blog").

Now I have to repeat the same process for the month folder...

Document monthDocument = null;

foreach (IconI child in yearDocument.Children)

    if (child.Text == month)

        monthDocument = new Document(child.Id);

        break;

// If the month folder doesn't exist, create it.

if (monthDocument == null)

    monthDocument = Document.MakeNew(month, DocumentType.GetByAlias("MonthFolder"), documentObject.User, yearDocument.Id);

And the final step is to move the new content item into the month folder...

// Move the document into the month folder.

documentObject.Move(monthDocument.Id);

Then I can just return true and I'm done!

If you want to see the final DateFolderActionHandler.cs source file, I have attached it to this blog post.

Hello World

Kevin — Thu, 24 Jan 2008 16:15:00 GMT

Ok, time for the usual lame first blog post to test that everything is set up properly, yada yada... Maybe an introduction? I'm currently working as a consultant doing .NET and web development work in Tulsa, OK. I have worked with lots of programming languages over the years including C/C++, Python, Java, VB, C#, and others. I've developed for various Unix platforms, done some Mac development, lots of web development, and for Windows of course.

No idea what exactly I'll be writing about on this blog. Right now, I'm playing with an open source .NET CMS called Umbraco as well as messing with using Cocoa# to put native Mac GUIs on my .NET programs, so those topics are sure to show up. I also work with the Sitecore CMS a lot at work, so that might show up here as well.

Kevin Williams .NET and Stuff : Umbraco

Umbraco Action Handlers 101

Hello World