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

建立自訂元件 custom-component

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

建立對象：

  • 初學者
  • 開發人員

瞭解如何建立要與AEM SPA編輯器搭配使用的自訂元件。 瞭解如何開發作者對話方塊和Sling模型，以擴充JSON模型來填入自訂元件。

目標

  1. 瞭解Sling模型在操控AEM提供的JSON模型API方面的作用。
  2. 瞭解如何建立AEM元件對話方塊。
  3. 瞭解如何建立與SPA編輯器架構相容的​ 自訂 AEM元件。

您將建置的內容

前幾章的重點是開發SPA元件，並將它們對應至​ 現有 ​個AEM核心元件。 本章著重於如何建立及擴充​ 新 ​個AEM元件，以及如何操作AEM所提供的JSON模型。

簡單的Custom Component說明建立新的AEM元件所需的步驟。

訊息以全部大寫字顯示

先決條件

檢閱設定本機開發環境所需的工具和指示。

取得程式碼

  1. 透過Git下載本教學課程的起點：

    code language-shell 
    $ git clone git@github.com:adobe/aem-guides-wknd-spa.git
$ cd aem-guides-wknd-spa
$ git checkout Angular/custom-component-start

  2. 使用Maven將程式碼庫部署到本機AEM執行個體：

    code language-shell 
    $ mvn clean install -PautoInstallSinglePackage

    如果使用AEM 6.x，請新增classic設定檔：

    code language-shell 
    $ mvn clean install -PautoInstallSinglePackage -Pclassic

  3. 安裝傳統WKND參考站台的完成套件。 由WKND參考網站提供的影像會在WKND SPA上重複使用。 可以使用AEM封裝管理員來安裝封裝。

    封裝管理員安裝wknd.all

您一律可以在GitHub上檢視完成的程式碼，或切換至分支Angular/custom-component-solution在本機簽出程式碼。

定義AEM元件

AEM元件定義為節點和屬性。 在專案中，這些節點和屬性在ui.apps模組中表示為XML檔案。 接下來，在ui.apps模組中建立AEM元件。

NOTE
有關AEM元件基本概念的快速重新整理可能有所幫助。

  1. 在您選擇的IDE中開啟ui.apps資料夾。

  2. 瀏覽至ui.apps/src/main/content/jcr_root/apps/wknd-spa-angular/components並建立名為custom-component的資料夾。

  3. 在custom-component資料夾下建立名為.content.xml的檔案。 以下列專案填入custom-component/.content.xml：

    code language-xml 
    <?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="cq:Component"
    jcr:title="Custom Component"
    componentGroup="WKND SPA Angular - Content"/>

    建立自訂元件定義

    jcr:primaryType="cq:Component" — 識別此節點是AEM元件。

    jcr:title是顯示給內容作者的值，且componentGroup會決定編寫UI中的元件分組。

  4. 在custom-component資料夾下，建立另一個名為_cq_dialog的資料夾。

  5. 在_cq_dialog資料夾下方建立名為.content.xml的檔案，並填入下列內容：

    code language-xml 
    <?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:granite="http://www.adobe.com/jcr/granite/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
    jcr:primaryType="nt:unstructured"
    jcr:title="Custom Component"
    sling:resourceType="cq/gui/components/authoring/dialog">
    <content
        jcr:primaryType="nt:unstructured"
        sling:resourceType="granite/ui/components/coral/foundation/container">
        <items jcr:primaryType="nt:unstructured">
            <tabs
                jcr:primaryType="nt:unstructured"
                sling:resourceType="granite/ui/components/coral/foundation/tabs"
                maximized="{Boolean}true">
                <items jcr:primaryType="nt:unstructured">
                    <properties
                        jcr:primaryType="nt:unstructured"
                        jcr:title="Properties"
                        sling:resourceType="granite/ui/components/coral/foundation/container"
                        margin="{Boolean}true">
                        <items jcr:primaryType="nt:unstructured">
                            <columns
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns"
                                margin="{Boolean}true">
                                <items jcr:primaryType="nt:unstructured">
                                    <column
                                        jcr:primaryType="nt:unstructured"
                                        sling:resourceType="granite/ui/components/coral/foundation/container">
                                        <items jcr:primaryType="nt:unstructured">
                                            <message
                                                jcr:primaryType="nt:unstructured"
                                                sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                                                fieldDescription="The text to display on the component."
                                                fieldLabel="Message"
                                                name="./message"/>
                                        </items>
                                    </column>
                                </items>
                            </columns>
                        </items>
                    </properties>
                </items>
            </tabs>
        </items>
    </content>
</jcr:root>

    自訂元件定義

    上述XML檔案會為Custom Component產生簡單的對話方塊。 檔案的關鍵部分是內部<message>節點。 此對話方塊包含一個名為Message的簡單textfield，並將文字欄位的值保留到名為message的屬性。

    接著會建立Sling模型，以透過JSON模型公開message屬性的值。

    note note
    NOTE
    您可以檢視核心元件定義🔗，以檢視更多對話方塊範例。 您也可以檢視CRXDE-Lite中/libs/granite/ui/components/coral/foundation/form下方可用的其他表單欄位，例如select、textarea、pathfield。

    使用傳統AEM元件時，通常需要HTL指令碼。 由於SPA會轉譯元件，因此不需要HTL指令碼。

建立Sling模型

Sling模型是註釋驅動的Java™ 「POJO」(Plain Old Java™物件)，可方便將資料從JCR對應至Java™變數。 Sling模型通常可封裝AEM元件的複雜伺服器端商業邏輯。

在SPA編輯器的內容中，Sling模型會使用Sling模型匯出工具，透過功能透過JSON模型公開元件的內容。

  1. 在您選擇的IDE中，開啟core模組。 CustomComponent.java和CustomComponentImpl.java已建立並作為章節起始程式碼的一部分進行存根。

    note note
    NOTE
    如果使用Visual Studio Code IDE，則安裝Java™🔗的擴充功能可能會有幫助。

  2. 在core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/CustomComponent.java開啟Java™介面CustomComponent.java：

    CustomComponent.java介面

    這是由Sling模型實作的Java™介面。

  3. 更新CustomComponent.java以擴充ComponentExporter介面：

    code language-java 
    package com.adobe.aem.guides.wknd.spa.angular.core.models;
import com.adobe.cq.export.json.ComponentExporter;

public interface CustomComponent extends ComponentExporter {

    public String getMessage();

}

    實作ComponentExporter介面需要Sling模型才能由JSON模型API自動擷取。

    CustomComponent介麵包含單一getter方法getMessage()。 此方法會透過JSON模型公開作者對話方塊的值。 JSON模型中只會匯出具有空白引數()的getter方法。

  4. 在core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/impl/CustomComponentImpl.java開啟CustomComponentImpl.java。

    這是CustomComponent介面的實作。 @Model註解將Java™類別識別為Sling模型。 @Exporter註解可透過Sling模型匯出工具序列化及匯出Java™類別。

  5. 更新靜態變數RESOURCE_TYPE以指向在上一個練習中建立的AEM元件wknd-spa-angular/components/custom-component。

    code language-java 
    static final String RESOURCE_TYPE = "wknd-spa-angular/components/custom-component";

    元件的資源型別會將Sling模型繫結至AEM元件，最終對應至Angular元件。

  6. 將getExportedType()方法新增至CustomComponentImpl類別以傳回元件資源型別：

    code language-java 
    @Override
public String getExportedType() {
    return CustomComponentImpl.RESOURCE_TYPE;
}

    實作ComponentExporter介面並公開允許對應至Angular元件的資源型別時，需要此方法。

  7. 更新getMessage()方法以傳回作者對話方塊儲存的message屬性值。 使用@ValueMap註解將JCR值message對應至Java™變數：

    code language-java 
    import org.apache.commons.lang3.StringUtils;
...

@ValueMapValue
private String message;

@Override
public String getMessage() {
    return StringUtils.isNotBlank(message) ? message.toUpperCase() : null;
}

    新增一些額外的「商業邏輯」，以傳回訊息的值為大寫。 這可讓我們檢視製作對話方塊儲存的原始值與Sling模型公開的值之間的差異。

    note note
    NOTE
    您可以在🔗檢視已完成的CustomComponentImpl.java。

更新Angular元件

已建立自訂元件的Angular代碼。 接下來，進行一些更新，以將Angular元件對應到AEM元件。

  1. 在ui.frontend模組中，開啟檔案ui.frontend/src/app/components/custom/custom.component.ts

  2. 觀察@Input() message: string;行。 轉換後的大寫值應對應至此變數。

  3. 從AEM SPA編輯器JS SDK匯入MapTo物件，並使用它來對應到AEM元件：

    code language-diff 
    + import {MapTo} from '@adobe/cq-angular-editable-components';

 ...
 export class CustomComponent implements OnInit {
     ...
 }

+ MapTo('wknd-spa-angular/components/custom-component')(CustomComponent, CustomEditConfig);

  4. 開啟cutom.component.html，並觀察到{{message}}的值顯示在<h2>標籤的一側。

  5. 開啟custom.component.css並新增下列規則：

    code language-css 
    :host-context {
    display: block;
}

    若要在元件為空白時正確顯示AEM編輯器預留位置，:host-context或其他<div>需要設定為display: block;。

  6. 使用您的Maven技能，從專案目錄的根將更新部署到本機AEM環境：

    code language-shell 
    $ cd aem-guides-wknd-spa
$ mvn clean install -PautoInstallSinglePackage

更新範本原則

接下來，瀏覽至AEM以驗證更新，並允許將Custom Component新增至SPA。

  1. 請瀏覽至http://localhost:4502/system/console/status-slingmodels，以驗證新Sling模型的註冊。

    code language-plain 
    com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl - wknd-spa-angular/components/custom-component

com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl exports 'wknd-spa-angular/components/custom-component' with selector 'model' and extension '[Ljava.lang.String;@6fb4a693' with exporter 'jackson'

    您應該會看到以上兩行，指出CustomComponentImpl與wknd-spa-angular/components/custom-component元件相關聯，並已透過Sling模型匯出工具註冊。

  2. 瀏覽至http://localhost:4502/editor.html/conf/wknd-spa-angular/settings/wcm/templates/spa-page-template/structure.html的SPA頁面範本。

  3. 更新配置容器的原則以將新的Custom Component新增為允許的元件：

    更新配置容器原則

    儲存原則的變更，並將Custom Component視為允許的元件：

    自訂元件為允許的元件

編寫自訂元件

接下來，使用AEM SPA編輯器編寫Custom Component。

  1. 導覽至http://localhost:4502/editor.html/content/wknd-spa-angular/us/en/home.html。

  2. 在Edit模式中，將Custom Component新增至Layout Container：

    插入新元件

  3. 開啟元件的對話方塊，然後輸入包含一些小寫字母的訊息。

    設定自訂元件

    這是根據章節中先前的XML檔案建立的對話方塊。

  4. 儲存變更。 請注意，顯示的訊息全部是大寫。

    訊息以全部大寫字顯示

  5. 導覽至http://localhost:4502/content/wknd-spa-angular/us/en.model.json以檢視JSON模型。 搜尋wknd-spa-angular/components/custom-component：

    code language-json 
    "custom_component_208183317": {
    "message": "HELLO WORLD",
    ":type": "wknd-spa-angular/components/custom-component"
}

    請注意，根據Sling模型新增的邏輯，JSON值會設為所有大寫字母。

恭喜！ congratulations

恭喜，您已瞭解如何建立自訂AEM元件，以及Sling模型和對話方塊如何與JSON模型搭配運作。

您一律可以在GitHub上檢視完成的程式碼，或切換至分支Angular/custom-component-solution在本機簽出程式碼。

後續步驟 next-steps

擴充核心元件 — 瞭解如何擴充要與AEM SPA編輯器搭配使用的現有核心元件。 瞭解如何將屬性和內容新增至現有元件，是擴充AEM SPA Editor實作功能的強大技術。

recommendation-more-help
e25b6834-e87f-4ff3-ba56-4cd16cdfdec4