How to implement an Action Handler

How-to
This How To will explain what ActionHandlers are and how you can write and use your own ActionHandlers.

Chapters

• Chapter 1: What is an Action Handler?
• Chapter 2: How to implement an Action Handler
• Chapter 3: How to install the Action Handler
• Chapter 4: Supported Actions

How to implement an Action Handler

You can implement your own Action Handler in any .NET project as own class. In this example I will do an own class library project to show how the complete cycle is.

1. So in VS.NET create a new class library project. Give it a name of your choice. In this example the name of the project is TH.Umb.Sandbox.Library.
2. Add a new class and give it a name of your choice. In this example the name of the class is DefaultValueHandler
3. Add references to businesslogic.dll, cms.dll and interfaces.dll from the umbraco bin folder.
4. Let the class implement the interface umbraco.BusinessLogic.Actions.IActionHandler.
5. Implement the function HandlerName which returns the name of this Action Handler.
6. Implement the function ReturnActions which defines on which actions this Action Handler will react.
7. Last but not least implement the function Execute which is doing the job. Here you can define what code should be executed on this action.

So at least you should have a code like this:

using System;

namespace TH.Umb.Sandbox.Library
{
    public class DefaultValueHandler : umbraco.BusinessLogic.Actions.IActionHandler
    {
        string umbraco.BusinessLogic.Actions.IActionHandler.HandlerName()
        {
            return "TH.Umb.Sandbox.Library.DefaultValueHandler";
        }

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

        Boolean umbraco.BusinessLogic.Actions.IActionHandler.Execute(umbraco.cms.businesslogic.web.Document documentObject, umbraco.interfaces.IAction action)
        {
            if (documentObject.ContentType.Alias == "th_sandbox_defaultvaluetest") 
            {
                try
                {
                    umbraco.cms.businesslogic.property.Property p = documentObject.getProperty("DefaultValueProperty");
                    if (p == null) { return false; }
                    p.Value = "This is the default value set by an action handler";
                    documentObject.Save();
                }
                catch (Exception)
                {
                    return false;
                }
                return true;
            }
            else
            {
                return false;
            }
        }
    }
}

One word the the function ReturnActions: The returned variable is an array of actions. So you can return more than one action. Therefore you can handle more than one type of action with one Action Handler.

One word to the function Execute: The first parameter you get in this function is named documentObject and it is the Document on which this action is performing. The second parameter is the action which is performing. So if you have set more than one action in ReturnActions you can differ which action you are handling in this moment.