In Episerver 7.5 and above, a new feature was released that allows content editors to change the widths of blocks and pages partials. In my last article How To Make A Block Use Multiple Views ? A Partial View Controller Explained
I briefly covered this topic, but today, I'm going to dig a bit deeper under the covers and explain how you can enable 'Display Options' in your site.
Why Use Display Options?
One of the benefits of allowing content editors to drop a block or a page within a content area is that they have a lot of flexibility over the layout of the page. In the old days, companies were given a template that defined the page and content editors had very little options to change that layout.
When the business decided they wanted to move a block from the left hand side to the right hand side it would have usually involve a developer or designer to make the change and redeploy. In some places that could be a two week process. Since Episerver 7.5 and the additions of blocks and display options, gone are the days of the business being stuck with fixed layouts. This gives a lot more power to the content editors, they can decide what blocks should be displayed on a page, in what order blocks should appear and now the width the block should be as well.
With this extra flexibility also comes a lot of complexity, you need to understand responsive grids and it also means our code base gets slightly more complex. Today's tutorial will guide you to setting this up in your own site.
How Display Options Works
In the editor when a user sets a display option, a tag property is stored against that block or page partial in the database. This tag can later be accessed by a partial controller, controller or template co-ordinator when a content area is being rendered.
Based on the value of this tag we can then either call a completely different view for each width, or, you can pass in a parameter to the view and change the outputted CSS to alter the width. For example, assuming you know a bit about responsive grids, you can think of this CSS change as swapping the grid width class from say 12 rows for a full-width display option to 6 rows for a half-width display option.
Setting It Up
To enable display options you will need to create an Initialization Module, I usually call mine 'DisplayRegistryInitialization' but feel free to rename it as appropriate. In this tutorial,l I am going to register 5 display options for our site but you can add or remove as many as you like. For our site we will have these options:
- Full Width
- Two Thirds
- One Third
- One Fourth
Our code will look like this:
The DisplayOptionTags class is defined below. As you can see it maps to Bootstraps grid css.
How To Render Different Sized Views
Now we have all the code we need to enable display options in Episerver, the next part of the puzzle is using this data in our views to change our partial widths. I'm going to assume you have a base partial and/or block controller in your project.
If you have no idea what I'm talking about then download my free code sample that contains a base controller from this tutorial EPiServer: Dependencies in Episerver Explained .
In our base partial controller we're going to add a method to return the display option tag.
This code also uses below two custom attributes I created:
The code also uses a custom Enum I've created called DisplayOptionEnum. One important thing to note is the BootstrapClassAttribute defined on each property which defines it's associated, bootstrap class. We will use this when we're rendering our views.
Now, in our partial view controller, we can call GetDisplayOptionTag() from the base class and get the correct display option. I'm using enums as, from previous experience, I've found it makes life a lot easier to unit test rather than just working with strings. Lastly, it uses this extension method: GetAttributeOfEnumValue is a custom extension method and can be seen here:
Displaying The Tag On The Screen
Call the GetBootstrapClass extension (also defined below) to get the correct CSS class to display.
Next define GetBootstrapClass() within the view model. Depending on how you have set-up your project will determine where this code will go. I personally always use a base view model so I'm going to stick all my code in there:
Setting The Display Option
Then in each of your block controllers you need to pass in the DisplayOptionTag, which is done like this:
We've gone through quite a lot of code to get here but finally, we now have a way to render different sized blocks based on a display-option set by the content editors. I'm using Enums a lot as I've found it a lot easier to unit test and ensure everything's working as it should be.
All the above code can be downloaded in a fully working website from my github account here. #ILoveEpiserver