为AEM Screens开发自定义组件 developing-a-custom-component-for-aem-screens

AEM 6.5以及最新的Screens Feature Pack。

AEM Screens播放器

本地开发环境

在CRX包管理器中，验证是否安装了以下两个包：

1. screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip
2. screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip

Screens We.Retail运行通过CRX包管理器安装的Ui.Apps和Ui.Content包。

screens-weretail-run.ui.apps ​包会在/apps/weretail-run下安装代码。

此包中包含用于呈现项目自定义组件的代码。 此包中包含组件代码以及所需的任何JavaScript或CSS。 此包还嵌入了​ screens-weretail-run.core-0.0.1-SNAPSHOT.jar，其中包含项目所需的任何Java™代码。

ui.apps代码的CRXDE Lite表示形式

Hello World ​组件只是一个占位符。 在本教程中，新增了功能，作者可以更新组件显示的消息。

screens-weretail-run.ui.content ​包在下方安装代码：

• /conf/we-retail-run
• /content/dam/we-retail-run
• /content/screens/we-retail-run

此资源包包含项目所需的起始内容和配置结构。 /conf/we-retail-run ​包含We.Retail运行项目的所有配置。 /content/dam/we-retail-run ​包括项目的开始数字资源。 /content/screens/we-retail-run ​包含Screens内容结构。 所有这些路径的内容主要在AEM中更新。 为了提高环境（本地、开发、暂存、生产）之间的一致性，通常将基本内容结构保存在源代码控制中。

导航到AEM Screens > We.Retail运行项目：

从AEM“开始”菜单中，单击Screens图标。 验证是否看到We.Retail运行项目。

在​ CRXDE-Lite ​中，http://localhost:4502/crx/de/index.jsp（或所选的IDE）导航到/apps/weretail-run/components/content/helloworld.

将以下属性添加到helloworld组件：

    jcr:title="Hello World"
    sling:resourceSuperType="foundation/components/parbase"
    componentGroup="We.Retail Run - Content"

/apps/weretail-run/components/content/helloworld

/apps/weretail-run/components/content/helloworld的属性

Hello World ​组件扩展了​ foundation，组件，parbase ​组件，以便可以在序列通道中正确使用它。

在/apps/weretail-run/components/content/helloworld下创建名为helloworld.html.的文件

使用以下内容填充文件：

<!--/*

 /apps/weretail-run/components/content/helloworld/helloworld.html

*/-->

<!--/* production: preview authoring mode + unspecified mode (i.e. on publish) */-->
<sly data-sly-test.production="${wcmmode.preview || wcmmode.disabled}" data-sly-include="production.html" />

<!--/* edit: any other authoring mode, i.e. edit, design, scaffolding, etc. */-->
<sly data-sly-test="${!production}" data-sly-include="edit.html" />

根据正在使用的创作模式，Screens组件需要两种不同的渲染：

1. 生产：预览或Publish模式(wcmmode=disabled)
2. 编辑：用于所有其他创作模式，即编辑、设计、基架、开发人员……

helloworld.html充当开关，检查哪个创作模式处于活动状态并重定向到另一个HTL脚本。 Screens组件使用的常见约定是，对于编辑模式，具有edit.html脚本；对于生产模式，具有production.html脚本。

在/apps/weretail-run/components/content/helloworld下创建名为production.html.的文件

使用以下内容填充文件：

<!--/*
 /apps/weretail-run/components/content/helloworld/production.html

*/-->

<div data-duration="${properties.duration}" class="cmp-hello-world">
 <h1 class="cmp-hello-world__message">${properties.message}</h1>
</div>

以上是Hello World组件的生产标记。 由于该组件在序列渠道中被使用，因此包含data-duration特性。 序列渠道使用data-duration属性来了解序列项显示的时长。

该组件呈现带有文本的div和h1标记。 ${properties.message}是HTL脚本的一部分，该脚本输出名为message的JCR属性的内容。 稍后将创建一个对话框，允许用户输入message属性文本的值。

另请注意，组件使用BEM（块元素修饰符）表示法。 BEM是一种CSS编码约定，它使创建可重用组件变得更容易。 BEM是AEM核心组件使用的表示法。

在/apps/weretail-run/components/content/helloworld下创建名为edit.html.的文件

使用以下内容填充文件：

<!--/*

 /apps/weretail-run/components/content/helloworld/edit.html

*/-->

<!--/* if message populated */-->
<div
 data-sly-test.message="${properties.message}"
 class="aem-Screens-editWrapper cmp-hello-world">
 <p class="cmp-hello-world__message">${message}</p>
</div>

<!--/* empty place holder */-->
<div data-sly-test="${!message}"
     class="aem-Screens-editWrapper cq-placeholder cmp-hello-world"
     data-emptytext="${'Hello World' @ i18n, locale=request.locale}">
</div>

以上是Hello World组件的已编辑标记。 如果填充了对话框消息，则第一个块会显示组件的已编辑版本。

如果没有输入对话框消息，则会呈现第二个块。 在这种情况下，cq-placeholder和data-emptytext将标签​ Hello World ​呈现为占位符。 可以使用i18n国际化标签的字符串，以支持在多个区域设置中进行创作。

复制Screens图像对话框以用于Hello World组件。

最简单的方法是从现有对话框开始，然后进行修改。

1. 从以下位置复制对话框： /libs/screens/core/components/content/image/cq:dialog
2. 将对话框粘贴到/apps/weretail-run/components/content/helloworld下方

更新Hello World对话框以包含消息选项卡。

更新对话框，使其与以下内容匹配。 JCR节点结构的最后一个对话框以XML形式展示如下：

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
    jcr:primaryType="nt:unstructured"
    jcr:title="Hello World"
    sling:resourceType="cq/gui/components/authoring/dialog">
    <content
        jcr:primaryType="nt:unstructured"
        sling:resourceType="granite/ui/components/coral/foundation/tabs"
        size="L">
        <items jcr:primaryType="nt:unstructured">
            <message
                jcr:primaryType="nt:unstructured"
                jcr:title="Message"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <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="Message for component to display"
                                fieldLabel="Message"
                                name="./message"/>
                        </items>
                    </column>
                </items>
            </message>
            <sequence
                jcr:primaryType="nt:unstructured"
                jcr:title="Sequence"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <items jcr:primaryType="nt:unstructured">
                    <column
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="granite/ui/components/coral/foundation/container">
                        <items jcr:primaryType="nt:unstructured">
                            <duration
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/form/numberfield"
                                defaultValue=""
                                fieldDescription="Amount of time the image is shown in the sequence, in milliseconds"
                                fieldLabel="Duration (milliseconds)"
                                min="0"
                                name="./duration"/>
                        </items>
                    </column>
                </items>
            </sequence>
        </items>
    </content>
</jcr:root>

消息文本字段已保存到名为message的属性，持续时间数字字段已保存到名为duration的属性。 这两个属性均在/apps/weretail-run/components/content/helloworld/production.html中由HTL作为${properties.message}和${properties.duration}引用。

Hello World — 已完成的对话框

为Hello World组件的客户端库创建文件夹。

在/apps/weretail-run/components/content/helloworld下创建名为clientlibs的文件夹。

在clientlibs文件夹下，创建名为shared且类型为cq:ClientLibraryFolder的节点。

将以下属性添加到共享客户端库：

• allowProxy | 布尔型 | true

• categories| 字符串[] | cq.screens.components

/apps/weretail-run/components/content/helloworld/clientlibs/shared的

/apps/weretail-run/components/content/helloworld/clientlibs/shared的属性

categories属性是一个用于标识客户端库的字符串。 cq.screens.componentscategory在“编辑”和“预览 — 生产”模式下均使用。 因此，在sharedclientlib中定义的任何CSS或JS都将以所有模式加载。

作为最佳实践，绝不应该公开生产环境中直接指向/apps的任何路径。 allowProxy属性确保通过前缀/etc.clientlibs引用客户端库CSS和JS。

在共享文件夹下创建名为css.txt的文件。

使用以下内容填充文件：

#base=css

styles.less

在shared文件夹下创建名为css的文件夹。 在css文件夹下添加名为style.less的文件。 客户端库的结构现在应如下所示：

本教程不会直接编写CSS，而是使用LESS。 LESS是一种常用的CSS预编译器，它支持CSS变量、mixin和函数。 AEM客户端库本身支持LESS编译。 Sass或其他预编译器可以使用，但必须在AEM之外编译。

使用以下内容填充/apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less：

/**
    Shared Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less

**/

.cmp-hello-world {
    background-color: #fff;

 &__message {
  color: #000;
  font-family: Helvetica;
  text-align:center;
 }
}

复制并粘贴shared客户端库文件夹以创建名为production的客户端库。

复制共享客户端库以创建生产客户端库。

将生产客户端库的categories属性更新为cq.screens.components.production.

这样做可确保仅在“预览 — 生产”模式下加载样式。

/apps/weretail-run/components/content/helloworld/clientlibs/production的

/apps/weretail-run/components/content/helloworld/clientlibs/production的属性。

使用以下内容填充/apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less：

/**
    Production Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less

**/
.cmp-hello-world {

    height: 100%;
    width: 100%;
    position: fixed;

 &__message {

  position: relative;
  font-size: 5rem;
  top:25%;
 }
}

上述样式将消息居中显示在屏幕中央，但仅在“生产”模式下显示。

在​ CRXDE Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs中，导航到/apps/settings/wcm/designs。

在designs文件夹下创建一个名为we-retail-run且类型为cq:Page的节点。

在we-retail-run页面下，添加另一个名为jcr:content且类型为nt:unstructured的节点。 将以下属性添加到jcr:content节点：

在/apps/settings/wcm/designs/we-retail-run设计页面。

从AEM的“开始”菜单中，导航到​ Screens > We.Retail“运行”，然后单击​ 渠道。

单击​ 创建 ​按钮

1. 选择​ 创建实体

在创建向导中：

模板步骤 — 选择​ 序列频道

1. 属性步骤

• 基本选项卡>标题= 空闲频道
• 渠道选项卡>选中​ 使渠道联机

打开“空闲通道”的页面属性。

更新设计字段，使其指向/apps/settings/wcm/designs/we-retail-run，即在上一部分中创建的设计页面。

指向/apps/settings/wcm/designs/we-retail-run的设计配置

编辑新创建的空闲通道，以便将其打开。

将页面模式切换到​ 设计 ​模式。

1. 单击Parsys中的​ 扳手 ​图标，以便配置允许的组件。

2. 单击​ Screens ​组和​ We.Retail运行 — 内容 ​组。

将页面模式切换到​ 编辑。 Hello World组件现在可以添加到页面中，并与其他序列渠道组件相结合。

在​ CRXDE Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs/we-retail-run/jcr%3Acontent/sequencechannel/par中，导航到/apps/settings/wcm/designs/we-retail-run/jcr:content/sequencechannel/par。 请注意，components属性现在包含group:Screens、group:We.Retail Run - Content。

在/apps/settings/wcm/designs/we-retail-run下

/apps/settings/wcm/designs/we-retail-run下的设计配置