Umbraco and server side headless integration

Umbraco is a great CMS that has been steadily been getting better over the last 2 years. It has a really easy user interface, is easily extendable and for the most part takes the heavy lifting out of creating CMS websites. One feature that initially drew me to Umbraco was its ability to abstract the front-end from the back-end, this seems to be one of its primary purposes with multiple template rendering options; ASP.net MVC Razor, XSLT etc.

All the solutions work well and make the effort of changing the user interface easy, if you have experience in the templating languages that are supported. Something like Razor is relatively easy to pick up but there are still too many options and historically the API has changed a lot making it difficult to know the right way to go.

The main issue with using a templating engine like Razor with Umbraco is that is does nothing to abstract the model of data actually used in the template from the HTML that it is wired into. After all, the Model supplied by Umbraco is all the possible data that could be used on the template (and that’s a lot!). This makes integration and changes to templates harder to manage or understand in the long term, it’s all mushed in together. This is the difference between a Model and a ViewModel.

You could create a headless CMS using web API controllers, but they have their disadvantages over using a purely server side solution. You’ll still have to deal with routers, controllers and a structure to make the site work. If you don’t feel like diving into setting up a React or Angular solution then this could be another option. It gives a much cleaner solution and removes the need for the backend developer to even see any HTML.

Serverside Headless CMS

Works by completely abstracting the definition of the ViewModel from the HTML it’s integrated into. This frees up the front-end developer to build the front-end into a completely separate solution, using their own data to test how the user interface reacts to different data. When they have completed a release all the user interface files (partials and page) are sent to the production solution. The work of the back-end developer is greatly reduced and simplified; mapping the Model into a ViewModel and rendering the template provided by the front-end solution.

We are using Handlebars as the template rendering engine to create the front-end solution. It’s simple enough that most developers can pick it up in a few hours but is extendable enough to cope with edge case scenarios. For the Umbraco solution we use the Handlebars.net solution to render the files that the front-end supplies. Most importantly this package closely mimics the behaviour of the original Javascript library. The output from both renderings obviously needs to be the same.

Handlebars Helpers

One of the reasons for us deciding to use Handlebars is for its extend-ability. That comes in the form of Handlebars helper, these are functions that allow you to change template output. Whatever helpers are used by the front-end solution should produce the same output on the production solution otherwise the site will look different when moved to production.

Demo application

The easiest way to see the workflow in action is to download our example solution from and run Umbraco from backend.src\BlockingExample. The login for the demo site is admin and admin1234. Boot up the app from either Visual Studio or Web Matrix and follow the Simple Example, without partial link (/example-page/). The other examples just expand on the initial concept and show off some features that are not highlighted here.

This is the same download as used in the Introduction to Blocking on the front-end article, take a look to see how the HTML is built for a front-end developer.

Application startup

When the Umbraco application initialises, it reads all the pages and partials supplied by the front-end, pre-compiles (for efficiency) and store them in a runtime cache. The RegisterTemplateOnStartup and TemplateService files handle this startup process.

The result is a dictionary collection in the runtime cache that contains the name of the template and a Func<object, string> for the compiled template. To render the template just select the template name and pass ViewModel data. It will return the rendered template as a string.

var output = templates[templateName](data);

Rendering the front-end template

There are several options for where to render these Handlebars templates. We have done this many ways and we find that initially, building the ViewModel in the template gives us the greatest flexibility but it is dirty. Integration sometimes needs to be fluid and being able to make a quick change without a server restart makes the development process much quicker, especially when building a site. We can also use the Umbraco admin area template editor to update a ViewModel giving greater flexibility to make a quick change. This is definitely the dirtiest solution and really makes a mockery of the MVC pipeline but it also the easiest to understand and quickest to implement, so it’s the one we’ve used here.

There’s an extension helper to make this even easier.

This takes the file name of the page block from the front-end solution and the ViewModel generated in the template. Additionally there’s a default parameter that toggles display of the json to build the page. So to render the template would be

This works especially well when used with the ModelBuilder (and NestedContent), writing the ViewModels becomes really easy, just wire up and it works. Even more so when you can convert the child nodes to model types.

The code becomes really easy to understand and more importantly if you define the ViewModels upfront front-end and back-end can work independently and safely.

It may be a step too far but the demo site also includes a template using Partials to create commonly used ViewModels (ExamplePageWithPartial example).

This demo app shows the full development workflow, if you run the front-end solution (learn how here) then you will be able to make a change to the HTML and SCSS and push it through to the production app. The further examples in this demo show how we handle more complicated pages.

If the above feels too dirty then the ViewModels can be written in code outside of the templates. Or even doing it properly and create a custom ViewEngine using controller hijacking to build the ViewModels. There is more than one way to do this, it all depends on your requirements and how far you want to take it. The most important outcome is that your data is not hard wired into the templates, this makes it easy for you and other people to understand and maintain. Just as importantly, easy for the front-end developer to maintain their side of the solution.

UPDATE March 2019: since we wrote this blog post we have been working hard on improving the way that Umbraco maps the Model into the ViewModel, in larger applications we always realised that using JSON wasn’t really maintainable. Recently, we have created a ViewModel builder that generates POCOS representations of the data schema created in the frontend solution. We have been using this internally for the past few months and have seen great results. With these newly created ViewModels the mapping process becomes much more self-documenting and we can also take advantage of AutoMapping.

We’re still doing tests and writing up our results but we’ll be releasing some code, tools and blog posts to help others work in the same way over the next few months.