Personalisation Groups for Umbraco
The following is one of a series of posts introducing various open-source projects Zone has developed and made available for others to use. Some come from personal side-projects and others where we’ve been able to identify general solutions to specific problems we’ve worked on for our clients — who we thank for allowing their contributions to these projects to be released in this manner. Here Zone’s head of .Net, Andy Butland, shares the basics of a package that brings personalisation to the Umbraco content management system…
Personalisation of website content is a theme we are hearing more and more from both our clients and in internal conversations as we scope out the features for the sites we build at Zone.
We work with a number of CMS platforms, some of which offer out of the box features in this area. As things stand, unfortunately Umbraco currently doesn’t bring a great deal to the table for this.
I was lucky enough to attend a recent get together of a small number of the Umbraco core team and community members where this was a topic under discussion. The outcome of that was that this type of feature is now on the Umbraco road-map as was revealed in the key-note at the recent Codegarden conference.
So down the track we should see more features in the core. For now though, we’ve put together a freely available, open-source package that may help with these type of features for anyone looking to build personalisation into their Umbraco sites now.
How to use it
To install, you can add the package to your Umbraco installation in the standard way, download from the project page on our.umbraco.org and install via the back-office Developer section.
The package contains a couple of document types and data types that allow you to create group definitions. These definitions are made up of one or more criteria.
So for example you might have a Weekday morning visitors definition that is targeted using the Day of week and Time of day criteria with the appropriate days and time ranges selected.
Various criteria come with the package itself:
- Authentication status
- Cookie and/or session key presence/absence and value matching
- Country (via IP matching)
- Day of week
- Pages viewed
- Time of day
- Umbraco member group, type or profile field
And you can also add your own.
With these group definitions set up you can associate them with your pages.
Lastly, within your templates you’ll find a new extension method on all instances of IPublishedContent called ShowToVisitor(). Using that you can add the necessary behaviour to your templates to show or hide content based on the details of the current visitor.
How it works
The core of the package is the definition of the personalisation group show in the screenshots above. This is implemented as a custom Umbraco property editor using angularjs. Each criteria consists of an angular view and controller, along with an additional and service used for translating the internal representation of the group definition to something understandable by a content editor.
Most importantly though, on the server-side each criteria implemented an interface called `IPersonalisationGroupCriteria. As well a some properties to describe the criteria, there’s a single method that must be implemented by all criteria with functionality to determine if a particular aspect of the current visitor matches the criteria definition. So for example the “day of week” criteria checks what the current day is to determine a match.
This interface is what allows the package to be extensible — if a given criteria for the particular requirements you have isn’t available, you can create your own criteria by implementing this interface and following the conventions for the associated client-side assets.
When a Umbraco application using the package starts-up, all assemblies are scanned for classes that implement this interface and they are added as criteria that the editor can select from.
With this in place the editor can create personalisation groups and associate them with content. There remains though a step the developer still has to take which is to augment the template rendering to make use of the personalisation information. This is done via an extension method implemented on instances of IPublishedContent, such as Model.Content or the results of Umbraco node queries.
One simple example would be to only show certain instances of repeated content that match the current site visitor’s profile — which you could do like this:
@foreach (var post in Model.Content.Children.Where(x => x.ShowToVisitor())){<h2><a href=”@post.Url”>@post.Name</a></h2>}
Further information
To read more about the features and technology behind this package — and of course to view and perhaps contribute to the source — please see the following GitHub project. There’s also a more in-depth article introducing the package and discussing personalisation in Umbraco more generally published at Skrift.io
