Being able to execute custom code when a specific document event occurs is an important part of Umbraco development and is made pretty easy thanks to the events of the “ContentService”.
Say that we have a document type with the alias “documentTypeA” and we would like to execute some code when a document of this type is being saved. The traditional way consists in creating an application event handler like the one below:
This works pretty fine when having few document types or few handlers but when you have a lot of them, it can become pretty messy. Indeed, what if you want to subscribe to several events? You’ll need to duplicate the “if” in each method or you’ll have to create another method that accept an “Action” to execute your code, etc… At the end, you could end up with a code like this:
Even though it works, it’s a bit cumbersome to always do these checks. Therefore, I wrote a little plugin to make it easier to handle events.
Basically, the idea is to create a class that is responsible of handling events of one or several document types identified by an attribute. For example, you could create the following class to handle the events of all documents based on the document type “documentTypeA”.
The first thing to do is to apply the “DocumentEventHandler” attribute on the class to define what document types this class handles. You can leverage this by using two different properties:
- Include: Defines the name of the document types handled by the class. If this property is not defined, the class handles all the document types except the one defined in the “Exclude” property.
- Exclude: Defines the name of the document types that the class must not handle. This is particularly useful when you don’t define the “Include” property (for example to define that the class handles all document type but “X”).
The second thing to do is to inherit from “DocumentEventHandler”. This abstract class contains virtual methods that you have to override to handle the specified event. All the Umbraco native events are supported except “DeletingVersions” and “DeletedVersions”.
With this plugin, the “complex” example above could be simplified this way.
Now that your document event handler classes are defined, there is two way to register them (in order to let “uDocumentEventHandler” know about them).
The first option consists in adding the following “appSetting” in your “web.config” file:
The value of this “appSetting” must be the name of the assembly that contains the document event handler classes. This way, “uDocumentEventHandler” analyses it and registers all the class that inherit from “DocumentEventHandler”.
If you don’t want to touch the “web.config” file, you can also create a custom application event handler to register your assembly.
Once again, you just need to pass the assembly that contain the classes to the “Bind” method of the “DocumentEventHandlerBinder” static class and that’s it.
This plugins works well with “ModelBuilder”. Indeed, instead of typing the alias of the document type, you could use the value of the “ModelTypeAlias” property of the class generated by “ModelBuilder”.
To install the package, you have two solutions:
- Nuget (recommended): Just run the command “Install-Package AreaProg.uDocumentEventHandler”.
- Umbraco package
Personally, I prefer, by far, using NuGet packages as it will directly add the DLL as a reference to your project.
The namespace of the project is “AreaProg.uDocumentEventHandler“.
If you’re interested, the project is also hosted on GitHub, so if you use this package and encounter a bug or have a suggestion, don’t hesitate to create a new issue 😉