Single-page applications

Since the 6.2 LTS release, Magnolia comes with modules and libraries that help you develop a Single-Page Application (SPA),

"a web application or web site that interacts with the user by dynamically rewriting the current page rather than loading entire new pages from a server." (Wikipedia).

In the SPA scenario, while editing and publishing of page content that is fed to an SPA still happens in a Magnolia author instance, retrieval and rendering of that content is delegated to a JavaScript-based front-end web framework running externally to Magnolia instances. Likewise, development of an SPA is completely independent of Magnolia: You don't need to have our libraries or support to write an SPA.

Requirements

To serve SPA pages, you need to: 

• Configure and run a JavaScript framework server. Currently, the following JavaScript web frameworks are supported: Angular and ReactJS.
• Connect the SPA to the REST endpoints of the Magnolia public instance which will serve page content and template information to the SPA. 
• Make sure that page, area and component templates developed in the front-end framework are correctly mapped to their Magnolia counterparts, and that besides the index.html file you correctly reference all CSS and JavaScript files assembled by the front-end framework.

How is a Magnolia page served as an SPA page?

An SPA expects two types of input: page content and template definitions .

• Page content, which is always edited in the Pages app, is requested by an external SPA through the Magnolia Delivery endpoint API v2.
• Page, area and component template definitions are requested by the SPA through a dedicated Magnolia template definition endpoint.

Once available to the external app, they are passed to a function in the app app that renders the final page tree.

Rendering an SPA page

The rendering of an SPA page is done through the JavaScript libraries included in the external React or Angular framework. The libraries assemble a component tree from the REST-delivered content and templates.

• The page node represents the root content for a given application state, for example a page title or page properties.

  Note: In front-end terms, a page is also a component, just a top-level one.

• Each JCR node then represents a page, area or component.

The template id, typically stored in the  mgnl:template  property, is used as a key to get the correct JavaScript component.

In order to create components based on their template id, component mappings must be defined. The mappings contain entries whose key is the template id string, and whose value is a direct JavaScript reference to the component type. The mappings are stored in the front-end project, close to template implementations.

Editing content of an SPA page

Since content editing in an external front-end app is a complex and challenging task, the React/Angular apps currently don't provide remote content-editing capabilities through REST. All content editing is done in the Pages app of the Magnolia author instance. The Magnolia-provided SPA renderer libraries ensure that a SPA project can be edited in the Pages app. The SPA renderer produces template annotations, which the Pages app transforms into the green toolbars – editable page elements.

On the Magnolia side, an SPA has a very simple template definition that just references the index.html file generated by the external React or Angular app.

See also

• Single-page application (Wikipedia).
• angular.io - a TypeScript-based open-source web application framework.
• reactjs.org - a JavaScript library for building user interfaces.