AEM集成SPA(二)集成React完整教程

前言

这篇文章是对官方教程的整理,并实践动手排坑后做的总结,主要以SPA框架——React为代表,集成进AEM体系中。前端技术版本更新的太快,因此如果发现有问题,最好在 package.json 中为包设置成一致的版本。
文档和源码:pa空气n.b空气aidu.co空气m/s/1QHnzBa5saUVp_a63BLq5Hw 提取码:yoko

文章目录

  • 前言
  • 5 AEM SPA React完整教程
    • 5.1 Overview
    • 5.2 Project Setup
      • 5.2.1 说明
      • 5.2.2 配置aem-clientlibs-generator
      • 5.2.3 配置frontend-maven-plugin
      • 5.2.4 集成React App到Page
    • 5.3 Editable Components
      • 5.3.1 说明
      • 5.3.2 SPA Editor SDK的安装和集成
      • 5.3.3 Text Component
      • 5.3.4 Image Component
      • 5.3.5 HierarchyPage Sling Model
    • 5.4 Front End Development
      • 5.4.1 说明
      • 5.4.2 安装Sass
      • 5.4.3 通过代理获取JSON
      • 5.4.4 通过Mock获取JSON
      • 5.4.5 Header组件
      • 5.4.6 更新Image组件
      • 5.4.7 更新Text组件
      • 5.4.8 集成Responsive Grid
      • 5.4.9 集成Styleguidist
    • 5.5 Navigation and Routing
      • 5.5.1 说明
      • 5.5.2 SPA的路由方式
      • 5.5.3 安装React Router
      • 5.5.4 List Component
      • 5.5.5 更新Header组件
      • 5.5.6 添加Font Awesome图标
      • 5.5.7 重定向到首页

5 AEM SPA React完整教程

文档:

  • Getting Started with React and AEM SPA Editor
  • GitHub: WKND Events SPA Editor Project 每章教程都有对应Github的代码

5.1 Overview

https://helpx.adobe.com/experience-manager/kt/sites/using/getting-started-spa-wknd-tutorial-develop/react.html

技能要求:

  • Node.js
  • npm
  • webpack
  • Scss - todo
  • React Styleguidist - todo

环境要求:

  • Java 1.8
  • AEM 6.5 or AEM 6.4 + SP2
  • Apache Maven (3.3.9 or newer)
  • Node.js v10+
  • npm 6+

开发工具:

  • IntelliJ with AEM IDE Tooling - 这是那个用不起来的工具。。
  • Visual Studio - AEM Sync

Starter项目下载(建议从这里开始,每一章进行实操练习):

  • WKND Events React Starter Project
git clone [email protected]:Adobe-Marketing-Cloud/aem-guides-wknd-events.git
cd aem-guides-wknd-events
git checkout react/start

5.2 Project Setup

https://helpx.adobe.com/experience-manager/kt/sites/using/getting-started-spa-wknd-tutorial-develop/react/chapter-0.html

5.2.1 说明

这篇教程主要是项目初始化相关的内容,涉及到了打包插件、前端maven插件,以及示例的演示等。

新增的工程子模块:

  • react-app:React应用的webpack工程,后续的章节中此webpack工程将被转换成Maven模块作为client library发布到AEM

主要技术要求:

  • AEM editable template

  • create-react-app手脚架

  • aem-clientlib-generator:将react工程中编译后的css和js转化成AEM client library

    需要配置文件: clientlib.config.js

    此文件描述了react-app中的css和js位置,并发布到指定的aem clientlibs中

  • frontend-maven-plugin:通过Maven build来调用NPM命令行,确保项目依赖和持续集成发布

SPA模块和core模块相似,都是嵌入到了ui.apps模块再发布到AEM,详见下图:

AEM集成SPA(二)集成React完整教程_第1张图片

5.2.2 配置aem-clientlibs-generator

1)React工程初始化/启动/编译,在react-app模块下打开控制台

#淘宝镜像
npm config set registry https://registry.npm.taobao.org 
# 安装依赖
npm install
# 示例项目使用了create-react-app,启动手脚架
npm run start
# 编译
npm run build

2)安装aem-clientlib-generator,最新版本是1.7.3(写文档时测试过程出现过错误),教程中是1.4.1

cd <src>/aem-guides-wknd-events/react-app
# 默认安装最新的1.7.3
npm install aem-clientlib-generator --save-dev
# 或跟着教程版本1.4.1
npm install [email protected] --save-dev

这里可能会在编译时报错:Browserslist: caniuse-lite is outdated ,解决如下:

# 尝试更新所有包,没用
npm cache clean --force
npm update
# 尝试更新部分包,没用
npm update caniuse-lite browserslist
# 通过强制更新工具:https://www.npmjs.com/package/npm-update-all,太慢了
npm install npm-update-all -g
npm-update-all
# 通过npx更新嵌套的包
npx browserslist@latest --update-db
# 实际测试可行
npx [email protected] --update-db

3)aem-clientlib-generator的配置文件编写,此文件描述了react-app中的css和js位置,并发布到指定的aem clientlibs中,在react-app根目录创建文件:clientlib.config.js

module.exports = {
    // default working directory (can be changed per 'cwd' in every asset option)
    context: __dirname,
 
    // path to the clientlib root folder (output)
    clientLibRoot: "./../ui.apps/src/main/content/jcr_root/apps/wknd-events/clientlibs",
 
    libs: {
        name: "react-app",
        allowProxy: true,
        categories: ["wknd-events.react"],
        serializationFormat: "xml",
        jsProcessor: ["min:gcc"],
        assets: {
            js: [
                "build/static/**/*.js"
            ],
            css: [
                "build/static/**/*.css"
            ]
        }
    }
};

4)修改package.json中的npm启动scripts,目的是在build时触发aem-clientlib-generator工具

//package.json
...
 "scripts": {
   "build": "react-scripts build && clientlib --verbose",
    ...
}
...

5)编译测试

npm run build
# 成功后在/ui.apps/src/main/content/jcr_root/apps/wknd-events/clientlibs/目录下应该会有一个react-app的文件夹,里面有着打包后的css和js

6)在ui.apps/.gitignore中排除react-app,主要为了确保此目录每次都是动态编译生成的(可选,示例项目代码中默认有)

# ui.apps/.gitignore
# Ignore React generated client libraries from source control
react-app

5.2.3 配置frontend-maven-plugin

1)在root工程pom中添加react-app子模块

    <modules>
        
        <module>react-appmodule>
        <module>coremodule>
        <module>ui.appsmodule>
        <module>ui.contentmodule>
    modules>

2)查看本地node和npm的版本号,并作为properties配置到root的pom中

# 查看版本号
node -v # v12.13.1
npm -v # 6.12.1
    <properties>
        ...
        
        <frontend-maven-plugin.version>1.6frontend-maven-plugin.version>
        <node.version>v12.13.1node.version>
        <npm.version>6.12.1npm.version>
        
        ...
    properties>

3)在react-app子模块下创建pom.xml文件,在里面配置了frontend-maven-plugin


<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0modelVersion>
    
    
    
    <parent>
        <groupId>com.adobe.aem.guidesgroupId>
        <artifactId>aem-guides-wknd-eventsartifactId>
        <version>0.0.1-SNAPSHOTversion>
        <relativePath>../pom.xmlrelativePath>
    parent>
    
    
    
    
    <artifactId>aem-guides-wknd-events.react-appartifactId>
    <packaging>pompackaging>
    <name>WKND Events - React Appname>
    <description>UI React application code for WKND Eventsdescription>
    
    
    
    <build>
        <plugins>
            <plugin>
                <groupId>com.github.eirslettgroupId>
                <artifactId>frontend-maven-pluginartifactId>
                <version>${frontend-maven-plugin.version}version>
                <executions>
                    <execution>
                        <id>install node and npmid>
                        <goals>
                            <goal>install-node-and-npmgoal>
                        goals>
                        <configuration>
                            <nodeVersion>${node.version}nodeVersion>
                            <npmVersion>${npm.version}npmVersion>
                        configuration>
                    execution>
                    <execution>
                        <id>npm installid>
                        <goals>
                            <goal>npmgoal>
                        goals>
                        
                        <configuration>
                            <arguments>installarguments>
                        configuration>
                    execution>
                    <execution>
                        <id>npm run buildid>
                        <goals>
                            <goal>npmgoal>
                        goals>
                        <configuration>
                            <arguments>run buildarguments>
                        configuration>
                    execution>
                    
                    <execution>
                        <id>npm updateid>
                        <goals>
                            <goal>npmgoal>
                        goals>
                        <configuration>
                            <arguments>updatearguments>
                        configuration>
                    execution>
                executions>
            plugin>
        plugins>
    build>
project>

4)通过maven命令测试

cd <src>/aem-guides-wknd-events/react-app
mvn clean install 
# 通过frontend-maven-plugin插件,将自动运行配置的NPM脚本,从而编译react-app

5)最后将整个项目部署到AEM

(1)可以通过命令行,工程root下运行

cd <src>/aem-guides-wknd-events
mvn -PautoInstallPackage -Padobe-public clean install

(2)推荐通过IDEA的运行配置,上面命令行对应的IDEA运行配置如下:

AEM集成SPA(二)集成React完整教程_第2张图片

注意:由于npm中版本的不同,因此react-app编译时会有问题(有个依赖过期了),导致无法进行完整流程的编译和部署,目前此问题已修复,若未修复则需要单独编译完再打包。各个子模块的编译顺序:

  • react-app
  • core
  • apps
  • content

注意: IDEA的运行配置设置中需要激活Profile:adobe-public(用于解决运行时依赖问题),如下图:

AEM集成SPA(二)集成React完整教程_第3张图片

5.2.4 集成React App到Page

其实就是将SPA导出的Webpack工程集成到AEM的structure/page页面模板中

1)修改headerlibs:apps/wknd-events/components/structure/page/customheaderlibs.html

主要是meta和css设置,将导入到页首,具体的分析可以参考前文章节[4.9 SPA Page Component](#4.9 SPA Page Component)


<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />

<meta property="cq:datatype" data-sly-test="${wcmmode.edit || wcmmode.preview}" content="JSON" />

<meta property="cq:wcmmode" data-sly-test="${wcmmode.edit}" content="edit" />

<meta property="cq:wcmmode" data-sly-test="${wcmmode.preview}" content="preview" />

<meta property="cq:pagemodel_root_url"
      data-sly-use.page="com.adobe.aem.guides.wkndevents.core.models.HierarchyPage"
      content="${page.rootUrl}" />

<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html" />
<sly data-sly-call="${clientlib.css @ categories='wknd-events.react'}" />



2)修改footerlibs:apps/wknd-events/components/structure/page/customfooterlibs.html

主要是js依赖设置,将导入到页尾


<sly data-sly-use.clientLib="${'/libs/granite/sightly/templates/clientlib.html'}">sly>

<sly data-sly-test="${wcmmode.edit || wcmmode.preview}"
     data-sly-call="${clientLib.js @ categories='cq.authoring.pagemodel.messaging'}">sly>

<sly data-sly-call="${clientLib.js @ categories='wknd-events.react'}">sly>



3)创建React入口页面body.html

在apps/wknd-events/components/structure/page下创建:body.html


<div id="root">div>

4)安装与部署,不重复赘述了;然后访问以下页面测试:

http://localhost:4502/editor.html/content/wknd-events/react/home.html

5.3 Editable Components

https://helpx.adobe.com/experience-manager/kt/sites/using/getting-started-spa-wknd-tutorial-develop/react/chapter-1.html

5.3.1 说明

这篇教程在基于上一篇(项目初始化)的基础上,进行SPA的Editable Components开发。

重点:

  • 三个AEM SPA Editor JS SDK的安装和使用(集成)
  • SPA Editor SDK的概念和原理建议参考最先前的文章(4.6和4.8)
  • Text组件示例
  • Image组件示例
  • 示例为我们提供了一个SlingModel:HierarchyPage,并作出详细分析

5.3.2 SPA Editor SDK的安装和集成

SPA Editor SDK的概念和原理建议参考最先前的文章(4.6和4.8)。简要流程:AEM通过Sling Model导出JSON内容,SPA Editor SDK将JSON和React组件映射关联。

1)安装AEM SPA Editor JS SDK

# 打开控制台,进入react-app根目录
cd <src>/aem-guides-wknd-events/react-app
# 安装AEM SPA Editor JS SDK(3个)
npm install @adobe/cq-spa-component-mapping
npm install @adobe/cq-spa-page-model-manager
npm install @adobe/cq-react-editable-components
# 安装一些其它的依赖(4个)
npm install react-fast-compare
npm install typescript --save-dev
npm install ajv --save-dev
npm install clone --save-dev
# 安装后检查package.json中的dependencies(7个)和devDependencies(4个)是否齐全
  • @adobe/cq-spa-component-mapping - 映射AEM Components和SPA Components,此模块不依赖特定的SPA框架
  • @adobe/cq-spa-page-model-manager - 提供API,来管理用于组成SPA(页面)的AEM Pages的Model表示,此模块不依赖特定的SPA框架
  • @adobe/cq-react-editable-components - 提供通用的React helpers和Components支持AEM authoring;此模块还封装了cq-spa-page-model-manager和cq-spa-component-mapping以支持React框架

2)现在可以开始将AEM SPA editor JS SDK集成进React中了。首先是通过JSON Model(来自AEM)初始化App,修改:react-app/src/index.js,就是react的入口JS

import React from 'react';
import ReactDOM from 'react-dom';
import { ModelManager, Constants } from '@adobe/cq-spa-page-model-manager';
import './index.css';
import App from './App';

/**
 * 将ReactDOM渲染入口封装成函数,并初始化SPA Editor需要的相关属性
 * 可以看到依赖了App组件(真正的入口)
 */
function render(model) {
    ReactDOM.render(
        (<App cqChildren={ model[Constants.CHILDREN_PROP] }
             cqItems={ model[Constants.ITEMS_PROP] }
             cqItemsOrder={ model[Constants.ITEMS_ORDER_PROP] }
             cqPath={ ModelManager.rootPath }
             locationPathname={ window.location.pathname }/>),
        document.getElementById('root'));
}
/*初始化ModelManager*/
ModelManager.initialize({ path: process.env.REACT_APP_PAGE_MODEL_PATH }).then(render);

3)修改react-app/src/App.js,相当于首页,也是应用程序的入口

// src/App.js
import React from 'react';
import { Page, withModel, EditorContext, Utils } from '@adobe/cq-react-editable-components';
import './App.css';//注意这里CSS样式的引入在示例源码中没有,实际测试发现在Editor模式下出现页面向下无限滚动,就是样式导致的,建议注释掉。最后还需要清除Chrome缓存!

/**
 * This component is the application entry point
 * 这个组件就是应用程序入口
 * Page继承了react库的Component,因此可被React识别成组件
 * render()函数中,this.childComponents和this.childPages将\n
 * 自动导入React Components,这些组件由JSON Model驱动
 */
class App extends Page {
  render() {
    return (
        <div className="App">
          <header className="App-header">
            <h1>Welcome to AEM + React</h1>
          </header>
          { this.childComponents }
          { this.childPages }
        </div>
    );
  }
}

export default withModel(App);

4)开始创建Page组件(React),在src下创建,目录结构如下:

/react-app
	/src
		/components
			/page
				Page.js
				Page.css

Page.js

/**
 * Page.js
 * - WKND specific implementation of Page
 * - Maps to wknd-events/components/structure/page
 */
import {Page, MapTo, withComponentMappingContext } from "@adobe/cq-react-editable-components";
require('./Page.css');

/**
 * 此组件是React Component的一个变体,将映射"structure/page"的resource type
 * 目前除了添加特定的css样式外没有做其他的功能更改
 * 在这个例子中,通过MapTo函数实现了AEM组件和React组件的映射
 * 映射resourceType:wknd-events/components/structure/page的AEM组件 -> 此React组件
 */
class WkndPage extends Page {

    get containerProps() {
        let attrs = super.containerProps;
        attrs.className = (attrs.className || '') + ' WkndPage ' + (this.props.cssClassNames || '');
        return attrs
    }
}

MapTo('wknd-events/components/structure/page')(withComponentMappingContext(WkndPage));

Page.css

/* Center and max-width the content */
.WkndPage {
    max-width: 1200px;
    margin: 0 auto;
    padding: 12px;
    padding: 0;
    float: unset !important;
}

5)在 /react-app/src/components 下创建:MappedComponents.js

/**
 * Dedicated file to include all React components that map to an AEM component
 * 导入所有和AEM映射的React组件的专用JS文件
 */
require('./page/Page');

6)更新 /react-app/src/index.js ,导入MappedComponents

// src/index.js
    ...
    import App from './App';
    //include Mapped Components
+  import "./components/MappedComponents";
    ...

7)编译安装,测试访问:http://localhost:4502/content/wknd-events/react/home.html

审查元素,可以看到自己组件里的样式:

AEM集成SPA(二)集成React完整教程_第4张图片

5.3.3 Text Component

自定义的React组件,映射了AEM的Text组件

1)创建如下结构的Text React组件,目录结构

/react-app
	/src
		/components
			/text
				Text.js
				Text.css

2)Text.css暂时为空,Text.js代码如下:

/**
 * Text.js
 * Maps to wknd-events/components/content/text
 */
import React, {Component} from 'react';
import {MapTo} from '@adobe/cq-react-editable-components';

/**
 * Default Edit configuration for the Text component that interact with the Core Text component and sub-types
 * Text组件的默认的Edit配置,此配置与AEM的Core Text Component和sub-types交互
 * @type EditConfig
 * @type {{isEmpty: (function(*=): boolean), emptyLabel: string}}
 */
const TextEditConfig = {

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

/**
 * Text React component
 * 作为普通的组件,仅需继承React的Component即可
 */
class Text extends Component {

    get richTextContent() {
        return <div dangerouslySetInnerHTML={{__html:  this.props.text}}/>;
    }

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

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

MapTo('wknd-events/components/content/text')(Text, TextEditConfig);

3)更新 react-app/src/components/MappedComponents.js ,加入新的Text组件依赖

/**
 * Dedicated file to include all React components that map to an AEM component
 * 导入所有和AEM映射的React组件的专用JS文件
 */
require('./page/Page');
require('./text/Text');

4)安装部署,模块顺序注意一定要是:先react-app,后ui.apps

mvn -PautoInstallPackage -Padobe-public clean install

5)测试访问:http://localhost:4502/editor.html/content/wknd-events/react/home.html,此时的Text组件是一个空组件,可以进行编辑(过程中出现了点小问题,清除浏览器缓存即可),实际测试结果:

AEM集成SPA(二)集成React完整教程_第5张图片

6)测试访问当前Page的JSON数据(Sling Model Exporter导出)

访问:http://localhost:4502/content/wknd-events/react/home.model.json

可以看到整体的页面结构,这就是SPA Editor进行逐层分析并做映射的数据源,具体JSON可自己分析,其中找到当前的Text组件的JSON数据如下:

AEM集成SPA(二)集成React完整教程_第6张图片

此使可以重写结合步骤2中的Text.js的代码进行分析,可以看到:MapTo函数(来自@adobe/cq-react-editable-components)通过JSON字段 :type 进行组件映射,并且能够将JSON中的其它字段通过 this.props.xxx 进行访问,此组件中就如:

this.props.text === "文本文本文本"
this.props.richText === true

5.3.4 Image Component

这一节以编写Image的React组件为例

1)创建如下结构的Image组件,目录结构

/react-app
	/src
		/components
			/image
				Image.js
				Image.css

2)Image.css暂时为空,Image.js代码如下:

/**
 * Image.js
 * Maps to wknd-events/components/content/image
 */
import React, {Component} from 'react';
import {MapTo} from '@adobe/cq-react-editable-components';

/**
 * Default Edit configuration for the Image component that interact with the Core Image component and sub-types
 * Image 组件的默认的Edit配置,此配置与AEM的Core Image Component和sub-types交互
 * @type EditConfig
 * @type {{isEmpty: (function(*=): boolean), emptyLabel: string}}
 */
const ImageEditConfig = {

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

/**
 * Image React component
 * 作为普通的组件,仅需继承React的Component即可
 */
class Image extends Component {

    get content() {
        return <img src={this.props.src} alt={this.props.alt}
                    title={this.props.displayPopupTitle && this.props.title}/>
    }

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

MapTo('wknd-events/components/content/image')(Image, ImageEditConfig);

3)更新 react-app/src/components/MappedComponents.js ,加入新的Image组件依赖

/**
 * Dedicated file to include all React components that map to an AEM component
 * 导入所有和AEM映射的React组件的专用JS文件
 */
require('./page/Page');
require('./text/Text');
require('./image/Image');

4)安装部署

  1. 访问页面测试:

http://localhost:4502/editor.html/content/wknd-events/react/home.html

同样的,会看到默认为空的Image组件,可以对它进行各种编辑,Image组件支持拖拽。

  1. 查看页面JSON:

http://localhost:4502/content/wknd-events/react/home.model.json

找到当前Component的JSON如下:

"image": {
"alt": "Rain",
"src": "/content/wknd-events/react/home/_jcr_content/root/responsivegrid/image.coreimg.jpeg/1591154158036/wknd-events.jpeg",
"srcUriTemplate": "/content/wknd-events/react/home/_jcr_content/root/responsivegrid/image.coreimg{.width}.jpeg/1591154158036/wknd-events.jpeg",
"areas": [],
"uuid": "b1160ef2-2c65-4de8-8b5d-491e2be3ef56",
"widths": [],
"lazyEnabled": false,
"link": "/content/wknd-events/react.html",
":type": "wknd-events/components/content/image"
}

和Text组件类似,Sling Model Exporter导出的JSON中的所有字段都能够被React的Image组件使用。

下篇教程将会开始CSS样式的添加,并向前端开发圈子看齐~

5.3.5 HierarchyPage Sling Model

这一小节是额外内容,主要分析了官方的示例项目中提供的Sling Model:HierarchyPage。

HierarchyPageImpl为我们提供了在单次请求中能够获取多AEM Pages的content的能力,也就是通过一个JSON的导出所有相关的content内容。

1)在core子模块中,接口com.adobe.aem.guides.wkndevents.core.models.HierarchyPage代码片段如下:

package com.adobe.aem.guides.wkndevents.core.models;

import com.adobe.cq.export.json.ContainerExporter;
import com.adobe.cq.export.json.hierarchy.HierarchyNodeExporter;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonProperty;

public interface HierarchyPage extends HierarchyNodeExporter, ContainerExporter {...}

它继承了2个接口:

  • ContainerExporter:定义了容器组件的JSON,如:Page、Responsive Grid、Parsys
  • HierarchyNodeExporter:定义了层次节点的JSON,如:Root Page和它的Child Pages

2)接着分析其实现类:com.adobe.aem.guides.wkndevents.core.models.impl.HierarchyPageImpl

官方的说明:在示例项目中,HierarchyPageImpl被单独拷贝在项目中使用。不久后HierarchyPageImpl将通过Core Components库提供。开发者仍可以自行扩展该接口,但不再需要负责维护这个接口的实现了。请确保备份和更新。

...
@Model(adaptables = SlingHttpServletRequest.class, adapters = {HierarchyPage.class, ContainerExporter.class}, resourceType = HierarchyPageImpl.RESOURCE_TYPE)
@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME, extensions = ExporterConstants.SLING_MODEL_EXTENSION)
public class HierarchyPageImpl implements HierarchyPage {
    /**
     * Resource type of associated with the current implementation
     */
    protected static final String RESOURCE_TYPE = "wknd-events/components/structure/page";
    ...
}

上面代码片段中可以看到,HierarchyPageImpl被注册成"wknd-events/components/structure/page"资源类型的Sling Model Exporter。如果需要在自己的项目中需要自定义的接口实现,就需要修改 RESOURCE_TYPE 指向自定义项目的 page component,也就是基础的page原型组件(AEM的)。

最后再稍微介绍一下实现类中的几个重要方法:getRootModel()getRootPage() 将返回对应的根节点,方法中有三个fields说明如下:

    /**
     * Is the current model to be considered as a model root
     * 帮助识别程序的rootPage。rootPage被用作app的运行入口,它还集成了所有的child pages
     */
    private static final String PR_IS_ROOT = "isRoot";

    /**
     * Depth of the tree of pages
     * 标识在层次结构中收集子页面(child pages)的深度
     */
    private static final String STRUCTURE_DEPTH_PN = "structureDepth";

    /**
     * List of Regexp patterns to filter the exported tree of pages
     * 正则表达式,用于忽略或排除不需要被自动收集(collect)的页面
     */
    private static final String STRUCTURE_PATTERNS_PN = "structurePatterns";

3)看完实现类,接着我们来看下如何查看和修改上一步中提到的字段的值。

在AEM的Lite中,找到editable template的policy节点:

/conf/wknd-events/settings/wcm/policies/wknd-events/components/structure/app/default

这里我通过JSON获取此节点的值,浏览器访问:

http://localhost:4502/conf/wknd-events/settings/wcm/policies/wknd-events/components/structure/app/default.json

结果如下:

{
    "jcr:primaryType": "nt:unstructured",
    "jcr:title": "SPA Page",
    "isRoot": true,
    "structurePatterns": "(react/)(?:(?!blog)(/)?)",
    "jcr:description": "Default policy of the page",
    "sling:resourceType": "wcm/core/components/policy/policy",
    "structureDepth": "2"
}

官方的提示: 目前没有UI界面修改这些字段,只能在Lite中手动修改或在ui.content子模块修改xml文件。完善的功能将在未来推出。

4)示例中的页面分析

示例中的根页面react.html:http://localhost:4502/content/wknd-events/react.html,是基于 wknd-events-app-template 创建的,通过添加后缀 .model.json 访问此页面的JSON:

http://localhost:4502/content/wknd-events/react.model.json

可以查看当前页和其子页面home.html的content内容。

5.4 Front End Development

https://helpx.adobe.com/experience-manager/kt/sites/using/getting-started-spa-wknd-tutorial-develop/react/chapter-2.html

5.4.1 说明

这一章关注于前端开发(游离于AEM外)。前端开发者能够修改JS和CSS,并且能立即在浏览器上看到效果,这个过程中不需要完整的编译(development build)。当前流行的前端工具:Webpack development server、SASS、Styleguidist已被示例项目集成,加速前端开发。

主要内容:

  • Sass的使用
  • 为了实现前端的独立开发,需要有获取Sling Model的JSON数据的能力,两种方式:
    • 为create-react-app设置AEM服务的代理
    • 通过本地Mock JSON数据文件(这里没有用到MockJS技术,不太推荐)
  • 添加Header组件
  • 为Image组件和Text组件添加样式
  • 在React工程中集成Responsive Grid,AEM Authoring页面后可以同步效果
  • Styleguidist的使用,自动生成Image和Text的Markdown文档

5.4.2 安装Sass

对于React组件,需要保证模块化的独立性,因此它推荐尽量避免复用具有相同class name的CSS样式(组件间)。示例项目将引入Sass的几个实用功能实现样式复用:variables、mixins。此项目还会遵循: SUIT CSS naming conventions. (SUIT是BEM表示法(块元素修饰符)的一种变体,用于创建一致的CSS规则)。

1)安装Sass

# 进入react-app目录
cd <src>/aem-guides-wknd-events/react-app
# 安装node-sass
npm install node-sass --save
# 装完后就能在项目中看.scss文件了
# 更多有关adding a Sass stylesheet with a React project的帮助:https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-a-sass-stylesheet

2)创建以下目录结构和文件,用于存放scss共享样式:

/react-app
	/src
		/components
      + /styles
          + _shared.scss
          + _variables.scss

3)_variables.scss内容:

//variables for WKND Events

//Typography
$em-base:             20px;
$base-font-size:      1rem;
$small-font-size:     1.4rem;
$lead-font-size:      2rem;
$title-font-size:     5.2rem;
$h1-font-size:        3rem;
$h2-font-size:        2.5rem;
$h3-font-size:        2rem;
$h4-font-size:        1.5rem;
$h5-font-size:        1.3rem;
$h6-font-size:        1rem;
$base-line-height:    1.5;
$heading-line-height: 1.3;
$lead-line-height:    1.7;

$font-serif:         'Asar', serif;
$font-sans:          'Source Sans Pro', sans-serif;

$font-weight-light:      300;
$font-weight-normal:     400;
$font-weight-semi-bold:  600;
$font-weight-bold:       700;

//Colors
$color-white:            #ffffff;
$color-black:            #080808;

$color-yellow:           #FFEA08;
$color-gray:             #808080;
$color-dark-gray:        #707070;

//Functional Colors
$color-primary:          $color-yellow;
$color-secondary:        $color-gray;
$color-text:             $color-gray;

//Layout
$max-width: 1200px;
$header-height: 80px;
$header-height-big: 100px;

// Spacing
$gutter-padding: 12px;

// Mobile Breakpoints
$mobile-screen: 160px;
$small-screen:  767px;
$medium-screen: 992px;

4)shared.scss内容:

@import './_variables';

//Mixins
@mixin media($types...) {
  @each $type in $types {

    @if $type == tablet {
      @media only screen and (min-width: $small-screen + 1) and (max-width: $medium-screen) {
        @content;
      }
    }

    @if $type == desktop {
      @media only screen and (min-width: $medium-screen + 1) {
        @content;
      }
    }

    @if $type == mobile {
      @media only screen and (min-width: $mobile-screen + 1) and (max-width: $small-screen) {
        @content;
      }
    }
  }
}

@mixin content-area () {
  max-width: $max-width;
  margin: 0 auto;
  padding: $gutter-padding;
}

@mixin component-padding() {
  padding: 0 $gutter-padding !important;
}

@mixin drop-shadow () {
  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
}

5.4.3 通过代理获取JSON

这小结主要讲了如何通过代理的方式获取AEM Server的JSON数据,实现在create-react-app手脚架上实时开发的目的。在create-react-app脚手架自带的服务器(localhost:3000)上做实时的前端开发时,可以通过这种代理的方式,获取来自AEM content的JSON Model和images等数据源。

有关Create React App脚手架中的Proxying的更多信息,可以参考:Proxying API Requests in Development

前提条件:

  • 一个运行在:http://localhost:4502/ 的AEM Server实例
  • create-react-app
  • 在react-app工程下打开编辑器

过程:

1)对于示例项目,在前面的章节中,我们已经通过create-react-app脚手架创建项目了,因此这里能够直接配置proxy功能。修改react-app/package.json,添加代理配置:

// package.json
...
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build && clientlib --verbose",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "proxy": "http://localhost:4502",
...

2)在/react-app根目录下创建文件:.env.development

# Configure Proxy end point,定义了Page Model的JSON数据源地址
REACT_APP_PAGE_MODEL_PATH=/content/wknd-events/react.model.json

.env.development 是一种环境变量的配置文件,它在node应用以开发模式(development mode)运行时加载。更多信息可以参考: environment variables can be found here 。

其实在前面的章节中,文件 src/index.js 中已经使用到了这个环境变量:

// src/index.js
...
/*初始化ModelManager*/
ModelManager.initialize({ path: process.env.REACT_APP_PAGE_MODEL_PATH }).then(render);

3)启动creat-react-app脚手架服务器(http://localhost:3000),控制台输入:

# 进入react-app目录
cd <src>/aem-guides-wknd-events/react-app
# 启动服务
npm run start # 可以直接:npm start

4)登录AEM Server(http://localhost:4502),然后访问react服务:

http://localhost:3000/content/wknd-events/react/home.html

如果没出错误的话,你将在create-react-app服务中看到和AEM Server中一样的页面。

**注意:**你必须提前登录AEM Server,否则代理将无法访问,导致页面为空白。

在create-react-app中设置Proxy可能会出现跨域问题,如果你遇到了如下的问题,可以参考: AEM CORS configuration 。

Fetch API cannot load http://localhost:4502/content.... No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:3000' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

5)将 /src/index.css 更名为 index.scss,然后更新内容:

/* src/index.scss */
@import './styles/shared';
/* Google Font import */
@import url('https://fonts.googleapis.com/css?family=Asar|Source+Sans+Pro:400,600,700');

body {
  //font-weight: $normal;
  background-color: $color-white;
  font-family: $font-sans;
  margin: 0;
  padding: 0;

  font-weight: $font-weight-light;
  font-size: $em-base;
  text-align: left;
  color: $color-black;
  line-height: 1.5;
  line-height: 1.6;
  letter-spacing: 0.3px;
}

h1, h2, h3, h4 {
  font-family: $font-sans;
}

h1 {
  font-size:  $h1-font-size;
}

h2 {
  font-size: $h2-font-size;
}

h3 {
  font-size: $h3-font-size;
}

h4 {
  font-size: $h4-font-size;
}

h5 {
  font-size: $h5-font-size;
}

h6 {
  font-size: $h6-font-size;
}

p {
  color: $color-text;
  font-family: $font-serif;
}

ul {
  list-style-position: inside;
}

// abstracts/overrides

ol, ul {
  padding-left: 0;
  margin-bottom: 0;
}

hr {
  height: 2px;
  //background-color: fade($dusty-gray, (.3*100));
  border: 0 none;
  margin: 0 auto;
  max-width: $max-width;
}

*:focus {
  outline: none;
}

textarea:focus, input:focus{
  outline: none;
}

body {
  overflow-x: hidden;
}

img {
  vertical-align: middle;
  border-style: none;
  width: 100%;
}

6)修改 /src/index.js 中的样式导入

// src/index.js
...
- import './index.css';
+ import './index.scss';
...

7)重新访问测试:http://localhost:3000/content/wknd-events/react/home.html

这里可以在index.scss中为h1类样式添加color属性,然后查看浏览器动态更新:

h1 {
  font-size:  $h1-font-size;
  color: $color-yellow;
}

5.4.4 通过Mock获取JSON

和上一小节中代理方式的目的一致,这一小节将通过使用静态的JSON文件来模拟JSON数据。通过这种方式,react-app工程将不依赖AEM Server实例。同时,此方法还能让前端开发者实时更新JSON数据、方便功能测试、模拟新的JSON相应实体,完全不依赖后端开发者。

1)首先需要获取一份Sling Model Exporter导出的JSON数据,第一次获取是需要启动并登录AEM Server实例的。在示例项目中,访问下面的链接获取页面(react.html)的完整JSON,然后保存它。

http://localhost:4502/content/wknd-events/react.model.json,这里给出我的示例(复制粘贴即可):

{
  "title": "React App",
  ":type": "wknd-events/components/structure/app",
  ":itemsOrder": [],
  ":items": {},
  ":path": "/content/wknd-events/react",
  ":hierarchyType": "page",
  ":children": {
    "/content/wknd-events/react/home": {
      "title": "Home",
      ":type": "wknd-events/components/structure/page",
      ":itemsOrder": [
        "root"
      ],
      ":items": {
        "root": {
          "columnCount": 12,
          "allowedComponents": {
            "applicable": false,
            "components": [
              {
                "path": "/conf/wknd-events/settings/wcm/templates/wknd-events-page-template/structure/jcr:content/root/wcm/foundation/components/responsivegrid",
                "title": "Layout Container"
              },
              {
                "path": "/conf/wknd-events/settings/wcm/templates/wknd-events-page-template/structure/jcr:content/root/wknd-events/components/content/image",
                "title": "Image"
              },
              {
                "path": "/conf/wknd-events/settings/wcm/templates/wknd-events-page-template/structure/jcr:content/root/wknd-events/components/content/list",
                "title": "List"
              },
              {
                "path": "/conf/wknd-events/settings/wcm/templates/wknd-events-page-template/structure/jcr:content/root/wknd-events/components/content/text",
                "title": "Text"
              }
            ]
          },
          "columnClassNames": {
            "responsivegrid": "aem-GridColumn aem-GridColumn--default--12"
          },
          "gridClassNames": "aem-Grid aem-Grid--12 aem-Grid--default--12",
          ":itemsOrder": [
            "responsivegrid"
          ],
          ":items": {
            "responsivegrid": {
              "columnCount": 12,
              "allowedComponents": {
                "applicable": false,
                "components": [
                  {
                    "path": "/content/wknd-events/react/home/jcr:content/root/responsivegrid/wcm/foundation/components/responsivegrid",
                    "title": "Layout Container"
                  },
                  {
                    "path": "/content/wknd-events/react/home/jcr:content/root/responsivegrid/wknd-events/components/content/image",
                    "title": "Image"
                  },
                  {
                    "path": "/content/wknd-events/react/home/jcr:content/root/responsivegrid/wknd-events/components/content/list",
                    "title": "List"
                  },
                  {
                    "path": "/content/wknd-events/react/home/jcr:content/root/responsivegrid/wknd-events/components/content/text",
                    "title": "Text"
                  }
                ]
              },
              "columnClassNames": {
                "image": "aem-GridColumn aem-GridColumn--default--12",
                "text": "aem-GridColumn aem-GridColumn--default--12"
              },
              "gridClassNames": "aem-Grid aem-Grid--12 aem-Grid--default--12",
              ":itemsOrder": [
                "text",
                "image"
              ],
              ":items": {
                "text": {
                  "text": "

Rain forecast

\n
    \n
  1. not a nici day
  2. \n
  3. ohh
  4. \n
\n"
, "richText": true, ":type": "wknd-events/components/content/text" }, "image": { "alt": "Rain", "src": "/content/wknd-events/react/home/_jcr_content/root/responsivegrid/image.coreimg.jpeg/1591154158036/wknd-events.jpeg", "srcUriTemplate": "/content/wknd-events/react/home/_jcr_content/root/responsivegrid/image.coreimg{.width}.jpeg/1591154158036/wknd-events.jpeg", "areas": [], "uuid": "b1160ef2-2c65-4de8-8b5d-491e2be3ef56", "widths": [], "lazyEnabled": false, "link": "/content/wknd-events/react.html", ":type": "wknd-events/components/content/image" } }, ":type": "wcm/foundation/components/responsivegrid" } }, ":type": "wcm/foundation/components/responsivegrid" } }, ":path": "/content/wknd-events/react/home", ":hierarchyType": "page" } } }

2)进入react-app工程,在目录 /react-app/public 下创建文件: mock.model.json ,复制前面内容

/react-app
	/public
		favicon.ico
        index.html
        manifest.json
      + mock.model.json
	/src
		...

3)继续在public下创建目录 images ,存放图片静态文件,目录结构如下:

PS:图片可以去这个网站获取 Unsplash.com

/react-app
	/public
		favicon.ico
        index.html
        manifest.json
        mock.model.json
      + /images
      + 	mock-image.jpg
	/src
		...

4)修改 mock.model.json 文件中的图片路径,搜索: wknd-events/components/content/image

"image": {
      ...
    - "src": "旧的图片地址",
    + "src": "/images/mock-image.jpeg"
      "srcUriTemplate": "...",
      ...
      ":type": "wknd-events/components/content/image"
}

5)更新 react-app/.env.development 环境变量文件,添加Mock的JSON路径:

# Configure Proxy end point,定义了Page Model的JSON数据源地址
# REACT_APP_PAGE_MODEL_PATH=/content/wknd-events/react.model.json

# Request the JSON from Mock JSON,制定了本地的静态JSON数据源,PS:public目录下的文件发布后将在根路径下
REACT_APP_PAGE_MODEL_PATH=mock.model.json

6)重启 create-react-app 脚手架工程

# 先ctrl+c结束进程,然后重新启动
npm run start

测试访问:http://localhost:3000/ 或 http://localhost:3000/content/wknd-events/react/home.html (有关链接这里有个疑问,为什么都可以?但测试过来只要是3000端口的任意路径都是能访问的,也就是说,目前暂时还没有将React的路由功能放进去)

然后尝试修改 mock.model.json 内容,查看页面变化

7)最后我补充一点,通过Mock JSON文件这种方式,并没有关闭Proxy代理,因为在查找JSON文件时,先在public目录下获取到了文件,因此不会再通过代理访问AEM Server。

5.4.5 Header组件

这一小节运用前面的知识创建Header组件。

1)在 /react-app/src/components 下创建如下的目录结构和文件:

/react-app
	/src
		/components
		+	/header
		+		Header.js
		+		Header.scss

Header.js

// src/components/header/Header.js

import React, {Component} from 'react';
import './Header.scss';

export default class Header extends Component {

    render() {
        return (
            <header className="Header">
                <div className="Header-wrapper">
                    <h1 className="Header-title">WKND<span className="Header-title--inverse">_</span></h1>
                </div>
            </header>
        );
    }
}

Header.scss

@import '../../styles/shared';

.Header {
  background-color: $color-primary;
  height: $header-height;
  width: 100%;
  position: fixed;
  top: 0;
  z-index: 99;

  @include media(tablet,desktop) {
    height: $header-height-big;
  }

  &-wrapper {
    @include content-area();
    display: flex;
    justify-content: space-between;
  }

  &-title {
    font-family: 'Helvetica';
    font-size: 20px;
    float: left;
    padding-left: $gutter-padding;

    @include media(tablet,desktop) {
      font-size: 24px;
    }
  }

  &-title--inverse {
    color: $color-white;
  }
}

2)更新 react-app/src/App.js 文件,将Header组件包含进去

...
+ import Header from './components/header/Header';

class App extends Page {
    render() {
        return (
            <div className="App">
                <Header/> {/*添加Header组件*/}
                <header className="App-header">
                    <h1>Welcome to AEM + React</h1>
                </header>
                {this.childComponents}
                {this.childPages}
            </div>
        );
    }
}
...

3)更新 react-app/src/index.scss ,添加header相关的样式

/* index.scss */
body {
    //font-weight: $normal;
    background-color: $color-white;
    font-family: $font-sans;
    margin: 0;
    padding: 0;
    font-weight: $font-weight-light;
    font-size: $em-base;
    text-align: left;
    color: $color-black;
    line-height: 1.5;
    line-height: 1.6;
    letter-spacing: 0.3px;
 
+    padding-top: $header-height-big;
+    @include media(mobile, tablet) {
+        padding-top: $header-height;
+    }
}

4)查看浏览器效果

AEM集成SPA(二)集成React完整教程_第7张图片

5.4.6 更新Image组件

为第三章中的Image Component添加caption标题

1)修改 react-app/src/components/image/Image.js

...
+ import './Image.scss'; //也可以 require('./Image.scss');

...
class Image extends Component {
 
+    get caption() {
+        if(this.props.title && this.props.title.length > 0) {
+            return <span className="Image-caption">{this.props.title}</span>;
+        }
+        return null;
+    }
 
    get content() {
        return <img src={this.props.src} alt={this.props.alt}
            title={this.props.displayPopupTitle && this.props.title}/>
    }
 
    render() {
        return (<div className="Image">
                {this.content}
+               {this.caption}
            </div>);
    }
}
...

2)修改/创建文件 react-app/src/components/image/Image.scss

@import '../../styles/shared';

.Image {
  @include component-padding();

  &-image {
    margin: 2rem 0;
    width: 100%;
    border: 0;
    font: inherit;
    padding: 0;
    vertical-align: baseline;
  }

  &-caption {
    color: $color-white;
    background-color: $color-black;
    height: 3em;
    position: relative;
    padding: 20px 10px;
    top: -10px;
    @include drop-shadow();

    @include media(tablet) {
      padding: 25px 15px;
      top: -14px;
    }

    @include media(desktop) {
      padding: 30px 20px;
      top: -16px;
    }
  }
}

3)查看页面效果,发现没有caption

AEM集成SPA(二)集成React完整教程_第8张图片

4)修改 mock.model.json 文件,为image组件添加title属性

"image": {
+ "title": "This is a caption.",
  ...
  ":type": "wknd-events/components/content/image"
}

5)查看页面效果,caption出来了

AEM集成SPA(二)集成React完整教程_第9张图片

5.4.7 更新Text组件

为前面的Text Component添加样式

1)更新 react-app/src/components/text/Text.js

...
+ import './Text.scss';//或者 require('./Text.scss')

...
class Text extends Component {
...
    render() {
+        let innercontent = this.props.richText ? this.richTextContent : this.textContent;
+        return (<div className="Text">
+            {innercontent}
+        </div>)
-        //return this.props.richText ? this.richTextContent : this.textContent;
    }
}
...

2)新增/修改 react-app/src/components/text/Text.scss

@import '../../styles/shared';

.Text {
  @include component-padding();
}

5.4.8 集成Responsive Grid

原先在AEM的Editor.html模式下,有一个Layout Mode,这个Mode下我们可以动态的修改组件大小。SPA Editor 框架为我们引入了这个能力,我们只需要集成AEM的Responsive Grid到我们的React框架即可使用。

starter 示例项目中,有一个Responsive Grid专用的client library已经被引入,位于 ui.apps 子模块。你可以通过下面路径查看:

/aem-guides-wknd-events/ui.apps/src/main/content/jcr_root/apps/wknd-events/clientlibs/responsive-grid

这个client library有一个category属性:wknd-events.grid ,并且包含了名为 grid.less 的样式文件,这个样式文件为Layout Mode提供了基础样式,请确保在接下来的React APP中,此CSS样式文件被正确加载。

1)打开 /react-app/clientlib.config.js (clientlib插件配置文件),添加dependencies属性:

module.exports = {

    ...

    libs: {
        name: "react-app",
        allowProxy: true,
        categories: ["wknd-events.react"],
        serializationFormat: "xml",
        jsProcessor: ["min:gcc"],
+        dependencies:["wknd-events.grid"],//添加样式库依赖
        assets: {
            js: [
                "build/static/**/*.js"
            ],
            css: [
                "build/static/**/*.css"
            ]
        }
    }
};

2)重新编译React工程,然后将AEM项目打包部署;接着访问测试:

http://localhost:4502/editor.html/content/wknd-events/react/home.html

现在你能够在Editor模式下通过toolbar修改组件的大小了,如下图所示:

AEM集成SPA(二)集成React完整教程_第10张图片

修改Text组件大小:

AEM集成SPA(二)集成React完整教程_第11张图片

3)现在可以进行自由的创作了,这里我照着原教程简单的Authoring了此页面,请自由发挥

AEM集成SPA(二)集成React完整教程_第12张图片

4)最后,为了确保在React工程中能够正常使用Responsive Grid CSS,做以下修改:

  1. 找到 react-app/public/index.html ,引用AEM的responsive-grid.css
<head>
+ <link rel="stylesheet" href="/etc.clientlibs/wknd-events/clientlibs/responsive-grid.css" type="text/css">
...
head>

**PS:**这里使用了 /etc.clientlibs 前缀获取clientlibs的资源文件,是一种固定用法,详细的介绍可自行查找官方文档有关于clientlibs篇章内容。

  1. 修改 react-app/.env.development 文件,将JSON的获取方式从静态文件改回代理模式
# Configure Proxy end point,定义了Page Model的JSON数据源地址
REACT_APP_PAGE_MODEL_PATH=/content/wknd-events/react.model.json

# Request the JSON from Mock JSON,制定了本地的静态JSON数据源,PS:public目录下的文件发布后将在根路径下
# REACT_APP_PAGE_MODEL_PATH=mock.model.json

5)重启React工程 npm start ,访问测试:http://localhost:3000/content/wknd-events/react/home.html,此时你能看到经AEM的Authoring后的Responsive Grid相关的效果了。

**提示:**如果你想完全的前端本地开发,不依赖AEM,你应该将AEM的responsive grid CSS文件内容复制出来,粘贴到React工程的 react-app/public/grid.css 文件中,并修改 react-app/public/index.html 文件中css的依赖路径。

5.4.9 集成Styleguidist

开发SPA组件的一种流行方法是单独开发它们。 这使开发人员可以跟踪组件可能处于的各种状态。有许多方便开发的工具如: Styleguidist 和 Storybook ,示例项目中将会使用Styleguidist,因为它将样式指南和文档组合到一个工具中。

PS: 其实就是一个文档编写工具,通常来说文档和代码是分离的,代码更新了文档还需要修改, React Styleguidist 就能做到,可以参考:使用 React Styleguidist 编写文档 。

1)安装Styleguidist

# 进入react-app模块
cd <src>/aem-guides-wknd-events/react-app
# 安装Styleguidist
npm install react-styleguidist --save

2)打开 react-app/package.json 添加Styleguidist相关的scripts脚本

  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build && clientlib --verbose",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
+    "styleguide": "styleguidist server",
+    "styleguide:build": "styleguidist build"
  },

3)在 react-app/ 根目录下创建文件: styleguide.config.js

const path = require('path')
module.exports = {
    components: 'src/components/**/[A-Z]*.js',
    assetsDir: 'public/images',
    require: [
        path.join(__dirname, 'src/index.scss')
    ],
    ignore: ['src/components/**/Page.js', 'src/components/**/MappedComponents.js', 'src/components/**/Header.js', '**/__tests__/**', '**/*.test.{js,jsx,ts,tsx}', '**/*.spec.{js,jsx,ts,tsx}', '**/*.d.ts']
}

此配置文件描述:

  • components:扫描被export的组件,支持正则
  • asseDir:静态资源文件路径
  • require:引入文档需要的样式文件,__dirnam 表示被执行js文件的绝对路径,参考
  • ignore:忽略的组件

4)导出Image组件,修改 react-app/src/components/image/Image.js

/**
 * Image React component
 * 作为普通的组件,仅需继承React的Component即可
 */
export default class Image extends Component {
...

5)创建markdown文档: react-app/src/components/image/Image.md

Image:
​```js
Alternative Text here
​```
Image with a caption:
​```js
Alternative Text here
​```

未启动Styleguidist server,此时md显示如下:

AEM集成SPA(二)集成React完整教程_第13张图片

6)按照前面的步骤修改Text组件,Text.md参考:

Text:
​```js

​```
RichText:
​```js

​```

7)启动 Styleguidist server:

npm run styleguide
# 运行成功后如下
You can now view your style guide in the browser:

  Local:            http://localhost:6060/
  On your network:  http://10.2.20.118:6060/

成功后截图:

AEM集成SPA(二)集成React完整教程_第14张图片

大功告成,下一章将会讲述有关导航栏和Router相关的知识,十分重要!

5.5 Navigation and Routing

https://helpx.adobe.com/experience-manager/kt/sites/using/getting-started-spa-wknd-tutorial-develop/react/chapter-3.html

5.5.1 说明

这一章是目前官方的最后一篇,主要介绍了AEM SPA中路由概念和使用方式。

新技术点:

  • React Router
  • Font Awesome Icons

主要内容:

  • AEM SPA中的路由介绍和简要实现原理
  • 安装React Router
  • 文章列表组件(导航文章)
  • 完善Header组件(添加了路由功能,导航回首页的button)
  • 使用Font Awesome Icons(图标工具)
  • React中重定向的使用

示例代码下载地址

5.5.2 SPA的路由方式

在AEM SPA Editor中使用Navigation(导航栏)的最佳方式就是将不同的SPA页面视图和AEM的特定页面做映射。这种方式使得管理应用程序的多个模块变得简单,并且能够让内容制作者(content author)编辑独立的页面视图。更多有关路由的介绍,可移步 [4.11 SPA Model Routing](#4.11 SPA Model Routing)

每个AEM的Page表示在SPA框架(React)中,都会被 标签包裹,标签中还需要AEM Page的路径,如下面伪代码描述的:

// React JSX 伪代码,路由示例
render(){
    return (
        
            
                
                     
                
                
                     
                
                
                     
                
            
        
    );
}

在第一章中我们已经讨论过了,React App是通过AEM的JSON Model驱动的。JSON Model通过一个叫 HierarchyPage 的Sling Model,将多个AEM Pages的内容(content)包含在了一个请求中。这种方式允许React App在初始化页面时,直接将几乎所有的数据内容加载,并且在用户后续的浏览中,应当最小化服务端(server-side)的子请求。有关 HierarchyPage的介绍和实现 可参考前文 [5.3.5](#5.3.5 HierarchyPage Sling Model) 。

以下假代码是一段AEM导出的JSON示例,注意这个JSON结构和JSX中的结构能十分完整的映射:

{
    ":type": "wknd-events/components/structure/app",
    ":itemsOrder": [],
    ":items": {},
    ":hierarchyType": "page",
    ":path": "/content/wknd-events/react",
    ":children": {
        "/content/wknd-events/react/home": {},
        "/content/wknd-events/react/home/first-article": {},
        "/content/wknd-events/react/home/second-article": {}
        },
    "title": "React App"
}

5.5.3 安装React Router

React Router 为React框架提供了一系列的导航组件,提供了对页面视图的管理功能。React Router分为三个子模块:

  • react-router
  • react-router-dom
  • react-router-native

示例项目中,由于需要发布到Web平台,因此将使用 react-router-dom ,更多信息请参考: React Router for the Web

1)安装 react-router 和 react-router-dom,在react-app工程下打开命令行:

# 进入react-app
cd react-app
# 安装react-router
npm install react-router --save
# 安装react-router-dom
npm install react-router-dom

2)在react-app下创建 utils 工具类文件夹,然后添加工具类 RouteHelper.js ,目录结构如下:

/react-app
	/src
		/utils
			RouteHelper.js

RoutHelper.js(力所能及的注释了)

/**
 * Helper that facilitate the use of the {@link Route} component
 * 对 {@link Route} 组件的改进工具类
 */
import React, {Component} from 'react';
import {Route} from 'react-router-dom';
import { withRouter } from 'react-router';

/**
 * Returns a composite component where a {@link Route} component wraps the provided component
 * 将返回(传入组件)经由 {@link Route} 组件装饰后的组件
 *
 * @param {React.Component} WrappedComponent    - React component to be wrapped;需要被装饰的React组件
 * @param {string} [extension=html]             - extension used to identify a route amongst the tree of resource URLs;为路径添加后缀(默认为.html)
 * @returns {CompositeRoute}
 */
export const withRoute = (WrappedComponent, extension) => {
    return class CompositeRoute extends Component {
        render() {
            //获取传入组件的cqPath属性值
            let routePath = this.props.cqPath;
            //当为空时默认返回原组件,还会携带上包装器的相关属性
            if (!routePath) {
                return <WrappedComponent {...this.props}/>;
            }
            //判断路径后缀,设置默认值
            extension = extension || 'html';
            // 最终的路径组成: Context path + route path + extension
            return <Route key={ routePath }
                          path={ '(.*)' + routePath + '.' + extension }
                          render={//绑定了一个渲染函数,好像用了React的向上提升?具体有点忘了
                            (routeProps) => {
                                return <WrappedComponent {...this.props} {...routeProps}/>;
                            }
                          }/>
        }
    }
};

/**
 * ScrollToTop component will scroll the window on every navigation.
 * wrapped in in `withRouter` to have access to router's props.
 * 此组件主要作用是:在每次点击导航栏按钮后将页面滚动至顶部
 * 这个组件将被withRouter装饰(注意,不是自定义的withRoute,它来自react-router库),能够访问路由的属性
 */
class ScrollToTop extends Component {
    //React生命周期函数,在组件更新时触发
    componentDidUpdate(prevProps) {
        //当location地址发生变化时
        if (this.props.location !== prevProps.location) {
            window.scrollTo(0, 0)
        }
    }
    render() {
        return this.props.children
    }
}
export default withRouter(ScrollToTop);

说明: withRoute(第一个组件包装方法)是可复用的组件,能包装任何React组件。这里主要将用于包装Page组件以提供页面路由功能。

程序中的Header组件是一个固定组件,当我们导航到不同页面时,都希望将页面滚动到顶部,上面的ScrollToTop组件提供了这个功能,更详细的信息可以参考: scroll restoration and React Router

3)更新 react-app/src/index.js ,主要将 App 组件用 BrowserRouter 和 ScrollToTop 装饰:

...
+ import {BrowserRouter} from 'react-router-dom';
+ import ScrollToTop from './utils/RouteHelper';

...
function render(model) {
    ReactDOM.render(
        (
+            <BrowserRouter>
+                <ScrollToTop>
                    <App cqChildren={ model[Constants.CHILDREN_PROP] }
                         cqItems={ model[Constants.ITEMS_PROP] }
                         cqItemsOrder={ model[Constants.ITEMS_ORDER_PROP] }
                         cqPath={ ModelManager.rootPath }
                         locationPathname={ window.location.pathname }/>
+                </ScrollToTop>
+            </BrowserRouter>
        ),
        document.getElementById('root')
    );
}
...

说明: BrowserRouter 是由react-router-dom提供的,通过HTML5的history API同步App UI界面和URL,这样可以轻松的深度链接到程序的特定页面视图。

4)更新 Page组件react-app/src/components/page/Page.js ,使用 RouteHelper 中的自定义包装器 withRoute 包装

...
+ import {withRoute} from '../../utils/RouteHelper';

...
class WkndPage extends Page {
...
}

- //MapTo('wknd-events/components/structure/page')(withComponentMappingContext(WkndPage));
+ MapTo('wknd-events/components/structure/page')(withComponentMappingContext(withRoute(WkndPage)));

概括说明: AEM的Resource wknd-events/components/structure/page 表示一个AEM Page对象,它将被SPA Editor映射成React组件 WkndPage 。通过 withRoute 包装器将所有page包装成 Route ,从而能被导航。

5.5.4 List Component

这一小节将实现一个List React组件,它能够显示链接列表。与此List React组件映射的AEM组件( AEM List component )来自AEM Core Components。

List组件的JSON模型示例如下:

"list": {
    "dateFormatString": "yyyy-MM-dd",
    "items": [
        {
            "url": "/content/wknd-events/react/home/first-article.html",
            "path": "/content/wknd-events/react/home/first-article",
            "description": null,
            "title": "First Article",
            "lastModified": 1539529744910 //时间戳
        },
        {
            "url": "/content/wknd-events/react/home/second-article.html",
            "path": "/content/wknd-events/react/home/second-article",
            "description": null,
            "title": "Second Article",
            "lastModified": 1539532397436
        }
    ],
    "showDescription": false,
    "showModificationDate": false,
    "linkItems": false,
    ":type": "wknd-events/components/content/list"
}

1)创建 List 组件,在 react-app/src/components 下创建如下目录和文件:

/react-app
	/src
		/components
			/list
				List.js
				List.scss

2)编写 List.js (力所能及的注释了)

import React, {Component} from 'react';
import {MapTo} from '@adobe/cq-react-editable-components';
import {Link} from "react-router-dom";
import './List.scss';

/**
 * 1 编写EditConfig,作为占位符(placeholder),并给出组件为空时的字符串显示
 * @type {{isEmpty: (function(*=): boolean), emptyLabel: string}}
 */
const ListEditConfig = {

    emptyLabel: 'List',

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

/**
 * 2 编写ListItem组件,用于渲染li和link,将作为List组件的模块
 * ListItem renders the individual items in the list
 * ListItem组件需要传递以下属性:
 * - title
 * - url
 * - path
 * - date
 * 注意:{@link Link} 组件来自react-router-dom,不是标准的锚标记,标签的显示与传统很像\n
 * 但是标签是通过React Router进行导航的,它不会刷新页面
 */
class ListItem extends Component {

    get date() {
        if (!this.props.date) {
            return null;
        }
        let date = new Date(this.props.date);
        //这里时区我改成了中文,参考 https://juejin.im/post/5ac7079f5188255c637b3233 原先是:en-US
        return date.toLocaleDateString('zh');
    }

    render() {
        if (!this.props.path || !this.props.title || !this.props.url) {
            return null;
        }
        return (
            <li className="ListItem" key={this.props.path}>
                <Link className="ListItem-link" to={this.props.url}>{this.props.title}
                    <span className="ListItem-date">{this.date}</span>
                </Link>
            </li>
        );
    }
}

/**
 * 3 编写List组件,在里面通过遍历集合数据,并将属性传递给ListItem组件渲染
 * 此组件需要一个array集合数据:items,将从JSON Model中获取
 * export dafault作为默认组件导出,主要用于styleguide
 * 最后需要映射AEM组件:wknd-events/components/content/list
 * List renders the list contents and maps wknd-events/components/content/list
 */
export default class List extends Component {
    render() {
        return (
            <div className="List">
                <ul className="List-wrapper">
                    {this.props.items && this.props.items.map((listItem, index) => {
                        return <ListItem path={listItem.path} url={listItem.url}
                                         title={listItem.title} date={listItem.lastModified}/>
                    })
                    }
                </ul>
            </div>
        );
    }
}
MapTo("wknd-events/components/content/list")(List, ListEditConfig);

3)编写 List.scss

@import '../../styles/shared';

.List {
  @include component-padding();
}

.ListItem {
  list-style: none;
  float: left;
  width: 100%;
  margin-bottom: 1em;
  font-size: $lead-font-size;
  padding: 4px;
  color: #0045ff;

  &:hover {
    background-color: #ededed;
  }

  &-link {
    text-decoration: none;
  }

  &-date {
    width: 100%;
    float: left;
    color: $color-secondary;
    font-size: $base-font-size;
  }
}

4)编写Styleguidist的markdown文档,创建 react-app/src/components/list/List.md ,在这个文档中我们为List组件模拟了数据:

**说明:**由于使用了react-router的 标签,我们需要模拟 来装饰List组件。

List Component:
 
​```js
const {Route} = require('react-router-dom');
const {BrowserRouter} = require('react-router-dom');
let items = [
    {
        url: "#",
        path: "item1",
        title: "First Article",
        lastModified: 1539529744910
    },
    {
        url: "#",
        path: "item2",
        title: "Second Article",
        lastModified: 1539532397436
    }
    ];
    
        
            
        
    
     
​```

5)运行styleguide服务测试:

npm run styleguide

遇到问题:List Component不显示 ,经排查,最终发现是 组件的使用问题。React文档

//原先是这样的,注意中path的属性,找不到,因此不渲染
    
        
            
        
    
//测试使用“#”也不行,使用“/”可以

成功后的效果图:

AEM集成SPA(二)集成React完整教程_第15张图片

6)将 List 组件注册到 react-app/src/components/MappedComponents.js

require('./page/Page');
require('./text/Text');
require('./image/Image');
+ require('./list/List');

7)编译react-app项目,然后安装部署AEM

8)打开 AEM Sites Console ,在 /content/wknd-events/react/home 下创建两个子页面: First ArticleSecond Article (first-article 和 second-article),使用 WKND Event Page template

AEM集成SPA(二)集成React完整教程_第16张图片

9)打开 http://localhost:4502/editor.html/content/wknd-events/react/home.html 页面,添加List Component,配置如下内容:

AEM集成SPA(二)集成React完整教程_第17张图片

10)在Preview视图下测试跳转链接,此时你应该能够跳转进子页面,子页面里的组件也是能在Editor模式下编辑的。

接着访问非Editor环境: http://localhost:4502/content/wknd-events/react/home.html

尝试点击导航列表,可以发现页面不会刷新,浏览器URL将被更新,浏览器的退后按钮也能工作。在导航时,可以通过审查network发现除了页面第一次初始化加载之后不会有任何的请求流量。

目前我们还没有办法从子页面返回Home页(不通过浏览器的后退按钮),下一小结将对Header组件添加一个动态的返回按钮。

5.5.5 更新Header组件

这一小节将为Header组件添加一个后退按钮,和前面的List组件类似,这里也将使用React Router提供的组件实现。

1)更新 react-app/src/components/header/Header.js ,完整代码如下,具体内容见注释:

// src/components/header/Header.js

import React, {Component} from 'react';
import './Header.scss';
/**
 * 1.0 react router依赖
 */
+ import {Link} from "react-router-dom";
+ import {withRouter} from 'react-router';

/**
 * 2.0 移除export default,原先代码:export default class Header extends Component {...}
 * 2.1 添加新的getter方法:homeLink(),这个方法中将会根据location URL判断当前route是否是HomePage
 *     如果不是HomePage,将会生成一个返回HomePage后退Link
 * 2.2 更新render()函数,添加方法调用homeLink
 * 2.3 最后在js最底部export出由withRouter函数装饰后的Header组件,确保Header组件能够访问location的props
 */
+ class Header extends Component {

+    get homeLink() {
        let currLocation;
        currLocation = this.props.location.pathname;
        currLocation = currLocation.substr(0, currLocation.length - 5);

        if (this.props.navigationRoot && currLocation !== this.props.navigationRoot) {
            return (<Link className="Header-action" to={this.props.navigationRoot + ".html"}>
                Back
            </Link>);
        }
        return null;
    }

    render() {
        return (
            <header className="Header">
                <div className="Header-wrapper">
                    <h1 className="Header-title">WKND<span className="Header-title--inverse">_</span></h1>
+                    <div className="Header-tools">
+                        {this.homeLink}
+                    </div>
                </div>
            </header>
        );
    }
}
+ export default withRouter(Header);

2)修改 react-app/src/App.js ,为Header组件传递navigationRoot属性:

return (
    <div className="App">
-        <Header/> {/*添加Header组件*/}
+		 <Header navigationRoot="/content/wknd-events/react/home"/>
        ...
        {this.childComponents}
        {this.childPages}
    </div>
);

3)确保环境变量文件 react-app/.env.development 中Model获取方式是通过代理:

# Configure Proxy end point, Request the JSON from AEM, 定义了Page Model的JSON数据源地址
REACT_APP_PAGE_MODEL_PATH=/content/wknd-events/react.model.json

4)重启 react-app 工程:npm start ,确保启动并登录了AEM Server,然后访问测试:

http://localhost:3000/content/wknd-events/react/home.html

此时你点击List组件,跳转到子页面后将会在Header组件上自动生成一个back按钮,如图:

AEM集成SPA(二)集成React完整教程_第18张图片

下面将会为这个Back按钮添加一些样式

5.5.6 添加Font Awesome图标

Font Awesome 是一款流行的icon合集,它为React提供了一套 官方的组件 ,可以十分简单方便地集成进React应用,示例项目中也将引入一小部分icons。

1)安装Font Awesome,官方介绍文档: Font Awesome

# 在react-app工程下打开终端
cd <src>/aem-guides-wknd-events/react-app
# 安装Font Awesome
npm install @fortawesome/fontawesome-svg-core --save
npm install @fortawesome/free-solid-svg-icons --save
npm i @fortawesome/react-fontawesome --save

2)编写 Icons.js 工具类:react-app/src/utils/Icons.js ,添加一些需要使用到的Icons:

import { library } from '@fortawesome/fontawesome-svg-core';
import { faCheckSquare, faChevronLeft, faSearch, faHeadphonesAlt, faMusic, faCamera, faFutbol, faPaintBrush, faTheaterMasks} from '@fortawesome/free-solid-svg-icons';

library.add(faCheckSquare, faChevronLeft, faSearch, faHeadphonesAlt, faMusic, faCamera, faFutbol, faPaintBrush, faTheaterMasks);

3)修改 react-app/src/components/header/Header.js 组件,添加 ”chevron-left“ icon:

+ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+ require('../../utils/Icons');//顺序一定要在import后

...
class Header extends Component {

    get homeLink() {
...
        if (this.props.navigationRoot && currLocation !== this.props.navigationRoot) {
            return (<Link className="Header-action" to={this.props.navigationRoot + ".html"}>
-                Back
+                <FontAwesomeIcon icon="chevron-left" />
            </Link>);
        }
        return null;
    }
...
}

4)修改 react-app/src/components/header/Header.scss ,添加样式(下列全部):

@import '../../styles/shared';

$icon-size-lg: 46px;
$icon-size-md: 40px;
$icon-size-sm: 32px;

.Header {
 ...
  &-tools {
    padding-top: 8px;
    padding-right: $gutter-padding;
  }

  &-action {
    background: $color-white;
    border-radius: 100%;
    width: $icon-size-sm;
    height: $icon-size-sm;
    font-size: 18px;
    color: $color-black;
    text-align: center;
    align-content: center;
    float: left;
    margin-right: 1.5rem;

    &:last-child {
      margin-right: 0;
    }

    .svg-inline--fa {
      position: relative;
      top: 2.5px;
      right: 1px;
    }

    @include media(desktop) {
      width: $icon-size-lg;
      height: $icon-size-lg;
      font-size: 26px;
    }

    @include media(tablet) {
      width: $icon-size-md;
      height: $icon-size-md;
      font-size: 22px;
    }
  }
}

5)重启 react-app ,测试,此时Back按钮应该成为了图标:

AEM集成SPA(二)集成React完整教程_第19张图片

5.5.7 重定向到首页

这是本章的最后一小节,这里将更新 index.js ,也就是应用的入口JS文件。通过添加 Redirect 组件(提供自react-router),实现访问 react.html 页面时自动重定向到 home.html

1)更新 react-app/src/index.js ,导入react-router的 Redirect he Route组件:

import { Redirect, Route } from 'react-router';

2)更新render函数,添加重定向规则(从react.html -> home.html):

function render(model) {
    ReactDOM.render(
        (
            <BrowserRouter>
                <ScrollToTop>
+                    <Route path="/content/wknd-events/react.html" render={() => (
+                        <Redirect to="/content/wknd-events/react/home.html"/>
+                    )}/>
                    <App cqChildren={model[Constants.CHILDREN_PROP]}
                         cqItems={model[Constants.ITEMS_PROP]}
                         cqItemsOrder={model[Constants.ITEMS_ORDER_PROP]}
                         cqPath={ModelManager.rootPath}
                         locationPathname={window.location.pathname}/>
                </ScrollToTop>
            </BrowserRouter>
        ),
        document.getElementById('root')
    );
}

3)重启 react-app ,访问:http://localhost:3000/content/wknd-events/react.html ,此时将会自动重定向到 home.html

4)将项目编译部署到AEM Server,测试访问:http://localhost:4502/editor.html/content/wknd-events/react.html

  1. 此时你能够导航到List组件中的子页面,Header组件的back按钮也将正常显示样式
  2. 注意在AEM Editor模式下,浏览器的url不能够正确反射回来,需要在非Editor下测试访问:http://localhost:4502/content/wknd-events/react.html ,可以看到重定向和HTML5的History API都能够正常工作了

你可能感兴趣的:(AEM技术分享)