In this tutorial, you will learn how to create a custom checkbox picker property for Episerver CMS v6. Episerver is great at a lot of things, however, it does not ship with a very powerful tagging system. It is possible to define a single list of items that all page templates can access. A client had a requirement to create tags based on the specific page types the content editor was using Adding a global cat tagging solution would not need the client's needs, content editors would be able to add invalid tags onto page type.

After some research, I found a good article here that solved a similar problem. When I implemented this solution, I encountered a lot of issues around saving. With the proposed solution, if you clicked save twice the data would be lost. In this tutorial, I have created an updated component based on that article which is a little bit more robust.

This property works in a slightly non-intuitive way. The property needs to be configurable as it needs to read in tag data depending on which page types it's accessed on. This property uses the HelpText attribute to define which part of the category tree the property should read the data from. The HelpText value ArticleRoot matches a name that I've set up in my categories.

One important thing to note is that even though the type is PropertyCategoryCheckboxList the underlining data type is string. The property will allow a content editor to select one or more selections. This means that data will need to be saved as a comma-separated list. Let us now look at the code required to build the property:

The code is pretty simple. Inherit from the Episerver property, PropertyMultipleValue and in CreatePropertyControl() return a new custom control. Let us create that controller now:

Let us step through what is happening in the code above

  • Line 13, gets the value of help text, if none exits try to get a fallback value

  • Line 15, uses Category.Find() to query the CMS for the data

  • Line 28, passes in a list of CMS items into GetCategoryIds()

  • Line 53, the un-flattens the list and passes it back

  • Line 32, iterate through the list and create some HTML elements, select any of the entries that have been previously selected.

  • Line 34, the HTML are rendered within the CMS

The last part of the puzzle is ApplyEditChange and storing the selected values. This was the main issue I had with the code I found online. I fixed the code like this:

The big difference with the code is that I store the selection using the PropertyData.Value rather than creating a clone of the page and trying to save that clone. All this code is doing :

  • Loop through the checkbox list displayed and store anything that is ticked in categoryIdList

  • Iterate through cateogryIdListand create a string of Id's separated by a comma

  • Store this string using PropertyData.Value

If the code above works when you view the property in the Episerver editor, you should have a checkbox list on your page type that pulls in all the child categories. You now have a custom Episerver property that allows users to select from a list. You can find some demo code here. Happy Coding 🤘