In this tutorial, you will learn about the different ways of integrating HTML into an Episerver website. When undertaking a new project we need to be efficient. A designer will create a design (usually in Photoshop) that represents all the pages that need to be built. It will be your job to take these designs and convert them into HTML. Converting designs into a normal static website is easy enough. Converting designs into a CMS-powered website is more tricky. In this tutorial, I will hope to answer the question, what is the best way to convert the design into Episerver CMS?

One option would be to get a backend developer to create all the blocks and pages and then get a frontend developer to create the HTML all within these .NET views. If you have attempted to build a website using this process, you will understand this is not ideal. Below lists some of the challenges the frontend developers will face in this workflow:

  • Need to understand the page and block structure of the website
  • Use Visual Studio and own a license
  • Compile a .NET website and understand build errors
  • Wait longer to load and debug

To avoid these types of issues, a very common approach is to first build the design within a static HTML website and then at some point, convert that work into an Episerver solution. Let us discuss the pros and cons of this approach.

Why Use A Static HTML Site in a .NET build?

Episerver can be built to work in a very flexible way, using pages and blocks. Allowing content editors to create flexible layouts, makes the CMS a lot more useful for content editors and the business, however, it makes Episerver HTML development more challenging for frontend developers. Why? Content editors can dynamically add components onto a page, they can resize blocks if display options are enabled, they can re-order blocks in different ways, and through feature flags they can inject classes into HTML.

In an Episerver CMS-powered website, you will have a lot less control over what the final rendered pages HTML will look like. Traditionally, in a CMS system, a developer would define a page template that had some pre-defined properties. Content editors could create and update pages using these pre-built properties. After publishing the page in the CMS, the end results would be a fairly predictable page layout being rendered. This made the HTML development easier as the frontend developer knew what the mark-up of the page would roughly look like. This made testing things easier as well.

Now content editors can drag blocks around inside of the CMS, predicting what the final HTML Episerver will produce can't be known as easily. Content editors might put blocks in combinations you never dreamed of, so, with this, in mind you will need to rewrite your HTML and CSS to work in a more dynamic and responsive way. This is why using a responsive grid framework like Bootstrap makes a lot of sense when building an Episerver website.

When using a responsive grid, like Bootstrap, you have different problems. If your HTML is missing a row class, or a grid has been set to be greater than 12, Bootstrap will usually float the element to the left. In most cases it will look OK, in others, the final page mark-up may not be in line with the designs. In short, when building a flexible block architecture inside of Episerver CMS, you will hit a lot of headaches as you won't be able to guarantee the end HTML Episerver will produce.

With all that in mind, it should start to be a bit more obvious why creating a static HTML version of the website before integrating the HTML into the CMS will make the designer's life easier. Writing HTML and CSS within pages and blocks is time-confusing and frustrating to test for frontend developers. When I have introduced the idea of building a static HTML website first to clients, in most instances the backend development team usually question its need.

A lot of developers who haven't come from a digital agency background struggle to understand the point of building a static HTML first. The most common feedback from the backend teams is that it makes their lives a little bit harder. Copying the HTML from the static site into the .NET powered Episerver website is deemed a 'waste of time', especially when designers 'could just work within Visual Studio'. From my experience failing to appreciate the differences between the different disciplines within web development has its own cost which is usually much higher.

Let us think about the differences between disciplines, there are different tools, operating systems and even the workflow of how code is written differs. The coding cycle of C# is a lot more painful compared to the wonderful world of hot reloading in HTML land. Almost every frontend designer that I have ever worked with has wanted to work directly within a text editor, like Sublime, or Atom. Backend developers are used to working with Visual Studio. Visual Studio is great although for writing backend code, although it is a little clunky to use compared to a good text editor. It also costs. Cost is the first major benefit from free a frontend developer from using Visual Studio. Buying an MSDN subscription for all the designers within a company is expensive. An MSD subscription is about £2000 a year, if you have 5 designers, then that's nearly £10,000 a year on software. Compare this cost to a free tex-editor and you will save yourself a lot of money.

To allow a developer to be as efficient as they can, they need to be able to use the tools they feel most comfortable with. I personally think it's a stupid idea to make people work with tools they don't want to use. If you let designers work within a separate static site, you have fewer constraints on tooling. If you force people to only work directly within the .NET website, everyone on the team will need to use a Windows PC, have IIS set up on their laptop and have a Visual Studio license. Allowing frontend developers to build the HTML within a static site will open up a lot more possibilities. Designers will be able to use a MAC or a Windows PC, dependant on their preference, rather than being forced to use Microsoft stuff.

Another issue for frontend developers working within Visual Studio is that they need to understand how a .NET project is structured. They may need to understand namespacing, they might even need to create new views, controllers and view models. This will mean the frontend designers will require training on .NET, otherwise, they will keep distracting a backend developer to help them. You now have two unproductive people in the team 😢

Designers will also have to understand the extra noise of the solution, understanding the folder structures, naming conventions as well as have a basic understanding of some of the key files like the web.config. These types of config files are vital for Episerver to run, however, they don’t really add any value to a designer so it makes their lives more time consuming when navigating around the project structure.

Whats The Downsides Of Using An HTML Site on An Episerver Build?

Using an HTML site does have some trade-offs. If you need to copy files from one solution into another, you obviously have a higher integration cost than just working directly in Episerver. Each time a tweak is made within the static HTML site, this change will also need to be copied into Episerver. In this copying process, it is very easy to miss things and then spend 10-30 minutes scratching your head wondering why the page looks pony 🐎. When you create everything within a static HTML site, you may also get some slight nuances on rendered output. On the static site, you won't get the extra div tags that Episerver automatically wraps around anything added into a content area.

The workaround for these issues is obvious. Don't start the HTML migration into Episerver until you have fully tested your static HTML site and all key project stakeholders have signed it off. It's much quicker and easier to make changes to the HTML site. Get sign off and make sure the static site works as it will be easier to change things before copying begins. Save yourself some headaches, don't try and run before you can walk. Most people will want to start integrating ASAP, however, from my experience, this usually results in more wasted effort.

Lastly, you have to have good developers who respect the workflow. Everyone on the team needs to understand design tweaks need to be done within the static site first. If people try and fix design tweaks within the Episerver solution, work will get lost and overridden. Everything needs to be done within the static site first and then copied across, even after go-live! To help mitigate this issue, I've previously used a CI tool like team city to build the assets of the static website into a Nuget package. In order to copy updates from the static site to the Episerver site, it's been a simple case of updating the internal NuGet package within the Episerver solution. This also greatly reduces the number of copying errors that can occur.

Building websites is complex and you definitely can't please all the people all the time. From experience, most backend developers will prefer designers to work within Visual Studio as it will make their lives easier. Most front-end developers, for obvious reasons, will want to use the tools they are most familiar with. When I work on any new Episerver project I will always recommend the HTML static site route as the benefits far outweigh the downsides. If you have the time, building a Nuget package or a deployment script that can automatically copy the CSS files into the Episerver solution makes life a lot easier. Happy Coding 🤘