In this tutorial, you will gain a little more knowledge about integrating HTML within an Episerver powered website. One common mistake I often see frontend developers who are new to Episerver CMS make is assuming the HTML Episerver generates will be exactly as they expect it to be. Frontend designers will often work on a static HTML build that will eventually be integrated into Episerver. When writing HTML, a lot of designers who are new to Episerver make the mistake of forgetting about the end goal, the Episerver integration. If a frontend developer solely focuses on the static HTML and assumes that the CMS will render the mark-up exactly how they want it to, this can cause integration woes. Let me explain how this happens.

On a lot of projects, a front-end developer converts a design into static HTML. A backend developer takes this HTML and adds it into the views within the .NET solution. When the backend developer integrates the HTML things can become interesting. The HTML may end up being added as part of an Episerver page template, it might be added into an Episerver block, or even an Episerver page partial. A good backend developer will design the components available within the Episerver backend so it is easy for a content editor to use the CMS. designing a good content editor experience means that the HTML might not be copied exactly as the frontend developer expects.

On most projects, the frontend developer will not be an Episerver expert. They will not understand the best way to design the CMS. Content modelling is usually a job that is left for the backend developer. If some HTML is added into the CMS in a way the frontend is not expecting, this cause confusion between the different disciplines within the team. If you are a frontend developer reading this statement and it confuses you, don't worry you are not alone. If you find yourself in this situation, I'm hoping this tutorial will explain the issue a little bit better. Sound good, read on!

How To Convert HTML Components Into Episerver Blocks

Episerver’s architecture is based on a page and blocks model. An HTML page template will get converted into an Episerver page type. If the design has components that are shared between pages this will be created within Episerver as blocks. This means an HTML component MAY be converted into an Episerver block. I say MAY in bold as on some pages, HTML components may, or, may not directly map into a corresponding Episerver block.

I will personally aim to design the CMS so it is simple for content editors to use. This is the end goal of the system. In 5 years time, I want to build something that content editors enjoy. Building unneeded components in the CMS just to mirror up with a design that was built by someone who does not understand the CMS will not help you to move towards that goal. In some circumstances, it will, others not so much. How I split a design into an Episerver architecture will be based on the uniqueness of the component and if it is re-used anywhere else within the website.

A log-in page to a secure member area is always a good example of a fairly static Episerver template as it will use features that are not needed anywhere else. Content editor experience-wise, you never want to add dynamic areas into templates that should never change. In this example, a content editor should not be able to remove the log-in form, so it makes little sense to split the design up further. If a page is fixed and the components aren't used anywhere else, the question arises, what’s the point of splitting the page up further into Episerver blocks?

The more blocks you create in Episerver, the harder you make it for content editors to find what they are looking for. Have you ever felt very indecisive in a supermarket when picking something with hundreds of slight variations, like what type of pasta source to pick? The same thing happens when a content editor needs to choose from hundreds of different types of blocks. The more unneeded blocks you create, the more code you need to maintain. More code increases the scope of more bugs creeping into the system. Having an excess number of blocks can also increase the CMS response times. Keeping a lean block library has multiple benefits.

In the old days of CMS development, you had very rigid templates that had very fixed layouts. If you wanted to change the layout, a developer would be called upon and told to tinker with the template to change the layout as required. This process of needing a designer/developer to change a webpage layout is pants 🩲🩲🩲. The business has to wait on developer availability, a QA will be required to test the work and a release needs to be scheduled. The good thing about this process was that the HTML a designer would write would pretty much map directly to an Episerver template.

When Episerver moved to a block-based architecture, this was a great improvement for content editors, however, it added an extra level of complexity. The process of converting HTML into Episerver became harder. In a block architecture, you can define very flexible templates and let content editors basically design how they want the page to look themselves (within guidelines). Getting the right balance, between designing a solution that is flexible and not overly complex for content editors is a new skill that people who implement Episerver will need to learn. To develop a system that is flexible, the HTML will also need to be written in a way to cater for this, let me explain.

Episerver components are dynamic which means the end mark-up produced by Episerver is also dynamic. A block can be configured in such a way where a content editor can decide the width of each component using a display option. Another way a block is dynamic is through its properties. By adding custom properties onto a block it is possible to allow a content editor to select/unselect options that will change how the block looks. This means that to make a good CMS component it might make more sense to combine two (or more) similar HTML components into a single block. Properties can be added to the block that will allow a content editor to decide how it gets rendered. This approach can be better than creating two different blocks. It is easy to create a block that renders different HTML depending on content editor preferences. Let us see an example:

As a developer, I could create a block with a property of type dropdown list, called style. For this example, style has two options. Depending on which option the content editor picks will determine which CSS class name gets added/rendered in the final page markup:

being able to inject class name or even change the whole components HTML means you can create a nice editor expeirence and keeping the total numebr of blocks to a minimum. I've come across numerous designs that fail to consider the dynamic abilities of Episerver. Instead of thinking in terms of Episerver blocks, the designers only think in terms of HTML.  

How I Recommend A Frontend Developer Getting Started With Episerver

Being able to inject a class name or even change the whole components HTML means you can keep the total number of blocks shipped within a project to a minimum. I've come across numerous designs that fail to consider the dynamic abilities of Episerver. A lot of agencies seem to ship blocks solely based on the design. This means that they are creating bad editor experiences. Just because HTML components make sense at the very start of a project, does not mean they will map to a great Episerver block architecture.

How I Recommend A Frontend Developer Getting Started With Episerver

I'm hoping this post doesn't scare or confuse you too much! If you are an HTML designer working with Episerver, especially for the first time, before you start writing any HTML I would recommend that you sit down and closely work with the developer who will be integrating the HTML into Episerver first.

Between the two of you, you should be able to get a good understanding of how the design will be split into Episerver components. Without this upfront conversation, it's very common to see designers go off in an HTML tangent and design the HTML in a way that works well for a static HTML site, but, doesn't integrate with Episerver and the needs of a content editor. The Episerver block architecture provides a lot more flexibility in terms of how content editors interact with the CMS and also how they design the layout of the website. With this flexibility, however, comes a trade-off in terms of the end mark-up that gets rendered on your website. How you structure your HTML will need to be in line with this flexibility. How the design will be split into Episerver blocks should be factored into how you write the HTML in the first place. If you start designing your HTML without this consideration, it is very likely you will have to re-do a lot of work later on.

70% of the time an HTML component will directly map into an Episerver block, however, in some instances, it will require re-work. To minimize the amount of re-work you need to build your HTML with the end Episerver block in mind. If the HTML has been rewritten without an Episerver developers input, be warned you may need to rewrite it! Happy Coding 🤘