In this tutorial, you will learn how to use the UIDescriptor within Episerver CMS to customise how the editor looks. Specifically, you will learn how to configure Episerver CMS to use custom icons within the content tree. My mantra to CMS developments, is that happy content editors can make or break a project. Content editors are the people who will use the CMS on a daily basis. If you fail to architect the backend so it is easy for them to use, they moan. When enough people moan, despite how hard you worked, your project might be classed as a failure. Adding little icons that allow a content editor to quickly find the pages they are looking for will make it that much easier for them to use your system. If you want to be known as a legend by the content team, read on 🔥🔥🔥
How To Use Custom Icons For Specific Page Types In The Episerver Navigation Tree
From Episerver v7.5+ onwards, you can use a UIDescriptor to hook into the editor UI. UIDescriptor will provide you with some degree of control over how content types are displayed in the CMS. When you open the editor, in the background Episerver goes out and creates a number of EPiServer.Shell.UIDescriptor objects that define how various things within the editor will behave. The UIDescriptor allows you to hook into this pipeline and define how Episerver behaves.
In this tutorial, we will use a simple example that uses a container page-type. Any page type that implements a interface I have defined called IContainer will render within the navigation tree with a folder icon 😊
To get this up and running, we will use an initialization module. This initialization module will be trigger whenever the CMS is first loaded on application start. To add a UIDescriptor you will use the UIDescriptorRegistry API. UIDescriptorRegistry can be used to get a list of these populated UIDescriptor:
This is a lot of code, so lets us break us down into smaller chunks:
Note: This code sample uses the my JonDJones.IconPack, available from here
This code uses reflection to find the page types that implement the IContainer interface:
This code gets all the UI descriptors registered within Episerver:
This code compares the two lists and finds any matches. If a match is found, its IconClass property is updated with an icon defined within the JonDJones.IconPack assembly. Build this code and the next time you reload the editor, you should see the new icon:
You can obviously use whatever form of look-up to find the descriptors whose icon that you want to change. In most instances you will do the cast based on the page type definition rather than an interface. I have used an interface in this tutorial to demonstrate how you can target many types at the same time.
There is also an alternative way to create and register a UIDescriptor. You can implicitly register a descriptor yourself:
This code does the same as the code above, it just works on a single item per class. My personal preference is to use a initialisation module to register all the icons in one place. I find having a single class to manage everything easier to work with in code 😕 As always my normal advice applies, do what makes you happy ❤️
You are now an Episerver icon guru 🧘🧘🧘 Happy Coding 🤘
