How To Write Your CSS so it integrates with Episerver Easily :)

HTML integration is always one of the biggest issues in any project.  The majority of back-end developers don't have good enough front end skills to be able to tell the front-end developer what they need and many front-end developers are either new to responsive grids, don't know JavaScript and very likely don't know anything about Episerver. One of the biggest challenges when writing CSS for Episerver is that it needs to be modular. What does that mean?  In traditional web development, you might build a template that defined a fixed layout and that was that.  In the new world we have things called Blocks.  A block is a web component like an accordion or a carousel, that can usually be dropped in any content area on any page, in different orientations and with different widths.

Create a static version

When I'm working on a project, I always recommend that the html should be done in a static html site first and then integrated after it's completed.  Many people are tempted to start writing the HTML directly in Episerver and this is a very bad plan.  The static site is useful for several key reasons:

  • It allows front-end developers to work quicker as they are not having to constantly wait for a .Net page to load
  • The front end developer doesn't need to know how to use Visual Studio (or have a license)
  • When bugs are found, especially responsive stuff, it's much quicker and easier to change it on an html version then when it's intergrated into Episerver.  A front end developer needs to understand your site's page and block types, which isn't always easy for everyone to understand
  • You can fully test your site in all browsers and devices before you move it into Episerver. This is a major time saver, if you need to change html due to bugs, it can be a lot more time consuming fixing them in Episerver.  Trust Me!

Where should we store the static site?

After agreeing to use a static site on a project, the next question is usually where to create it.  For this, I recommend creating a folder in your Epi webroot called 'Static' and putting all your HTML in there.  The HTML can then reference the same CSS and JS as the Epi website.  This has the benefit later in the project that front-end developers can fix things once in the static version and, in the majority of cases, that will also fix the main website's bug.

Avoid Different Mark-up Between Desktop and Mobile

On a recent project, we had a front-end developer who was very new to Episerver and for every component on the page, created html for a desktop view and separate html for a mobile view. Asides from creating more mark-up, this makes life a lot harder/impossible to integrate.  When designing for Episerver only have one set of mark-up and use css to switch the views.  This might make the CSS a lot more complex but, unfortunately, that is one of the downsides of the new fully flexible world.

Content Areas render extra div's

After you start integrating, this issue is the biggest headache.  To get the preview and on page editing to work in the Episerver editor, Episerver renders two extra div's on top and below it. This, unfortunately, usually pushes styling out.  I have written a blog post (Episerver 7 : Extra div's in content area how to remove them ?) detailing how to remove them from the live view.  If you do not want to follow that approach, the next best solution is to simply add the extra div's into the static site in the right places and fix the bugs.  The important thing is to keep the static and main site CSS and HTML the same.  As soon as you branch off in a different direction, you'll be in a world of trouble. Another benefit of the static site is that, in the future, you can use it to trail new design ideas and add new pages simply without affecting the main website.  If you start to veer off the same html and css the static site becomes less useful later down the line.

Create a Row block

If you want a fully responsive site, especially with earlier versions of IE, then I recommend you create a custom row block.  A row block is a very basic block that simply contains a div with a row class on it and a content area inside the tags. A lot of people who don't understand grids struggle with the concept of creating the row block in the back-end, so bear with me.  In EPiServer 7 onwards, content editors now have the power to drop as many blocks (if applicable for your site, in different sizes) into a content area as they please. I'm using bootstraps for the grid system in this example, but, this example is relevant to most responsive sites. Picture a spreadsheet, we have columns and rows that make up our sheet. In a responsive page you also have columns and rows that work in a very similar manner. In bootstrap you can have a maximum of 12 columns that make up the width of your page and unlimited number of rows. If you want to have two components on the same line taking up the full width of the screen, you would create a new row and make each components have a class set to display at 6 columns widths each (two components of 6, make up the full 12 column width to get a full screen display). When we work with content editors who can drop as many blocks as they want to inside a content area, you need a way to ensure they do not break how bootstrap works. If a content editor added 5 full width blocks on top of each other into a content editor (which thay can) you would end up with a row that would have a column width of 60. When you try and re-size your browser strange things could and will happen. Ideally, you want to prevent content editors from being able to do this. A lot of technical people I know don't really understand responsive grids so how can you expect content editors to get it? This is the reason why you should create the row block. On most of my projects, I'll set all my content areas to only allow one or more row block to be added inside of it.  To add a block onto a page they need to create a row block and then drop any block they desire inside of the the row bock.  For each line a content editor wants to create on the page, they need to create a new row block in the content area. This adds a little bit more overhead for content editors but, on the flip side, the page will look a lot better on all devices. By preventing any other block except a row block to be dropped inside a content area, you can then ensure that all your components will be wrapped inside a row and will work responsively in your 12 column grid layout. The code to create a row block might look something like this: A dummy page

   [ContentType(DisplayName = "Page",
     Description = "Example Page",
     AvailableInEditMode = true)]
    public class Page: PageData
        [Display(Name = "ContentArea")]
        [AllowedTypes(new []{ typeof(RowBlock )]
        public virtual ContentArea MainContentArea{ get; set; }

The row block

   [ContentType(DisplayName = "Row Block",
     Description = "Divide area into columns",
     AvailableInEditMode = true)]
    public class RowBlock : SiteBlockData
        [Display(Name = "Columns")]
        [AllowedTypes(new []{ typeof(Block)]
        public virtual ContentArea Columns { get; set; }

The view


    <div class="row">
        @Html.PropertyFor(m => m.Columns)

Learning How To Structure the grid

On all of the projects I've worked on this issue is usually the second biggest pain point.  In a normal static site, front-end developers can do what they want to in terms of css styling as life's pretty straight-forward. For the back-end developer who has to integrate the HTML they do not have this luxury.  Back-end developers work with dynamic content. Content editors can drop a range of blocks onto a page and arrange them how they want to (what's the point of a CMS if they couldn't). It's this translation between the known static layout of page and the dynamic nature of elements that is a frequent source of frustration. In basic terms... when it comes to rendering elements in the CMS system applying a particular CSS class to individual specific areas in sequences or elements isn't always possible. From my experience of integrating static HTML the pain points are usually sequences of things, like adding a last class halfway in a list. grid_layout_example In most projects, people may want to hide different elements in tablet and mobile views.  In the example above, it's very common to have a requirement to hide elements 2 and 3 in tablet or mobile.  Writing the CSS to do this for a front-end developer is pretty simple but depending on how it's implemented, it will make life very hard to integrate it into Episerver preserving the flexibility Episerver provides. The back-end developer is working with dynamic content and they may not know the block order so adding the hide/last CSS classes on items 2 and 3 is difficult.  Applying a 'last' class is a classic example of something that is easy to implement on the static site and a lot more tricky in the back-end. A better approach is to hide the last two elements in the sequence using CSS selectors (4 and 5).  Using this approach will makes the back-end developer's life a lot easier as we can now just target the last two blocks rather than trying to do some complicated logic within the blocks just to apply a class. In terms of front-end effort it's pretty much the same. In terms of back-end sometimes it may not be possible, or, you have to come up with some dodgy hack to make it to work.   It's these very subtle changes of how you can write your CSS that can make everyone's life much happier and also get your project out the door a lot quicker.


As we have seen when integrating CSS and HTML into Episerver, it will be very likely you'll encounter a few issues along the way.  Following some of the principles in this guide should save you a lot of frustration and save valuable time for all parties involved in the project.  These slight restructuring tweaks may seem trivial but can save hours of integration woes.  The end result might not be 100% accurate to the original design but very similar.  In my experience of web projects, these small changes have never ended up as a show stoppers.  So there you have it.. good luck on your project! Do you have any integration horror stories or tips?  Share your ideas in the comment section below.

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

Back to top