A CMS for SPA Frameworks Like Angular and React - That Makes Developers and Marketers Happy

Part 2 of a 3 part series.

In the first part of this series we covered Single Page Application 101 and the troubled history of trying to get an SPA and CMS to work together nicely.

Now for the fun part -  how your teams can use all the wonderfulness of SPAs and headless development while retaining the wonderfulness of modern marketing tools.

What You First Need to Know About the Bloomreach Architecture

Our CMS has been designed to be content based, rather than page based. This means that each piece of content is stored independent of presentation.

In this set up, pages are basically different views of content, and the content isn’t attached to one particular page. Because content isn’t attached to one page, or one view, it means the same piece of content can be used on different pages, different touchpoints, and in different SPA frameworks.

This core separation of content, code, and presentation makes Bloomreach very API-friendly. Content and data can be shared cleanly between sites, devices, and 3rd party systems. It’s built for re-use.

Not only can Bloomreach dish out content in that API-friendly manner, but it can also dish out the logic behind that content in the same clean way. On the server side, the Bloomreach platform can use browsing behavior, 3rd party data, and links between content to determine the right “content kit” to deliver - and pump out this content and logic in that presentation-neutral, JSON format. This is the key to what makes Bloomreach so SPA-friendly.

Why We’ve Added SPA Support

Simply put, developers like SPAs and we think an Enterprise tool should encourage new, efficient ways of working. We figured the best way to give developers the SPA freedom they want is to ensure Marketing gets to keep all the editing features they are accustomed to - and to make it easy to do so.

The solution was designed to address 2 main factors:

1. Developers should have a built-in, API solution that is framework agnostic.  
    
2. Marketers should be able to edit the way they are used to (drag and drop, adding/deleting new pages, personalization rules) whether that content is displayed in an SPA, a traditional page, or both.

What We’ve Added SPA Support

The two key additions are the Page Model REST API and the Aggregated Page Model.

The Page Model API is a built-in JSON API with a generic representation of resources, meaning that you can integrate it with the framework of your choice. Bloomreach already thinks of page structure as a map of components (the content-based structure mentioned above), so the Page Model API simply makes this map easy to read and render for your SPA.

When your SPA calls for resources, the Page Model API sends it back an JSON/HTTP map of the component hierarchy, and directions on what content to fill those components with. The SPA renders the page based on the API agreement of how to read the map.

That map is the Aggregated Page Model, and it contains the page identifier, follow-up links, page representation (components and domain specific models), and content models.

Basically, it tells the SPA what components need to be there and what content to put in those components. How that content actually looks is up to your SPA.

This map breaks down your page representation into a lot of interlinking parts, each labeled with a metadata field. The SPA uses these metadata fields as a key on how to use each part. These modular (and sometimes nested) components are what gives marketers the ability to edit an SPA in the CMS, which we’ll look at next.   

If we return to the Paint-by-Numbers example from part 1, the Aggregate Page Model tells you what little boxes you have, which boxes are in other boxes, and what paint goes in which box.

The Page Model API then sends those instructions along with the right paint to the SPA you have sitting in your browser. The SPA then decides where those boxes go on the page, puts them there, and fills in the paint.

Our developers have written more detailed information on these features if you want to dive in.

Preview

To be able to edit in the what-you-see-is-what-you-get (wysiwyg) way that Marketers are used to, you first need to be able to see what can be edited. Of course, the crux of an SPA is that the rendering is done in the application on the front-end, so this means that your back-end CMS has to have, well, a front-end. Luckily, Bloomreach has always handled it’s preview in this sort of way.

So let’s talk pre-SPA real quick. To get a preview in the CMS - where you can see what content looks like before you publish it - we made a special preview site that sits in a server. It acts like any other site - a browser asks it for information, it runs to the database to check if it has the most updated version of that information, and it sends back the certified-fresh information - the key difference is that it is set up so that it can find all the unpublished content too.

For Marketers to be able to see that preview (we’re still talking pre-SPA, classic Bloomreach here), the Channel Manager in the CMS shows you a view of that preview site, seen as the blue box in the image above. In (very) simplified terms the preview in the CMS is acting as a browser to display content. Bottom line, Bloomreach can show what front-end render will look like within the back-end CMS platform.

With this set-up already long in place, being able to preview SPAs wasn’t too big of a jump. In fact, we’ve previously had customers build their own APIs to make Bloomreach’s preview work with SPAs. Now, we’ve just built a standard API into the product that lets the SPA render the preview and let’s marketers edit that preview in the drag and drop way they are used to.

This is the Preview API. It’s just like the Page Model API but it also adds meta-data via html comments that the SPA needs to insert before and after the DOM element (a language-neutral standard for accessing documents) for certain components. Basically, it flags where the component begins and ends.

The SPA and the CMS have an API contract (defined during integration) on what components can be edited in the CMS - the meta-data from the Preview API tells the SPA which of these components are present, the properties of each component, and a map containing all of the content referenced by the components present.

So that special preview site (already in place pre-SPA) now has an SPA on it and, with the Preview API, that SPA is powering what you see in your back-end CMS.

For a detailed explanation of how this meta-data works, and the wrapper classes it uses, have a look at Robbert Kauffman’s developer lab on integrating a React app with Bloomreach.

How the Preview Shows Your Edits (and makes them live)

When you edit using the CMS you aren’t really deciding how things “look” on the page, because the CMS just hands the SPA the raw content/component list (the Aggregate Page Structure) and the SPA is in charge of the look.

However, as we discussed above, the preview you see in your CMS is powered by the SPA, so you are instantaneously seeing how the SPA renders any changes you make. This makes it feel like your edits in the CMS are controlling the look, and for all practical purposes you are, but the nitty gritty of it is that you are running very quick experiments on how the SPA reads the Aggregate Page Structure and tweaking content based on results. 

The SPA generating your Preview has it’s little Preview API map. When you make a change by editing the preview the Preview API compiles a new map based on those changes. Remember, this Preview API is only making a map for you preview, so the map the public is getting hasn’t changed yet. 

The SPA takes the new map and renders the updated preview. When you see the render you like in the preview you know you have the right map (aka the right Aggregate Page Structure) - and you push publish. Now you’ve replaces the old map in the database with the new one, and when a public visitor asks for the map your servers will hand them the new one. 

For a much more detailed explanation of how this works, have a look at Lef Karamoulas’ video presentation on integrating a React App with the Bloomreach Channel Manager.

Marketers Keep the Features They Need

With this preview, and the meta-data the Preview API attaches to it, Marketers can edit and manage SPAs like they would any traditional website. I’m going to run through a few of the key features quickly, and if you would like a deeper explanation of how they work have a look at Ard Schrijvers’ video presentation on Bloomreach’s SPA++ support.

• Simple Editing 

The Aggregate Page Structure gives you a list of components and a content map that points each component to the right content. If you change the content, the map is updated to point the component to the right content. This mapping also prevents content from being duplicated in a browser, as multiple components can point to the same piece of content.  

• Drag and Drop 

Thanks to those meta-data tags from the Preview API, the list of components and content the CMS gives the SPA is broken into pieces with clear “begin” and “end” points in the map. If you drag a component to a new place in the preview, the CMS notices the order has changed and updates that order of that list, the SPA then renders the list in a new order. Again, how it decides to render that flipped list is up to the SPA itself, but the preview gives you the chance to experiment before going live. 

• Create a New “Page” 

In the case of SPAs you are creating a new view, or a new route, instead of an actual page but the best part is that a Marketer would be able to create these new views in the same way they are used to creating pages.

Create a new page in the Channel Manager (like normal), and you are given a fresh template in the Preview that you can add content and containers too. Behind the scenes this new template and the content you add is being serialized and added to the Aggregate Page Model, but as an editor you can create (and delete) like usual. 

Two other key aspects that Bloomreach’s SPA++ support enables are content personalization and hybrid setups, either between your SPA and traditional sites or even between 2 SPA frameworks. In part 3 we’ll dive into how both of these work thanks to Bloomreach’s content-based structure and server-side relevance work.