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.
In order to successfully implement an integration of an SPA with brXM, a front-end developer needs to understand the involved concepts:
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:
- 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.
- 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.
- 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.
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.
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.
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