Chapter 1 covers the installation of the AEM SPA Editor JS SDK and the implementation of two React components that map to AEM Text and Image components. The JSON model that drives the integration between AEM and React is inspected.

Install AEM SPA Editor JS SDK

Persona: Front End Developer

What is the AEM SPA Editor JS SDK?

In short, the SPA Editor JS SDK is a collection of open source JavaScript libraries that provide a framework for allowing authors to edit the contents of a Single Page Application deployed in AEM. AEM delivers the content in the form of JSON and the SPA Editor JS SDK maps the JSON to React components. Please read SPA Editor Overview for a more comprehensive view into how the SPA Editor works.

@adobe/cq-spa-page-model-manager - provides the API to manage the model representation of the AEM Pages that are used to compose a SPA. This module is not tied to a specific SPA framework.

@adobe/cq-react-editable-components - provides generic React helpers and components to support AEM authoring. This module also wraps the cq-spa-page-model-manager and cq-spa-component-mapping to make these available to the React framework.

Next, install the AEM SPA Editor JS SDK as part of the react-app project using npm.

App.js continues to be the entry point of the application but it now extends the Page class from @adobe/cq-react-editable-components. In the render() function this.childComponents and this.childPages will include React components that are driven by the JSON model.

The EditorContext wrapper is responsible for facilitating the communication model between the AEM editor and the React application. This includes indicators (blue boxes) for which parts of the application are editable and automatically refreshes the React component when it is updated by an author in AEM. The EditorContext is only active in the AEM authoring environment, based on the value of Utils.isInEditor().

This is the first time we are using the MapTo function which serves to map an AEM component to a React component. In this case we are mapping the resource type wknd-events/components/structure/page from AEM to a React component WKNDPage.

Using the browser's developer tools inspect the HTML rendered by the React app. You should see some empty divs that are generated by the React App. One of the divs should include the WkndPage css class created in step 4.

Note viewing the Page source will not show you the same markup, as this markup is generated by the app

Text Component

Persona: Front End Developer

Next we will map the AEM Text component to a React component that will allow users to author rich text as part of the app.

Using the editor of your choice open react-app under aem-guides-wknd-events/react-app.

The MapTo functionality provided by @adobe/cq-react-editable-components maps the Text JSON to the React Text component based on the :type value. The MapTo also makes available the values of text and richText as React props to the Text component.

Next Steps

(Bonus) HierarchyPage Sling Model

Persona: Backend Developer

The AEM SPA JS SDK is designed to parse a JSON schema into a JavaScript Model. A Sling Model, HierarchyPage.java has been included in the starter project that will expose content within AEM as JSON that matches the expected schema. A key feature of the exported JSON by the HierarchyPageImpl is the ability to expose the content of multiple AEM pages in a single request. This allows the SPA to be initialized with most of the content of the app and can remove the need for subsequent requests as a user navigates the app.

In the editor of your choice open the <src>/aem-guides-wknd-events/core module.

Open core/src/main/java/com/adobe/aem/guides/wkndevents/core/models/HierarchyPage.java

ContainerExporter - Defines the JSON of a container component like a page, responsive grid, or parsys

HierarchyNodeExporter - Defines the JSON of a hierarchical node, like a root page and it's child pages

Open core/src/main/java/com/adobe/aem/guides/wkndevents/core/models/impl/HierarchyPageImpl.java

This is the implemenation of the HierarchyPage interface.

Poznámka:

Currently the HierarchyPageImpl is copied into the project. In the near future a default HieararchyPageImpl will be made available via Core Components. Developers will continue to have the option to extend but will no longer be responsible for maintaining the implementation. Make sure to check back for updates.

The HierarchyPageImpl is registered as Sling Model Exporter for the wknd-events/components/structure/pageresource type. If implementing a custom project you would update the RESOURCE_TYPE to point to your project's base page component.

The methods getRoodModel() and getRootPage() are used to find and return what is considered to be the "root" of the application. There are three properties stored on an App template's policy used to drive the collection of content:

PR_IS_ROOT = "isRoot" - Helps identify the rootPage of the application. The rootPage is used as the starter point to collect all the child pages of the app.

Navigate to /conf/wknd-events/settings/wcm/policies/wknd-events/components/structure/app/default. This is the policy for the wknd-events-app-template template. Notice the properties for isRoot, structureDepth, structurePatterns.

Výstraha:

At the time of writing this tutorial the SPA Editor does not support Editable Templates in the UI. Full support for Editable Templates is expected in the near future. Until then, updates to the templates will need to be done via CRXDE-Lite or by modifying the XML in the ui.content module.