SPA Integration - Bloomreach Experience - Open Source CMS
06-12-2019

SPA Integration

Introduction

Bloomreach provides tooling (Javascript SDKs) for integrating SPAs and other Javascript front-end applications with the brXM delivery tier and CMS capabilities.

As a front-end developer, you can integrate with brXM such that your SPA can consume content and configuration stored in and managed through brXM, from brXM's Page Model API. You can also integrate your SPA with the page editing capabilities of brXM's Experience manager, such that a brXM user ("webmaster") can control the content and structure of the page(s) driven by the SPA without a need for a front-end developer to deploy a new version of the SPA.

Conceptual Integration

In order to successfully implement an integration of an SPA with brXM, a front-end developer needs to understand the involved concepts:

Page Structure

In brXM, a page is represented by the mapping of the page's URL to a hierarchy / tree of components. Each component covers a part of a page. Components can be nested and may have multiple children.

There are 3 types of components:

  1. Hard-coded components: these components are read-only to the Experience manager, they cannot be edited dynamically and are controlled by a brXM developer. The order of the children of hard-coded components doesn't matter; the rendering order is up to the SPA.
  2. Container components: these components contain a list of editable container items (child components). The order of the children of a container matters, and it can be edited in the Experience manager. Containers have a type attribute, which helps wrapping the children of the container appropriately.
  3. Containter item components: these are the children of a Container component. In the Experience manager, container items can be added, edited, moved and deleted. Container items can be edited by changing the values of a set of component parameters. Apart from "primitive" values such as strings, numbers and dates, a component parameter can refer to a document or a menu, both of which can be edited in the Experience manager. At present, container items are limited to be leaves in the component hierarchy.

Apart from above components, the structural representation of a page can also contain menus (editable through the Experience manager) and documents (editable in the Experience manager or brXM's Content application).

Each container item has a type attribute which must be recognized/interpreted by the SPA, such that the SPA can render the container item based on the provided parameters.

For example, imagine a container item of type Banner. The SPA would then know that a Banner container item has an image, a title and a link target. It would then render a piece of DOM which uses these parameters to produce a visible representation of the Banner. Alternatively, a Latest News container item type would provide the SPA with a list of news documents, and the SPA would render the title and summary of each of these news documents.

The page structure, along with the referenced menus and documents, is stored inside brXM, managed through the Experience manager or Content application, and exposed to the SPA through the Page Model API.

Editing Integration

The editing integration is only relevant when the channel / SPA is displayed in preview mode in the Experience manager. When a brXM user navigates to the Experience manager, back-end state is set up such that the Page Model request retrieves a preview version of the page model, specific to the current user and the selected parameters (selected project, view as persona or Alter Ego).

The editing integration between the SPA and the Experience manager requires the SPA to be served to the browser (an iframe inside the Experience manager) over the same host as the Experience manager itself, the CMS host. Typically, the SPA is not hosted on the CMS host, but on some other SPA host. Therefore, requests to the external SPA host need to be reverse-proxied through the CMS host. A brXM developer typically configures the URL Rewriter plugin for this purpose.

Since the preview SPA inside the Experience manager iframe is served from the same host as the Experience manager, the Experience manager can access the SPA window in order to set up the editing integration. The Experience manager parses the SPA DOM to detect page structure elements and to be able to draw the corresponding overlay boxes, edit-menu and manage-content buttons, and it injects a Javascript library used for the drag-n-drop functionality of container items. Page structure elements are detected based on the presence of Comment elements in the SPA DOM, which the SPA must insert when rendering the page in preview mode.

On top of this access to the SPA DOM, some communication is also required between the SPA and the Experience manager in order to achieve editing integration: When the SPA has made a change to the DOM which requires the Experience manager to (re-)inspect the DOM for page structure elements, it sends a sync message to the Experience manager. If the brXM user changes the parameters of a container item, the Experience manager sends a renderComponent message to the SPA, asking it to re-render a certain component, given a changed set of parameters. At present, any other editing action in the Experience manager triggers a full reload of the iframe, which will reboot the SPA and retrieve a fresh copy of the page model.

SPA Integration SDKs

Rather than requiring front-end developers to directly interact with the Page Model API and the Experience manager, Bloomreach provides a generic SPA Integration SDK, which exposes a Javascript API. This SDK is framework-agnostic, or "plain vanilla Javascript". Based on the SPA Integration SDK, Bloomreach also provides a React SPA Integration SDK which provides access to the SPA Integration SDK's logic in a way easy to consume for SPAs built using React.js. The React SPA Integration SDK also serves as a show-case on how you can use the SPA Integration SDK from other rendering frameworks such as Angular or Vue.js. These SPA Integration SDKs avoid that front-end developers have to understand and deal with all details required for the integration with brXM, and Bloomreach strongly recommends front-end developers to use the SDKs rather than implementing a raw integration themselves.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?