Peter Centgraf

Jun 30, 2021

Content: Lessons Learned

The newly-introduced Bloomreach Content product is a cloud native service based on the lessons learned from 20 years of development of the Bloomreach Experience Manager (brXM) private cloud and hosted Platform-as-a-Service Content Management System. We’ve brought deep knowledge of content management into the design of our new product and we’d like to explore some related topics in this new blog series for a cloud native developer audience.

Devs and the Business Meet at the Page: Headless Page Management

Bloomreach Content is built to provide tools for both developers and for site editors from across the full business, especially marketers and merchandisers working on a commerce site.

We have learned there’s a sweet spot for collaboration at the page level. Developers can build and test their components, gaining the control and consistency they need to test and release new features rapidly. Site editors gain the flexibility to build a variety of unique experiences by combining content-rich components in new ways, which they can test with users and iterate on to achieve business goals.

Other content management tools are optimized for either marketing users or developers, and the unfavored group misses key capabilities as a result, and business results suffer.

We’ve learned that we can get the best of both worlds by giving each group control over the aspects that matter most for their goals.

In this post, we’ll dig into the issue of page layout specifically, and show how taking on the full scope of an entire page in a headless architecture can provide a balance between developer and business concerns.

Developer and Site Editor Needs

From the developer perspective, a CMS is a tool to automate repetitive tasks - e.g. publishing web pages with a well-defined content structure. Ideally, a CMS should provide productive developer tools for building a fast, feature-rich site. This includes the ability to rapidly iterate through a code-test cycle and then lock in the fully-tested state for release to the live site. The key to automation is predictability, and developers want to control the details that might cause problems for their code.

From the business perspective, a CMS is a tool that allows them to publish campaigns, landing pages, blog posts, branded product detail pages and more - without having to call on developers for every change. Ideally, a CMS should implement a great site editing UX, with a ‘drag and drop’, What-You-See is What-You-Get (WYSIWYG) publishing environment. It should help editors to stay within the guide-rails of their company branding while giving them the flexibility to re-arrange content at will. It should be a productive tool for communication with site visitors, including the ability to test public reaction and update the customer experience based on that feedback.

A CMS is, in fact, a tool that allows for the elegant tradeoff of the concerns of the developer and the business. To look at either in isolation is a flawed approach. The choices embedded into the design of the platform determine how it maintains this balance of concerns.

Hierarchical MVC

One of the core choices in the design of a CMS is how much of the site structure and page layout will be within the scope of the tool, and how much must be controlled from outside by custom coding. To see why, we’ll start with a reminder about a well-known software design pattern.

Hierarchical MVC is a design pattern which can be traced as far back as 1987 (in the form of Presentation - Abstraction - Control). It provides a way to break down a user interface, such as a web page, into code to handle different aspects of the system. This is implemented in Bloomreach Content like this:



Components are small pieces of the full page, composed of a Model, View, and Controller

Model (Content)

The Model in HMVC is the raw data for a component. In the case of Bloomreach Content, this takes the form of documents. Documents can contain an arbitrary number of properties as defined within a document type, including meta-data, short text descriptions, longer rich text, numerical or date properties, pointers to images or other documents, etc.

View (Presentation)

The View is used to render the Model (content) within a component into a form that’s visually interesting for a site visitor. Views define the presentation of the Component, and this could take the form of raw HTML, a React Component, a mobile app component, or something more exotic.

Controller (Logic)

The controller provides logic to combine content and view and introduce any other behaviors that are necessary to drive the component. In the case of Bloomreach Content, the controller fetches content from the content repository, either with a direct reference or via some form of query, sorts and paginates it as needed, aggregates it with content from other parts of the page, and finally delivers that content to the view for presentation.


Containers are holders for one or more Components. Simply add the ability for a Container to hold other Containers, and you have the building blocks for a Hierarchical tree structure. In Bloomreach Content that tree represents the full layout for a page. For example, the top level structure might include containers for header, footer, and the main body of the page. The body can then be divided into containers for the left, right, and center sections of the page. With HMVC, page layout can be data, not code.

Hierarchical MVC in a Headless World

Separation of Model and View for reuse and flexibility

One of the key insights of the headless architecture is to provide a clean separation between the model and view, sometimes referred to as the content and presentation. Separation of content and presentation has been a key design principle for brXM from the introduction of the “channel manager” years ago. This design has served us well in the transition to a headless architecture.

One of the main benefits of this approach is to support content reuse across different channels, such as a responsive website, a mobile app, or an in-store kiosk. However, an equally important and often overlooked benefit is to provide flexibility to the site editor to compose content in different ways, to explore new ways of communicating with site visitors even within a single page. Separating content from presentation allows a site editor to choose when an image will have the most impact on its own and when to use it together with others in a carousel. It can also allow more responsive designs that match the context, for example by providing supporting components only on larger screens, while restricting the page to show only the main body content on smaller screens.

This separation also benefits developers, allowing them to incrementally improve a page by updating components separately from the content that they use, or by introducing new ways of displaying the same content. It can also facilitate large-scale redesigns of a site, since shared aspects of presentation such as visual design or header and footer elements are kept separate from the main body content for a page. This makes it easier to reuse these shared elements consistently and then update them separately from page-specific content.

The View is now decoupled

We can think of MVC in the headless CMS world like this:

The View has been decoupled from the backend Model and Controller. The primary change is that the View portion of a component is now residing within the frontend framework, written in a language like TypeScript or Swift. Note that the basic logic of HMVC has not changed at all!

In order to make this work in a seamless fashion and support the needs of both the developer (who is now a React, Vue or other framework coder) - and the business (who want to iterate at an ever faster rate), a comprehensive development workflow and integration is required. Frontend frameworks like Angular or Vue already have an MVC concept built in, so ideally the content from the backend system should fit naturally into that familiar framework for the frontend developer. Similarly, there should be a natural way to integrate the page layout and routing concepts into the frontend framework, to enable dynamic behavior in the frontend code based on the data managed in the backend.

Decoupling the frontend means crossing a network

Since a decoupled frontend is typically running on a different system than the backend, the frontend and backend are now separated across a network. This makes it even more important that the backend has the ability to manage the full structure of the page. The backend needs to know what content is needed for a page in order to deliver it to the frontend efficiently, rather than having the frontend execute multiple inefficient round-trip requests for individual content items.

Content and presentation have different needs

Many sites built with our headless CMS competitors try to resolve the problem of efficient content delivery by building a separate level into the content model to represent page structure. We think this approach is too limited. Reusable Content is fundamentally different in nature from page presentation, and the two types of data require different approaches. Content needs a stable data structure, well known to developers in advance, so that components can be built with clear expectations. Page layout should be flexible and interactively editable, to support a more creative design process open to inspiration and user feedback. 

Trying to manage presentation as content constrains marketers and designers too much, while trying to open up content structure to be more flexible would result in buggy components, difficult for developers to build and test. Content structure should match code structure, but presentation should be treated as flexible data to be interpreted dynamically.

Page layout is a key editor concern

It’s important to realize that Bloomreach considers the layout or composition of a page to be part of the presentation, not the content, and that presentation concerns should be under the control of the site editor. This subtle insight leads to a key difference between Bloomreach Content and many other headless content services. When you decouple content and presentation, that shouldn’t mean you give up on providing tools to manage the presentation part.

Components bridge the gap between developer and site editor

A component-based HMVC architecture provides a bridge between the needs of the developer and the site editor. Developers can focus on a stable content structure for each specific component, including whatever level of flexibility makes sense for the specific use case. Site editors gain the freedom to compose an endless variety of pages by combining components in unique ways, without needing developer support for each change. Supporting both brings balance to the Force, and peace rules over the land.

The Bloomreach Solution

So far we have talked about HMVC as a pattern and about how it works in a headless architecture. Now let’s take a look at how Bloomreach Content supports this approach with specific features.

Site Management API

The Site Management API provides tools for developers to define the basic building blocks for a site, including all aspects of the HMVC design pattern. It implements these features:

►Allows developers to define reusable components and page layouts.

►The defined set of components, customized to each site, becomes available for a site editor to drag and drop onto a specific page in the Experience Manager UI.

►Components include parameters for the site editor to fine-tune (for example, text colour or alignment for a title), including selecting from sets of options defined by the developer or defined by other site editors.

►Components use built-in content lookup and query functionality.

►Supports developer-only parameters to provide hints to the frontend code, allowing developers to structure their code separately from how components are presented to editors in the catalog.

►Supports other key aspects of the site, such as menus and routes to define site structure.

►Developers can also define default components to be included for all pages with a certain layout.

Experience Manager

The experience manager is the business tooling for site editors to use. 

►Editors can create new pages by selecting from predefined layouts.

►Editors can populate pages with components by dragging and dropping them from a component catalog.

►Editors can populate components with content by selecting it within the component as well as adjusting component configuration, directly in the UI.

►The UI provides rich inline editing support, allowing editors to create content and adjust presentation options by directly manipulating the live site in preview mode.

►Review and publishing options are also available here, without having to switch between contexts.

Page Delivery API

The page delivery APi is the primary integration point between the backend and the frontend.

►Provides developers the hierarchical page layout tree for a specific page.

►Since components are aware of their content, the platform composes a single API response with all data required for a whole page, in one fast request-response cycle.

►The Page Delivery API has been optimised with caching at multiple levels of the product and hosting architecture for extremely low latency even under high traffic load.


As the page layout and related content can be a complex payload, Bloomreach provides the SPA SDKs to support the frontend developer in using the data to render the page:

 ►SDK flavors are available for React, Vue, and Angular, as well as plain JavaScript or TypeScript.

 ►The SDKs include features to integrate more naturally with each framework, including support for next.js and nuxt.js for server-side rendering and isomorphic progressive web apps.

 ►The SDKs help with parsing the Page Delivery API into a TypeScript data model that is easier for a frontend developer to interact with.

 ►They help with mapping components from the page layout to frontend component implementations, and with feeding those components data to render.

 ►The SDKs also provide support for integration with the Experience Manager, such as providing shortcuts to enable real-time content editing in preview mode.

 ►The SDKs help with basic configuration tasks, like specifying the Bloomreach Content backend URL for Page Delivery API requests.

The Result

Treating the page structure and components as backend data enables an effective division of responsibilities between developers and site editors and as result, a decoupled workflow is possible. Developers get predictable data and great tools to build sites quickly, while site editors get amazing levels of flexibility to communicate in the best possible way with site visitors.

It’s a win all round.

Next time: Start with work and workflow at the page level, scale up with projects

Publishing content at the page level provides an intuitive UX. This is certainly better than publishing individual blocks of content independently, and it gives a satisfying immediate gratification for quick edits for specific pages. This works well for simple scenarios and as a result, Bloomreach Content has excellent page management tools for requesting review before publication, immediately publishing, or scheduling publication for a future date and time.

However, as site editing work scales to include multiple languages, brands, campaigns, and delivery endpoints, working at the page level is not enough. At a larger scale, it makes more sense to work with groups of pages as a single project to be reviewed and published together. Projects also provide benefits for developer workflow, including a natural flow for safely working with production data, gathering feedback, and testing. Stay tuned for a future post to dig into the Bloomreach Content project features in more detail.


Get Started Tutorial

►Site Management API docs

►Page Delivery API docs