In this tutorial, you will learn how to create a dropdown list and a checkbox list within Episerver CMS. The interesting twist in this tutorial is that we will get the data for these properties from the options defined within a bunch of custom enums. A very frequent requirement on projects is to give content editors the ability to pick from a list of things. Usability wise the best component to allow a user to pick an option from a range of items is usually either a drop-down or check-box list. Within Episerver CMS you can give this ability to a content editor via a selection factory property.
Understanding how this property works will give you a lot more content modelling power. Want to learn more, read on 🔥🔥🔥
What is a Selection Factory?
A selection factory is a dynamic CMS component that allows you as a developer to populate a selectable list within the editor with some type of data. To create a list you decorate a property with SelectOne. To create a checkbox, you decorate a property with the SelectMany attribute.
Both SelectOne and SelectMany require a data source specified when used. This is done via constructor property called SelectionFactoryType. SelectionFactoryType will provide the property with the data required to populate the items in either dropdown or checkbox. This data source will require you to create a custom class. This class is known as the selection factory. To add a data source to a property you will add the property with the SelectionFactoryType when adding the attribute. To create a selection factory, you will need to create a class implemented from the ISelectionFactory interface. As seen below:
To associate the selection factory onto a page or block property, you create a property and decorate it with a SelectOne or SelectMany. Add the CurrentSelectionFactory property, job done 💥
When you create a class that implement ISelectionFactory you will need to implement the GetSelections() method:
It is within this method, where add the code to fetch whatever data you need.
A Page Type Selection Factory
Now we've gone over a simple example with hardcoded values, let us go over the code to dynamically get data. Imagine we want to return a list of metadata stored in a page type called category. All category pages have been created within the CMS under the root node, under a page called Category Settings which is of type Category Root. To query for this data in code, we call the root page. In the Get() called we search the roto pages children to find the Category Root page. After finding it, we can use the Children property to get the meta-data for our list.
TIP: If you are unsure about the best way to store meta-data and settings in Episerver CMS, I would recommend reading The Best Ways To Store Site Settings in Episerver 💥
In the GetSelections() method we call GetCategories(). Here, we first get a reference to the root page. The code iterates through the list to find the category root. Performance-wise as this is a one-off call made infrequently by content editors, I would not normally worry about optimizing the code with caching. In a high traffic project, you could optimize this if you notice performance problems. After getting the data, items are added to a list of ISelectItem and returned. We're done. 🔥🔥🔥
This is all the code required to create dynamic drop-down and checkbox properties within the CMS. Simples. Happy Coding 🤘
