Single page applications (SPAs) can offer compelling experiences for website users. Developers want to be able to build sites using SPA frameworks and authors want to seamlessly edit content within AEM for a site built using such frameworks.
The SPA Editor offers a comprehensive solution for supporting SPAs within AEM. This page gives an overview of how SPA support is structured in AEM, how the SPA Editor works, and how the SPA framework and AEM keep in synch.
The Single-Page Application (SPA) Editor feature was introduced with AEM 6.4 and is currently a technology preview. The SPA Editor will be delivered separately to the AEM quickstart in an upcoming service pack for AEM 6.3 and 6.4.
- This feature is still in development and documentation is subject to change.
- The SPA Editor is the recommended solution for projects that require SPA framework based client-side rendering (e.g. React).
Sites built using common SPA frameworks such as React and Angular load their content via dynamic JSON and do not provide the HTML structure that is necessary for the AEM Page Editor to be able to place edit controls.
To enable the editing of SPAs within AEM, a mapping between the JSON output of the SPA and the content model in the AEM repository is needed to save changes to the content.
SPA support in AEM introduces a thin JS layer that interacts with the SPA JS code when loaded in the Page Editor with which events can be sent and the location for the edit controls can be activated to allow in-context editing. This feature builds upon the Content Services API Endpoint concept since the content from the SPA needs to be loaded via Content Services.
For further details about SPAs in AEM, see the following documents:
The page component for a SPA doesn't provide the HTML elements of its child components via the JSP or HTL file. This operation is delegated to the SPA framework. The representation of child components is fetched as a JSON data structure. The SPA components are then added to the page according to that structure. This behavior differentiates the page component's initial body composition from non-SPA counterparts.
The resolution and the management of the page model is delegated to a provided PageModel library. The SPA must use the Page Model library in order to be initialized and be authored by the Page Editor. The Page Model library provided indirectly to the AEM Page component via the cq-react-editable-components npm. The Page Model is an interpreter between AEM and the SPA and therefore always must be present. When the page is authored, an additional library cq.authoring.pagemodel.messaging must be added in order to enable the communication with the page editor.
If the SPA page component inherits from the page core component, there are two options for making the cq.authoring.pagemodel.messaging client library category available:
- If the template is editable, add it to the page policy.
- Or add the categories using the customfooterlibs.html.
The inclusion of the cq.authoring.pagemodel.messaging category should be limited to the context of the page editor.
When the cq.authoring.pagemodel.messaging category is added to the page, it will send a message to the Page Editor to establish the JSON communication data type. When the communication data type is set to JSON, the GET requests will communicate with the Sling Model end-points of a component. After an update occurs in the page editor, the JSON representation of the updated component is sent to the Page Model library. The Page Model library then informs the SPA of updates.
You can understand the architecture of the interaction between the SPA and AEM by thinking of the Page Editor as a mediator between the two.
- The communication between the page editor and the SPA is made using JSON instead of HTML.
- The page editor provides the latest version of the page model to the SPA via the iframe and messaging API.
- The page model manager notifies the editor it is ready for edition and passes the page model as a JSON structure.
- The editor doesn't alter or even access the DOM structure of the page being authored rather it provides the latest page model.
To enable the author to use the page editor to edit the content of an SPA, your SPA application must fulfill the requirements of the SPA Blueprint.