Hybrid Headless
Hybrid headless is a fancy name for a simple concept: use a full CMS which also serves its content directly via REST API, and manages clean, presentation-independent content. In this article, I’ll share four key hybrid headless techniques. All of these techniques revolve around the interplay of the delivery of content via REST of a headless CMS, plus the full-featured UX of a full CMS.
The headless CMS approach is great for so many reasons. Decoupling content from presentation ftw! Innovate with mobile apps and the new crop of front-end frameworks! Get started instantly! But with headless, there are some limitations that could bog your project down a little down the road.
These are the two key issues for me:
- Marketers and content creators (users who aren’t developers) cannot do as much.
- A headless CMS simply doesn’t cover many of the common content management requirements.
But this isn’t a “headless CMS are bad” article. I just want to set the stage for hybrid headless, in order to highlight some of the benefits of this approach.
You’ll have to balance the pros and cons for your project. Maybe these limitations are not relevant to your project, or are outweighed by the benefits of going totally headless.
Let’s take a look.
The UX of a full CMS
What’s so great about this UX? It empowers non-developers to perform key website tasks themselves. Of course all CMS are different, but there are two tools that are shared by most full CMS in some form:
The page tree (aka site map or content tree)
You can see and manipulate the structure of your entire project, typically represented as a hierarchy with the homepage at the top.
The page editor (aka page builder, WYSIWYG editor, post editor)
You can build and edit a page — choose a template for the page, modify its layout, drag-and-drop components, and populate it with content stored in your CMS. While it’s still called a “page editor”, a better term in this day and age is “experience editor” — it’s where you can really build an experience, not just enter content data in a form.
The four key hybrid headless techniques
Full CMS and REST API
Create clean, presentation-independent content. Serve the content through a website managed via the page tree and page editor, and serve it through REST endpoints.
Driven by the popularity of mobile apps, front-end js frameworks and SOA, many companies already use this fundamental technique. Marketers and content creators are self-sufficient and have full freedom to create and manage the website. Meanwhile, with the REST API, developers can create mobile and front-end apps in their programming languages and frameworks of choice — or pipe the content through existing delivery pipelines or third-party systems.
Page fragments as JSON
Marketers use the page editor to curate a fragment of a page with content and specific templates. Developers pull just the pure content of that fragment, as JSON, and render it in their app.
The benefit of this approach is that marketers can arrange not just their website, but also experiences that are used in apps and other systems. And they can do it in familiar tools, potentially including the ability to use the personalizaton and targeting features of the CMS.
Since developers pull content directly as JSON, they can use it however they want in a headless fashion. Developers have control over the actual display of the content, so it might look different than in the page editor.
At Magnolia, we have a banking client who uses this approach to enable their marketing team to update campaigns that are displayed in the consumer banking application. That banking application is delivered from a different server and vendor. This gives the marketing team the power to push new campaigns whenever they need to, independent of the lifecycle of the banking app itself.
Page fragments as HTML
As above, marketers use the page editor to curate a fragment of a page with content and specific templates. The developer configures another system or app to pull that fragment, rendered by the CMS as HTML. This is similar to the previous technique, but delivers rendered HTML instead of JSON.
“Wait, wait, what about a REST API? What about presentation-independent content?” you say. You caught me! It’s relevant in this list because it’s still about another app or delivery system grabbing some content from the CMS.
As before, the marketer creates experiences that are used in apps and other systems, with familiar tools. In this technique, since rendered HTML is delivered, the marketer also has a WYSIWYG authoring experience with live preview of the content.
At Magnolia, we have a number of customers who have chosen this approach for their web properties — such as e-commerce retailers whose marketing team wants to hand-craft the marketing content for the various departments of their shop with the page editor. The e-commerce system pulls these HTML fragments from the CMS to spice up the important, but dry, product data stored in the e-commerce system.
Build front-end apps
Developers design their front-end apps with a modern component-based architecture. Marketers use the page editor to manage the content of, configure, and assemble front-end javascript apps (aka SPA).
The first three techniques can all be used to manage the content of front-end apps (among other things). This one goes further.
With this approach, marketers can actually build a front-end app — in the same way that they are used to building a web page today.
This is huge since there is such momentum with frameworks like React, Angular and Vue. We have a lot of customers who love these frameworks, but are struggling with how to give their non-technical staff a way to manage them — so that the devs are not always burdened making tweaks and doing new releases whenever there is a change required.
In this technique, the “page editor” becomes an app editor. Marketing teams can build the apps that they need in a WYSIWYG environment and work with a live preview of the end-user’s experience.
The javascript frameworks all support this technique — but developers must take some care to create such dynamic apps that can be changed on-the-fly. The key difference is that instead of the app “hard-coding” exactly which components are nested within a parent component, it rather specifies a list of the components it could contain. When the app initializes, it loads a JSON configuration file that defines which components should actually be instantiated at each location.
There are aleady some nice libraries out there that make this easier, such as React Habitat from Deloitte.
At Magnolia, we are working on a generic solution which we plan to open source soon.
Hybrid headless in practice
It’s probably helpful to get concrete and see how those techniques can be applied in practice. As a product manager at Magnolia, I can draw from my knowledge of that CMS. (And maybe pique your curiosity about it too. :) The four techniques in practice:
Full CMS and REST API
Content apps provide a form-based editor for structured (presentation-independent) content. Content apps are equivalent to the editors in pure headless CMS.
Stories app provides a rich “medium-esque” editor for long-form content, giving the author freedom to create a full story instead of just fill in a form. Content is stored in clean blocks for retrieval as JSON via REST.
Content can be easily retrieved as JSON. Developers can quickly configure endpoints in a few lines of YAML. Access can be controlled through a full-featured role-based security system.
Page fragments as JSON
There are two ways to get the content of a page fragment via JSON.
- The REST API can return a fragment from within a page, a complete page, or a collection of pages.
- Render variations: Any template can provide multiple rendering variations, one of those can return JSON. A developer must code the JSON response using standard templating practices. The jsonfn library can be used to return the full content in one line of code. This approach can be used if the format of the REST API response is not the exact one you require.
Page fragments as HTML
In Magnolia, a feature called “Direct Component Rendering” gives easy access to any fragment of a page simply by including the “address” of the fragment in the url.
For example, to access a fragment on this page: http://demopublic.magnolia-cms.com/about.html
You can simply add “/main/00” to grab the first element of the “main” area. Try: https://demopublic.magnolia-cms.com/about/main/00.html
Build front-end apps
The Magnolia page editor uses simple HTML comments on the page to configure and indicate where the WYSIWYG editing widgets should be displayed. These invisible comment blocks provide information such as which areas of the page are editable, and which components can be inserted in that area.
With a little javascript code, these HTML comments can just as easily be inserted in the HTML generated by front-end javascript frameworks. This makes it easy to make front-end apps editable in Magnolia. I assume a similar mechanism is used in other CMS page editors, and so that the general approach will be do-able in other CMS as well.
Conclusion
Over the past 15 years, the pendulum has swung back and forth in favor of strict separation between content and presentation. At one extreme: only entering content in database-like forms is allowed, putting a wall separating authors from their readers. At the other: all content entry in-place in a WYSIWIG editor with the attendent risks of breaking the design.
But now I see a nice opportunity with the hybrid headless approach to become more subtle, less extreme, and take the aspects from both which really help people get their jobs done.
