文档AEMAEM 教程AEM Headless 教程

创建自定义组件 custom-component

Last update: Sun Jul 14 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，并将textifeld的值保留到名为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”(纯旧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