文件AEMAEM 教學課程AEM Headless 教學課程

整合SPA developer-workflow

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • 初學者
  • 開發人員

瞭解如何將在React中撰寫的單頁應用程式(SPA)原始程式碼與Adobe Experience Manager (AEM)專案整合。 瞭解如何使用現代前端工具（如Webpack開發伺服器），以針對SPA JSON模型API快速開發AEM。

目標

  1. 瞭解SPA專案如何與AEM和使用者端程式庫整合。
  2. 瞭解如何使用Webpack開發伺服器來進行專屬的前端開發。
  3. 探索使用​ proxy ​和靜態​ Mock ​檔案來針對AEM JSON模型API進行開發。

您將建置的內容

在本章中，您將會對SPA進行幾項細微的變更，以瞭解其如何與AEM整合。
本章會將簡單的Header元件新增至SPA。 在建置此​ 靜態 Header元件的過程中，使用了數種AEM SPA開發方法。

在AEM 中新增標題

SPA已擴充以新增靜態Header元件

先決條件

檢閱設定本機開發環境所需的工具和指示。 本章是建立專案章節的延續，但是您只要遵循啟用SPA的有效AEM專案，就可以了。

整合方法 integration-approach

已建立兩個模組作為AEM專案的一部分： ui.apps和ui.frontend。

ui.frontend模組是包含所有SPA原始程式碼的webpack專案。 大部分的SPA開發和測試都是在webpack專案中完成的。 觸發生產組建時，會使用webpack建置及編譯SPA。 編譯的成品（CSS和Javascript）會複製到ui.apps模組，然後部署到AEM執行階段。

ui.frontend高階架構

SPA整合的高階描述。

有關前端組建的其他資訊可在此處找到。

Inspect與SPA整合 inspect-spa-integration

接下來，檢查ui.frontend模組以瞭解AEM專案原型已自動產生的SPA。

  1. 在您選擇的IDE中，開啟您的AEM專案。 此教學課程將使用Visual Studio Code IDE。

    VSCode - AEM WKND SPA專案

  2. 展開並檢查ui.frontend資料夾。 開啟檔案ui.frontend/package.json

  3. 在dependencies底下，您應該會看到數個與react相關的專案，包括react-scripts

    ui.frontend是以建立React應用程式或CRA為基礎的React應用程式。 react-scripts版本指出使用的CRA版本。

  4. 也有數個前置詞為@adobe的相依性：

    code language-json 
    "@adobe/aem-react-editable-components": "~1.1.2",
"@adobe/aem-spa-component-mapping": "~1.1.0",
"@adobe/aem-spa-page-model-manager": "~1.3.3",
"@adobe/aem-core-components-react-base": "1.1.8",
"@adobe/aem-core-components-react-spa": "1.1.7",

    上述模組構成AEM SPA Editor JS SDK，並提供可將SPA元件對應到AEM元件的功能。

    此外也包含AEM WCM元件 — React Core實作和AEM WCM元件 — Spa編輯器 — React Core實作。 這是一組可重複使用的UI元件，對應至現成可用的AEM元件。 這些模組的設計用途與樣式皆符合您專案的需求。

  5. 在package.json檔案中，有數個scripts已定義：

    code language-json 
    "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build && clientlib",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
}

    這些是標準組建指令碼，由Create React應用程式讓可用。

    唯一的差異是將&& clientlib加到build指令碼中。 這個額外的指令負責在建置期間將編譯的SPA作為使用者端程式庫複製到ui.apps模組中。

    npm模組aem-clientlib-generator已用來協助處理這個問題。

  6. Inspect檔案ui.frontend/clientlib.config.js。 aem-clientlib-generator使用此設定檔來決定如何產生使用者端程式庫。

  7. Inspect檔案ui.frontend/pom.xml。 此檔案會將ui.frontend資料夾轉換為Maven模組。 pom.xml檔案已更新，以便在Maven組建期間使用frontend-maven-plugin至​ test ​和​ build SPA。

  8. 在ui.frontend/src/index.jsInspect檔案index.js：

    code language-js 
    //ui.frontend/src/index.js
...
document.addEventListener('DOMContentLoaded', () => {
    ModelManager.initialize().then(pageModel => {
        const history = createBrowserHistory();
        render(
        <Router history={history}>
            <App
            history={history}
            cqChildren={pageModel[Constants.CHILDREN_PROP]}
            cqItems={pageModel[Constants.ITEMS_PROP]}
            cqItemsOrder={pageModel[Constants.ITEMS_ORDER_PROP]}
            cqPath={pageModel[Constants.PATH_PROP]}
            locationPathname={window.location.pathname}
            />
        </Router>,
        document.getElementById('spa-root')
        );
    });
});

    index.js是SPA的進入點。 ModelManager由AEM SPA編輯器JS SDK提供。 它負責呼叫pageModel （JSON內容）並將其插入應用程式。

  9. 在ui.frontend/src/components/import-components.jsInspect檔案import-components.js。 此檔案會匯入現成可用的​ React Core Components，並讓它們可用於專案。 我們將在下一章中檢查AEM內容與SPA元件的對應。

新增靜態SPA元件 static-spa-component

接下來，將新元件新增至SPA，並將變更部署至本機AEM執行個體。 這是一個簡單的變更，只是為了說明SPA如何更新。

  1. 在ui.frontend模組的ui.frontend/src/components下建立名為Header的新資料夾。

  2. 在Header資料夾下建立名為Header.js的檔案。

    標頭資料夾和檔案

  3. 以下列專案填入Header.js：

    code language-js 
    //Header.js
import React, {Component} from 'react';

export default class Header extends Component {

    render() {
        return (
                <header className="Header">
                    <div className="Header-container">
                        <h1>WKND</h1>
                    </div>
                </header>
        );
    }
}

    以上是將輸出靜態文字字串的標準React元件。

  4. 開啟檔案ui.frontend/src/App.js。 這是應用程式進入點。

  5. 對App.js進行下列更新以包含靜態Header：

    code language-diff 
      import { Page, withModel } from '@adobe/aem-react-editable-components';
  import React from 'react';
+ import Header from './components/Header/Header';

  // This component is the application entry point
  class App extends Page {
  render() {
      return (
      <div>
+       <Header />
         {this.childComponents}
         {this.childPages}
     </div>

  6. 開啟新的終端機，並導覽至ui.frontend資料夾並執行npm run build命令：

    code language-shell 
    $ cd aem-guides-wknd-spa
$ cd ui.frontend
$ npm run build
...
Compiled successfully.

File sizes after gzip:

118.95 KB (-33 B)  build/static/js/2.489f399a.chunk.js
1.11 KB (+48 B)    build/static/js/main.6cfa5095.chunk.js
806 B              build/static/js/runtime-main.42b998df.js
451 B              build/static/css/main.e57bbe8a.chunk.css

  7. 導覽至ui.apps資料夾。 在ui.apps/src/main/content/jcr_root/apps/wknd-spa-react/clientlibs/clientlib-react下方，您應該會看到編譯的SPA檔案是從ui.frontend/build資料夾中複製的。

    在ui.apps中產生的使用者端資料庫

  8. 返回終端機並導覽至ui.apps資料夾。 執行下列Maven命令：

    code language-shell 
    $ cd ../ui.apps
$ mvn clean install -PautoInstallPackage
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  9.629 s
[INFO] Finished at: 2020-05-04T17:48:07-07:00
[INFO] ------------------------------------------------------------------------

    這會將ui.apps封裝部署至AEM的本機執行個體。

  9. 開啟瀏覽器索引標籤並導覽至http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html。 您現在應該會看到Header元件的內容顯示在SPA中。

    初始標頭實作

    從專案的根目錄（即mvn clean install -PautoInstallSinglePackage）觸發Maven組建時，會自動執行上述步驟。 您現在應該瞭解SPA與AEM使用者端程式庫之間整合的基本概念。 請注意，您仍然可以在AEM中的靜態Header元件下方編輯和新增Text元件。

Webpack Dev Server - JSON API的Proxy proxy-json

如先前練習所示，執行組建並將使用者端程式庫同步至AEM的本機執行個體需要幾分鐘的時間。 這對於最終測試來說是可接受的，但對於大多數SPA開發而言並不理想。

webpack-dev-server可用來快速開發SPA。 SPA是由AEM產生的JSON模型驅動。 在本練習中，來自執行中AEM執行個體的JSON內容是​ 已代理 ​至開發伺服器。

  1. 返回IDE並開啟檔案ui.frontend/package.json。

    尋找類似以下的一行：

    code language-json 
    "proxy": "http://localhost:4502",

    建立React應用程式提供簡易的機制來代理API要求。 所有未知的請求都是透過本機AEM快速入門localhost:4502進行代理處理。

  2. 開啟終端機視窗並導覽至ui.frontend資料夾。 執行命令npm start：

    code language-shell 
    $ cd ui.frontend
$ npm start
...
Compiled successfully!

You can now view wknd-spa-react in the browser.

Local:            http://localhost:3000
On Your Network:  http://192.168.86.136:3000

Note that the development build is not optimized.
To create a production build, use npm run build.

  3. 開啟新的瀏覽器索引標籤（如果尚未開啟），並導覽至http://localhost:3000/content/wknd-spa-react/us/en/home.html。

    Webpack開發伺服器 — Proxy json

    您應該會看到與AEM相同的內容，但未啟用任何撰寫功能。

    note note
    NOTE
    由於AEM的安全性需求，您將需要在相同瀏覽器中但在不同索引標籤中登入本機AEM執行個體(http://localhost:4502)。

  4. 返回IDE並在src/components/Header資料夾中建立名為Header.css的檔案。

  5. 以下列專案填入Header.css：

    code language-css 
    .Header {
    background-color: #FFEA00;
    width: 100%;
    position: fixed;
    top: 0;
    left: 0;
    z-index: 99;
    box-shadow: 0px 0px 10px 0px rgba(0, 0, 0, 0.24);
}

.Header-container {
    display: flex;
    max-width: 1024px;
    margin: 0 auto;
    padding: 12px;
}

.Header-container h1 {
    letter-spacing: 0;
    font-size: 48px;
}

    VSCode IDE

  6. 重新開啟Header.js，並將下列行加入參考Header.css：

    code language-diff 
      //Header.js
  import React, {Component} from 'react';
+ require('./Header.css');

    儲存變更。

  7. 導覽至http://localhost:3000/content/wknd-spa-react/us/en/home.html，檢視樣式變更會自動反映出來。

  8. 在ui.frontend/src/components/Page開啟檔案Page.css。 進行下列變更以修正邊框間距：

    code language-css 
    .page {
  max-width: 1024px;
  margin: 0 auto;
  padding: 12px;
  padding-top: 50px;
}

  9. 在http://localhost:3000/content/wknd-spa-react/us/en/home.html返回瀏覽器。 您應該會立即看到應用程式的變更反映出來。

    樣式已新增至標頭

    您可以繼續在AEM中進行內容更新，並看到這些更新反映在​ webpack-dev-server ​中，因為我們正在代理內容。

  10. 停止終端機中具有ctrl+c的webpack開發伺服器。

將SPA更新部署至AEM

對Header所做的變更目前只能透過​ webpack-dev-server ​顯示。 將更新的SPA部署到AEM以檢視變更。

  1. 導覽至專案的根目錄(aem-guides-wknd-spa)，並使用Maven將專案部署至AEM：

    code language-shell 
    $ cd ..
$ mvn clean install -PautoInstallSinglePackage

  2. 導覽至http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html。 您應該會看到已套用的更新Header和樣式。

    已在AEM中更新標題

    現在AEM已更新SPA，製作作業可以繼續進行。

恭喜！ congratulations

恭喜，您已更新SPA並探索與AEM整合！ 您現在知道如何使用​ webpack-dev-server ​針對AEM JSON模型API開發SPA。

後續步驟 next-steps

將SPA元件對應至AEM元件 — 瞭解如何使用AEM SPA編輯器JS SDK將React元件對應至Adobe Experience Manager (AEM)元件。 元件對應可讓使用者在SPA SPA編輯器中對AEM元件進行動態更新，類似於傳統的AEM編寫。

（額外優惠） Webpack Dev Server - Mock JSON API mock-json

快速開發的另一種方法是使用靜態JSON檔案充當JSON模型。 透過「嘲弄」 JSON，我們移除對本機AEM例項的相依性。 它也能讓前端開發人員更新JSON模型，以測試功能並推動JSON API的變更，之後再由後端開發人員實作。

模擬JSON的初始設定​ 需要本機AEM執行個體。

  1. 返回IDE並導覽至ui.frontend/public並新增名稱為mock-content的新資料夾。

  2. 在ui.frontend/public/mock-content下建立名為mock.model.json的新檔案。

  3. 在瀏覽器中導覽至http://localhost:4502/content/wknd-spa-react/us/en.model.json。

    這是由AEM匯出並驅動應用程式的JSON。 複製JSON輸出。

  4. 將上一步的JSON輸出貼到檔案mock.model.json中。

    模擬模型Json檔案

  5. 在ui.frontend/public/index.html開啟檔案index.html。 更新AEM頁面模型的中繼資料屬性，以指向變數%REACT_APP_PAGE_MODEL_PATH%：

    code language-html 
        <!-- AEM page model -->
    <meta
       property="cq:pagemodel_root_url"
       content="%REACT_APP_PAGE_MODEL_PATH%"
    />

    使用變數做為cq:pagemodel_root_url的值可讓您更輕鬆地在Proxy和模擬json模型之間切換。

  6. 開啟檔案ui.frontend/.env.development並進行下列更新，以註解REACT_APP_PAGE_MODEL_PATH和REACT_APP_API_HOST的上一個值：

    code language-diff 
    + PUBLIC_URL=/
- PUBLIC_URL=/etc.clientlibs/wknd-spa-react/clientlibs/clientlib-react/resources

- REACT_APP_PAGE_MODEL_PATH=/content/wknd-spa-react/us/en.model.json
+ REACT_APP_PAGE_MODEL_PATH=/mock-content/mock.model.json

- REACT_APP_API_HOST=http://localhost:4502
+ #REACT_APP_API_HOST=http://localhost:4502

REACT_APP_ROOT=/content/wknd-spa-react/us/en/home.html

  7. 如果目前正在執行，請停止​ webpack-dev-server。 從終端機啟動​ webpack-dev-server：

    code language-shell 
    $ cd ui.frontend
$ npm start

    導覽至http://localhost:3000/content/wknd-spa-react/us/en/home.html，您應該會看到內容與​ proxy json中所使用的內容相同的SPA。

  8. 對先前建立的mock.model.json檔案進行小幅變更。 您應該會看到更新後的內容立即反映在​ webpack-dev-server ​中。

    模型的json更新

能夠操控JSON模型並檢視對即時SPA的影響有助於開發人員瞭解JSON模型API。 此外，前端和後端開發均可並行進行。

您現在可以透過切換env.development檔案中的專案來切換使用JSON內容的位置：

# JSON API via proxy to AEM
#REACT_APP_PAGE_MODEL_PATH=/content/wknd-spa-react/us/en.model.json
#REACT_APP_API_HOST=http://localhost:4502

# JSON API via static mock file
REACT_APP_PAGE_MODEL_PATH=/mock-content/mock.model.json
recommendation-more-help
e25b6834-e87f-4ff3-ba56-4cd16cdfdec4