In this tutorial, you will learn how to set a default display option when rendering blocks within Episerver CMS. If you are new to Episerver display options, then I suggest you read this article first, How To Configure Episerver To Allow Users To Render Blocks At Different Sizes. When we work with Episerver and we want to allow content editors to define the widths of the blocks, we need to enable something called a display option. An example of how display options appear within the editor can be seen below:
When you enable the display option feature within Episerver, you can provide a lot more power and flexibility to the content editor, however, you also introduce a little bit more technical complexity as well.... On a normal project, you definitely don't want every single block to display by default in the same way. For example, a carousel will usually display as full-width, while a spotlight block will only ever be required to take up a half-width
This requirement of not wanting all blocks to be rendered in every single way possible highlights one of the main issues with display options in Episerver out-of-the-box.... it's an all/or nothing feature. When you enable display options, every single block will magically have a 'Display As' option next to it that will allow a content editor to specify the width of the block. The editor will be given the complete list of options for every single block. In terms of usability, this is not a great experience. As mentioned, some rendering options may not be required for certain blocks. Rendering a block at a certain width might make it render incorrectly. Giving editors options that they should not use is not ideal. As a developer if you want to provide a good CMS experience for your editors, you'll need to figure to come up with a solution.
You will never want every single block within your solution to be configurable to every width possible. If you followed my first tutorial about display options, then by default, all blocks will be rendered as full-width controls. On most projects, however, the reality is that you will want the automatic display option to behave differently on a per-block basis. In today's tutorial, I'm going to cover all the code that you will need to accomplish that in Episerver... so let's begin.
How Can I Make Sure My Episerver Blocks Look Correct?
When it comes to ensuring content editors use the right display option we have a few options:
Trust the content editors. In most places I've worked, content editors aren't stupid. If they publish a page and it doesn't look good, they remove it, edit it, or they experiment with the display option until it looks OK. This option of doing nothing is the quickest and easiest for developers. In some companies, like finance or legal, this may not be viable.
If the block only needs to render in one way, don't inject the display tag option into it... d'uh! This is also simple to implement. Make multiple views for all the different widths per block, called a shared partial view from each and implement the HTML once. This approach is OK, however, it might make the editor look broken. When the editor changes display options in the editor the block will always appear the same way 😱
Only render the appropriate display options per block using validation. This is the cleanest option and the one I recommend. This validation also allows you to cater for another scenario. What happens when you need two or more display options? For the remainder of this tutorial, this is the path we will take
Boiler Plate Code
To get this validation working we need a lot of boilerplate code. As the code spans duplicate classes, I've also uploaded an end-to-end example of how this works in my Episerver base build, available here which has a working version of everything in this tutorial.
The first thing we will need is an enum to store the display options:
Whenever I enable Display Options on a project, I recommend using a custom DisplayOptionEnum enum to get you a compile typed way of differing between the options. IntelliSense makes me happy 😊. As we want to write testable code I advise you to create some interfaces:
To set a default display option size on a block, we need a way to identify it. I'm a big advocate of solid and design patterns, so whenever I need to do anything like this I always go for composition over inheritance. If you add this interface to a block, it will be easy to identify the block as something with a default size. This will be useful later on.
Lets see how we can implement the interface on a block-type definition:
Next, let's look at the code where the magic happens! The content area!
In this class I inherit from ContentAreaRendered and override the GetContentAreaItemTemplateTag method. This is how we change the default Episerver behaviour. In this method, we're passing in the ContentAreaItem so all we have to do is check our interface is present. If the display option hasn't been set and the block implements the IDefaultDisplayOption interface, we return that value. The code's pretty simple, but it does everything we need it to.
Lastly, we need a way to call our custom content area to render within our view so we can pass a content area into it and get the correct view returned. This is done using this extension method:
The Razor HTML code looks like this:
With all this code you now have a way to add default display options to your blocks. Happy Coding 🤘
