In this tutorial, you will learn how to wrap items added into an Episerver content area with a Bootstrap class of row. Episerver uses something called a block to allow content editors to add components onto CMS pages. One of the hardest challenges for developers new to Episerver is deciding how to use page types and blocks in a way that makes the Episerver backend easy for content editors to use. Trust me, if you create a clunky editor experience, you won't hear the end of it from the content editors! When Episerver moved to a block architecture, it provided a new challenge for designers. The HTML that Episerver produces can vary based on the decisions of content editors. The types of blocks they add and the order in which they are added into a content area will define the pages rendered. Episerver also ships with something called the display option. A display option allows content editors to set the width of a block as can be seen below:
A display option defines the width, the block width. As seen above, content editors can select a display option from a content area. By clicking on the one they want a tag is associated against the block. In the view, you can then use that tag to render a different mark-up. Allowing content editors to decide how a block will be rendered is cool, however, it can also result in a lot of broken page layouts. For example, imagine you had a call to action block. The block was designed to render the whole page width on a landing page, what happens if the editor sets a display option of a quarter width and adds it to a sidebar?
This display option magic works by associating a tag with a block. If you are new to Episerver display options, I suggest you read this first DisplayOption to get a basic understanding of how to configure Episerver as a developer in order to take advantage of this feature.
If you're designing a responsive website (and in this day and age who isn't?), it's highly likely that you will want to use a responsive grid. Currently, BootStrap is the most popular framework so I assume you might use it! Bootstrap grids except components to be added into rows. Items in a row need to be build using a maximum of 12 columns. This brings us to an interesting challenge. If content editors can drag as many blocks as they want into a content area AND they can also set the width of each block, it is highly likely they will break the 12 columns per row requirement expected by bootstrap. Content editors are not developers so expect rules to be broken. When the rules are broken and a row is greater than 12 columns, what will the page look like?
One way of solving this issue is to configure Episerver to automatically insert rows for content editors, so they can use Episerver without needing to know anything about responsive grids. We can do this by automatically inserting a div with a class of row whenever the column width of the blocks is greater than 12. To do this we need CODE. So let us go over that code now 😊
Boilerplate Code
Before I get into the meat and veg of the code, you'll need to add a lot of boilerplate objects, enums, extensions etc.. within your project in order to get the code below to compile. This section will cover all the code you should need:
BootstrapClass Attribute:
Display Options Enum:
Configuring Episerver To Use Display Options:
Custom Class Used For Rendering Blocks With A Row:
Convert A String To Enum:
How To Build A Bootstrap Aware Content Area
We have finally got to the class where most of the magic will happen. First, a method will be required to keep track of the current running column width count. We need this so when the blocks exceed 12 columns, the row div can be injected.
I created this code using a custom HTML helper that you can call within your Razor views. Another option would have been to enforce this rule in all content areas. This is possible, however, I do not recommend it. Using an HTML helper will mean you can pick and choose when your website is BootStrap aware. If you use content areas to create the primary nav, for example, it is likely you won't want to wrap your menu items in row divs! The code to define the HTML helper is shown below:
An example of how you can use the helper in a view would look liek this:
This is all the code you need to make your Episerver CMS-powered website Bootstrap grid aware! If you struggled to keep up, all the above codes can be downloaded to a fully working website from my GitHub account here. #ILoveEpiserver
In this tutorial, I've talked about the HTML challenges a flexible block architecture brings to designers and developers who wish to make a high-quality easy to use product. The more power and flexibility that you give to content editors, the more you will need to consider how you will ensure that the HTML Episerver produces contains all the divs and class names needed to make a page look good. As with most development tasks, I wouldn't say there's one 'right way of dealing with this scenario and there are several techniques that you could use. To make the content lives as pain-free as possible, automatically inserting the Bootstrap row grid when it's needed does make the backend easier to use. Happy Coding 🤘
If you want to implement this you will need to create a custom HTML helper and you will also need to extend the default Content Area to render out the row HTML. Extending it is pretty easy when you get your head around it. Â You can always use Dotpeek to go through the default Episerver content area to help you understand how Episerver works out the box.
