Map SPA components to AEM components map-components

Before jumping into the SPA code, it is important to understand the JSON model that AEM provides. Navigate to the Core Component Library and view the page for the Text component. The Core Component Library provides examples of all the AEM Core Components.

Select the JSON tab for one of the examples:

You should see three properties: text, richText, and :type.

:type is a reserved property that lists the sling:resourceType (or path) of the AEM Component. The value of :type is what is used to map the AEM component to the SPA component.

text and richText are additional properties that are exposed to the SPA component.

View the JSON output at http://localhost:4502/content/wknd-spa-react/us/en.model.json. You should be able to find an entry similar to:

"text": {
    "id": "text-a647cec03a",
    "text": "<p>Hello World! Updated content!</p>\r\n",
    "richText": true,
    ":type": "wknd-spa-react/components/text",
    "dataLayer": {}
   }

In the IDE of your choice open up the AEM Project for the SPA. Expand the ui.frontend module and open the file Text.js under ui.frontend/src/components/Text/Text.js.

The first area we will inspect is the class Text at ~line 40:

class Text extends Component {

    get richTextContent() {
        return (<div
                id={extractModelId(this.props.cqPath)}
                data-rte-editelement
                dangerouslySetInnerHTML={{__html: DOMPurify.sanitize(this.props.text)}} />
                );
    }

    get textContent() {
        return <div>{this.props.text}</div>;
    }

    render() {
        return this.props.richText ? this.richTextContent : this.textContent;
    }
}

Text is a standard React component. The component uses this.props.richText to determine whether the content to render is going to be rich text or plain text. The actual “content” used comes from this.props.text.

To avoid a potential XSS attack, the rich text is escaped via DOMPurify before using dangerouslySetInnerHTML to render the content. Recall the richText and text properties from the JSON model earlier in the exercise.

Next, open ui.frontend/src/components/import-components.js take a look at the TextEditConfig at ~line 86:

const TextEditConfig = {
emptyLabel: 'Text',

    isEmpty: function(props) {
        return !props || !props.text || props.text.trim().length < 1;
    }
};

The above code is responsible for determining when to render the placeholder in the AEM author environment. If the isEmpty method returns true then the placeholder is rendered.

Finally take a look at the MapTo call at ~line 94:

export default MapTo('wknd-spa-react/components/text')(LazyTextComponent, TextEditConfig);

MapTo is provided by the AEM SPA Editor JS SDK (@adobe/aem-react-editable-components). The path wknd-spa-react/components/text represents the sling:resourceType of the AEM component. This path gets matched with the :type exposed by the JSON model observed earlier. MapTo takes care of parsing the JSON model response and passing the correct values as props to the SPA component.

You can find the AEM Text component definition at ui.apps/src/main/content/jcr_root/apps/wknd-spa-react/components/text.

In the project code open the file import-components.js at ui.frontend/src/components.
This file imports all of the SPA components that map to AEM components. Given the dynamic nature of the SPA Editor implementation, we must explicitly reference any SPA components that are tied to AEM author-able components. This allows an AEM author to choose to use a component wherever they want in the application.

The following import statements include SPA components written in the project:

import './Page/Page';
import './Text/Text';
import './Container/Container';
import './ExperienceFragment/ExperienceFragment';

There are several other imports from @adobe/aem-core-components-react-spa and @adobe/aem-core-components-react-base. These are importing the React Core components and making them available in the current project. These are then mapped to project specific AEM components using the MapTo, just like with the Text component example earlier.

From the AEM Start screen navigate to Tools > Templates > WKND SPA React.

Select and open the SPA Page template for editing.

Select the Layout Container and click it’s policy icon to edit the policy:

Under Allowed Components > WKND SPA React - Content > check Image, Teaser, and Title.

Under Default Components > Add mapping and choose the Image - WKND SPA React - Content component:

Enter a mime type of image/*.

Click Done to save the policy updates.

In the Layout Container click the policy icon for the Text component.

Create a new policy named WKND SPA Text. Under Plugins > Formatting > check all the boxes to enable additional formatting options:

Under Plugins > Paragraph Styles > check the box to Enable paragraph styles:

Click Done to save the policy update.

Navigate to the Homepage http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html.

You should now be able to use the additional components Image, Teaser, and Title on the page.

You should also be able to edit the Text component and add additional paragraph styles in full-screen mode.

You should also be able to drag+drop an image from the Asset finder:

Experiement with the Title and Teaser components.

Add your own images via AEM Assets or install the finished code base for the standard WKND reference site. The WKND reference site includes many images that can be re-used on the WKND SPA. The package can be installed using AEM’s Package Manager.

In a browser navigate to http://localhost:4502/content/wknd-spa-react/us/en.model.json

The Layout Container component has a sling:resourceType of wcm/foundation/components/responsivegrid and is recognized by the SPA Editor using the :type property, just like the Text and Image components.

The same capabilities of re-sizing a component using Layout Mode are available with the SPA Editor.

Return to http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html. Add additional Image components and try re-sizing them using the Layout option:

Re-open the JSON model http://localhost:4502/content/wknd-spa-react/us/en.model.json and observe the columnClassNames as part of the JSON:

The class name aem-GridColumn--default--4 indicates the component should be 4 columns wide based on a 12 column grid. More details about the responsive grid can be found here.

Return to the IDE and in the ui.apps module there is a client-side library defined at ui.apps/src/main/content/jcr_root/apps/wknd-spa-react/clientlibs/clientlib-grid. Open the file less/grid.less.

This file determines the breakpoints (default, tablet, and phone) used by the Layout Container. This file is intended to be customized per project specifications. Currently the breakpoints are set to 1200px and 768px.

You should be able to use the responsive capabilities and the updated rich text policies of the Text component to author a view like the following:

In the Visual Studio Code IDE, ensure that you have VSCode AEM Sync installed via the Marketplace extension:

Expand the ui.content module in the Project explorer and navigate to /conf/wknd-spa-react/settings/wcm/templates.

Right+Click the templates folder and select Import from AEM Server:

Repeat the steps to import content but select the policies folder located at /conf/wknd-spa-react/settings/wcm/templates/policies.

Inspect the filter.xml file located at ui.content/src/main/content/META-INF/vault/filter.xml.

<!--ui.content filter.xml-->
<?xml version="1.0" encoding="UTF-8"?>
 <workspaceFilter version="1.0">
     <filter root="/conf/wknd-spa-react" mode="merge"/>
     <filter root="/content/wknd-spa-react" mode="merge"/>
     <filter root="/content/dam/wknd-spa-react" mode="merge"/>
     <filter root="/content/experience-fragments/wknd-spa-react" mode="merge"/>
 </workspaceFilter>

The filter.xml file is responsible for identifying the paths of nodes that are installed with the package. Notice the mode="merge" on each of the filters which indicates that existing content will not be modified, only new content is added. Since content authors may be updating these paths, it is important that a code deployment does not overwrite content. See the FileVault documentation for more details on working with filter elements.

Compare ui.content/src/main/content/META-INF/vault/filter.xml and ui.apps/src/main/content/META-INF/vault/filter.xml to understand the different nodes managed by each module.

Navigate to the Image examples in the Core Component library.

Properties of src, alt, and title are used to populate the SPA Image component.

Next, create a new folder named Image under ui.frontend/src/components.

Beneath the Image folder create a new file named Image.js.

Add the following import statements to Image.js:

import React, {Component} from 'react';
import {MapTo} from '@adobe/aem-react-editable-components';

Then add the ImageEditConfig to determine when to show the placeholder in AEM:

export const ImageEditConfig = {

    emptyLabel: 'Image',

    isEmpty: function(props) {
        return !props || !props.src || props.src.trim().length < 1;
    }
};

The placeholder will show if the src property is not set.

Next implement the Image class:

 export default class Image extends Component {

    get content() {
        return <img     className="Image-src"
                        src={this.props.src}
                        alt={this.props.alt}
                        title={this.props.title ? this.props.title : this.props.alt} />;
    }

    render() {
        if(ImageEditConfig.isEmpty(this.props)) {
            return null;
        }

        return (
                <div className="Image">
                    {this.content}
                </div>
        );
    }
}

The above code will render an <img> based on the props src, alt, and title passed in by the JSON model.

Add the MapTo code to map the React component to the AEM component:

MapTo('wknd-spa-react/components/image')(Image, ImageEditConfig);

Note the string wknd-spa-react/components/image corresponds to the location of the AEM component in ui.apps at: ui.apps/src/main/content/jcr_root/apps/wknd-spa-react/components/image.

Create a new file named Image.css in the same directory and add the following:

.Image-src {
    margin: 1rem 0;
    width: 100%;
    border: 0;
}

In Image.js add a reference to the file at the top beneath the import statements:

import React, {Component} from 'react';
import {MapTo} from '@adobe/aem-react-editable-components';

require('./Image.css');

Open the file ui.frontend/src/components/import-components.js and add a reference to the new Image component:

import './Page/Page';
import './Text/Text';
import './Container/Container';
import './ExperienceFragment/ExperienceFragment';
import './Image/Image'; //add reference to Image component

In import-components.js comment out the React Core Component Image:

//MapTo('wknd-spa-react/components/image')(ImageV2, {isEmpty: ImageV2IsEmptyFn});

This will ensure that our custom Image component is used instead.

From the root of the project deploy the SPA code to AEM using Maven:

$ cd aem-guides-wknd-spa.react
$ mvn clean install -PautoInstallSinglePackage

Inspect the SPA in AEM. Any Image components on the page should continue to work. Inspect the rendered output and you should see the markup for our custom Image component instead of the React Core Component.

Custom Image component markup

<div class="Image">
    <img class="Image-src" src="/content/image-src.jpg">
</div>

React Core Component Image markup

<div class="cmp-image cq-dd-image">
    <img src="/content/image-src.jpg" class="cmp-image__image">
</div>

This is a good introduction to extending and implementing your own components.