Configuring SPAs for Editing in Magnolia
Oct 12, 2021
--
SPA editor 1200x628

Configuring SPAs for Editing in Magnolia

If you want to learn about Magnolia’s take on headless content management but don't know where to start, you've come to the right place. As part of our “Headless Magnolia” series, we’ll break down relevant features that allow you to use Magnolia as a headless CMS.

In this article, we’ll discuss how to configure Magnolia to enable content authors to edit Singe Page Applications (SPAs) in Magnolia’s Pages app.

Configuring SPAs for Editing in Magnolia

Magnolia Light Development is a modern approach that simplifies and speeds up front-end development using low-code configuration. The definitions for page and component templates and dialogs live in the file system as YAML files.

For you as a developer, this means that you have all your code and configuration in the same place, making it easier to understand, manage, merge, and share templates in source control.

Page definition

In Magnolia, a page is the canvas that is used to lay out a collection of components that contain content.

Pages are based on page templates. The definition of a page template contains the following properties:

  • title: title of the template as shown in the Pages app

  • dialog: optional dialog to manage page properties

  • templateScript: reference to the SPA’s index.html file

  • renderType and class: configuration to use the Pages app in headless mode

  • areas: definition of page areas

Java
  title: SPA Page
dialog: spa-light-module:pages/default
templateScript: /spa-light-module/webresources/index.html
renderType: spa
class: info.magnolia.rendering.spa.renderer.SpaRenderableDefinition
areas:
 (...)

If you are familiar with Magnolia’s FreeMarker templating, you can spot a few differences in the configuration, especially the following: while FreeMarker templates have a dedicated templateScript file each, the definition of a SPA template points to the same index.html file as different page templates are handled by the SPA.

Component definition

In Magnolia, a component is the smallest block of content that content authors can edit.

Components are based on component templates. The definition of a component contains the following properties:

  • title: title of the template as shown in the Pages app

  • dialog: optional dialog to manage page properties

Java
  title: Component
dialog: spa-light-module:components/component

Again, if you are familiar with Magnolia’s FreeMarker templating, you might notice that there is no templateScript nor renderType because the different component templates are handled by the SPA.

The Visual SPA Editor is here

Benefits of headless: Companies improve the performance and maintainability of their DX system by splitting it into smaller services.

Dialog definition

A dialog is a pop-up in Magnolia’s Pages app. It allows content authors to edit content via a form. A dialog definition contains the following properties:

Java
  label: Title
form:
 properties:
   text:
     label: Text
     $type: textField

Dialog definitions are independent from template rendering. So, the dialog definition used with FreeMarker rendering and headless mode are identical.

Front-end helpers for SPAs

Magnolia’s front-end helpers are a collection of JavaScript libraries that enable you to easily integrate SPA templates in the Magnolia Pages app. The libraries inject annotations as HTML comments around components. Magnolia’s editor recognizes these annotations and transforms them into controls for content authors, allowing them to edit the components’ content in our Visual SPA Editor.

We provide the helper libraries for three popular JavaScript frameworks and you can add them to your project by installing the following npm packages as dependencies:

If you are using another JavaScript framework, you can create your own helper library based on the Magnolia Template Annotations library.

Learn more about Magnolia’s headless features

Headless Magnolia series:

About the author

Bartosz Staryga

Front-End Solution Architect, Magnolia

Bartosz is an expert in headless content management and front-end development at Magnolia. He designs and develops new Magnolia features and supports customers with their headless implementations from content types to APIs to integrations. Bartosz enjoys building new things and seeing them in action. He is also a trainer for Magnolia’s Headless training.