Visual SPA Editor

What it does

The Visual SPA Editor connects the modern component-architecture of SPA, with the component concept of CMS page editors. You can build a SPA, and give it placeholder ``areas'', that can be managed from a CMS.

  • Frontend Developer: Builds SPA. Adapts SPA to make it content manageable.

  • Frontend or Magnolia Developer: Creates Magnolia bindings and dialogs. (Putting handles and knobs on the components for authors.)

  • Content authors and marketers: Choose which components to put in the areas, in what order, and edit their contents.

SPA block 1024x512

Overview

Authors use Page Editor:

  • Can build experiences based on predefined page and component templates.

  • Result is a hierarchy of pages and components stored in Magnolia.

Implementation:

  • Small javascript library for each JS framework (React, Angular, soon Vue)

  • JS library provides ``Area'' component. This is a placeholder for authors.

  • A Magnolia REST endpoint serves both layout and content for each page.

  • JS library uses this information to dynamically build app. It instantiates frontend components and passes the content in as props.

  • In the authoring experience, another Magnolia REST endpoint serves information about all the templates on the page. For example it provides which components are available in an area.

Capabilities:

  • Use any frontend component (React, Angular, Vue) without modification. They get all CMS content passed in as props.

  • Supports nested components.

  • Supports multiple pages, and `nested pages' (ie a page tree).

  • Authoring feature even works if the DOM changes dynamically while authoring.

Two key usage scenarios:

  • Existing SPA: Add content management to an Existing SPA

  • New DX/CMS project: team wants to use React templating.

Differences to Basic Headless

basic headless vs next level 1280

In Basic Headless, an author fills out a form, in a separate tool. Content is stored in a list in a database, and it is retrieved as a list via a REST API request. The typical frontend loops through the list and renders each item in a region of the view. So, authors can manage content items. YAY. But they cannot manage experiences.

With the SPA editor, an author chooses and places components on a visual page. For each component they fill out a form, in context. Content is stored in a tree in a database, we could call it a `leaf', and its retrieved as a tree via a REST API

The tree is important - the location of the leaf in the tree represents where the component was placed in the page. Each leaf also stores which type of component it is. In the frontend the code follows every branch of the content tree, and for each leaf it displays the type of component specified in the leaf.

The result: It’s a tool an author can use to manage content & to build out the full experience.

How it works in Production

The web experience is a SPA, served from any server.

It hits a Magnolia REST Delivery endpoint to get a JSON page payload which includes:

  • Content: The contents of all of the components on one page. (Typically a delivery endpoint)

  • Layout: The layout of components in the page (Actually, just the heirarchy of the content nodes.)

Mapping Information: which SPA component to instantiate for each Magnolia component, is in a file in the SPA.

The SPA instantiates 1) the specified components, with 2) that content, in 3) that heirarchy.

When the user navigates to a new Route (aka Page), the SPA hits the endpoint again and refreshes its content.

How it works in Editing Experience

An Author opens a page in the Magnolia Pages App. The template has renderType: spa.

Page Editor loads the SPA which is bundled in a Magnolia module.

It hits a Magnolia REST Delivery endpoint as above.

It hits the templateDefinition Magnolia REST endpoint for information about all the templates on the page. For example it provides which components are available in an area.

The JS library instantiates the components as above, but additionally adds hints/annotations for the Page Editor in the form of the HTML comments, for every area and component on the page. Then it calls the `mgnlRefresh' method to request the Edit Bars.

The Page Editor injects the green Edit Bars into the DOM, based on the annotations.

Author uses the Edit Bars.

Edits are persisted to Magnolia. Page Editor reloads the page in the iframe.

How to Make your SPA Editable

Check out the `Getting Started' Hello Magnolia - SPA tutorial to really get hands-on.

Start by browsing the Minimal Headless Spa Demos repository. There you can see a well organized, complete working example.

Step by step

Page

  1. Create a SPA component to represent your page. Use a `prop', like `title'.

  2. Load the content from the delivery endpoint for the the current route. Example

  3. Load the template information from the templateDefinition endpoint, based on the templateID of the route page.

  4. Create a component mapping configuration.

  5. Use the `Page' component from the Magnolia JS library to instantiate a frontend component. based on the templateId of the magnolia page, and the mapping.

  6. Deploy your SPA. Typically on its own server. (But you could optionally host your SPA in a Magnolia light module.. /magnolia/light-modules/react-minimal-lm/webresources build)

  7. Create a Page Template definition and point it to the SPA URL. Add a dialog with a `title' property.

  8. Run the page app. Edit the title.

Area

  1. Add areas to page template definition to enable author managed components

  2. Add Area components for the same areas to the frontend page component.

Components

  1. Create frontend components as usual.

  2. Create Magnolia components for each frontend component. (Just a definition and dialog, no template script needed!) Dialog properties will be available in your frontend compont as `props'.

  3. Add the component to your mapping configuration file.

  4. Repeat and prosper!

Feedback

Headless