为AEM Screensas a Cloud Service开发自定义组件

上次更新： 2023-11-21

以下教程将介绍为AEM Screens创建自定义组件的步骤。 AEM Screens可重复使用其他AEM产品的许多现有设计模式和技术。 本教程重点介绍了为AEM Screens开发时的差异和特殊注意事项。

概述

本教程面向不熟悉AEM Screens的开发人员。 在本教程中，为AEM Screens中的序列渠道构建了一个简单的“Hello World”组件。 通过对话框，作者可以更新显示的文本。

前提条件

要完成本教程，您需要满足以下条件：

  1. 最新的Screens功能包

  2. AEM Screens 播放器

  3. 本地开发环境

使用执行教程步骤和屏幕截图 CRXDE Lite. IDE也可用于完成本教程。 有关使用IDE开发的详细信息 带AEM的组件可在此处找到。

项目设置

屏幕项目的源代码通常作为多模块Maven项目进行管理。 为了加快教程，使用预生成了一个项目 AEM项目原型13. 更多详细信息 可在此处找到使用Maven AEM项目原型创建项目的内容.

  1. 使用下载并安装以下包 CRX包管理器：

获取文件

获取文件
（可选） 如果使用Eclipse或其他IDE，请下载以下源包。 使用Maven命令将项目部署到本地AEM实例：

mvn -PautoInstallPackage clean install

启动HelloWorld SRC Screens We.Retail运行项目

获取文件

  1. 在 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 We.Retail通过CRX包管理器运行Ui.Apps和Ui.Content包

  2. 此 screens-weretail-run.ui.apps 软件包在下方安装代码 /apps/weretail-run.

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

    注意

    在本教程中，不会编写任何Java™代码。 如果需要更复杂的业务逻辑，可以使用核心Java™捆绑包创建和部署后端Java™。

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

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

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

  3. 此 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 Run项目的所有配置。 /content/dam/we-retail-run 包括为项目启动数字资产。 /content/screens/we-retail-run 包含Screens内容结构。 这些路径下的内容主要在AEM中更新。 为了提高环境（本地、开发、暂存、生产）之间的一致性，通常将基本内容结构保存在源代码控制中。

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

    从AEM的“开始”菜单>单击屏幕上的图标。 验证是否可看到We.Retail运行项目。

    we-retail-run-starter

创建Hello World组件

Hello World组件是一个简单的组件，允许用户输入要在屏幕上显示的消息。 该组件基于 AEM Screens组件模板：https://github.com/Adobe-Marketing-Cloud/aem-screens-component-template.

AEM Screens具有一些有趣的限制，对于传统的WCM Sites组件未必是这样。

  • 大多数屏幕组件必须在目标数字标牌设备上全屏运行
  • 必须在序列渠道中嵌入大多数Screens组件才能生成幻灯片
  • 创作应允许编辑序列渠道中的各个组件，因此不可能全屏呈现它们

  1. 在 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的属性

    此 helloworld 组件扩展 foundation/components/parbase 组件，以便能够在序列通道中正确使用它。

  2. 在下创建文件 /apps/weretail-run/components/content/helloworld 已命名 helloworld.html.

    使用以下内容填充文件：

    <!--/*

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

*/-->

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

<!--/* edit: any other authoring mode, that is, edit, design, scaffolding, and so on. */-->
<sly data-sly-test="${!production}" data-sly-include="edit.html" />

    Screens组件需要两种不同的渲染，具体取决于 创作模式 正在使用：

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

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

  3. 在下创建文件 /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组件。 A data-duration 属性包含在内，因为组件在序列渠道中被使用。 此 data-duration 属性由序列渠道用来了解序列项目显示的时间。

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

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

  4. 在下创建文件 /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 呈现标签 《你好世界》 作为该案例中的占位符。 可以使用i18n国际化标签的字符串，以支持在多个区域设置中进行创作。

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

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

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

    copy-image-dialog

  6. 更新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 (ms)"
                                min="0"
                                name="./duration"/>
                        </items>
                    </column>
                </items>
            </sequence>
        </items>
    </content>
</jcr:root>

    此 textfield ，则将消息保存到名为的属性 message 而且 numberfield 的Duration将保存到名为的属性 duration. 这两个属性均在中引用 /apps/weretail-run/components/content/helloworld/production.html 由HTL作为 ${properties.message} 和 ${properties.duration}.

    Hello World — 已完成的对话框

    Hello World — 已完成的对话框

创建客户端库

客户端库提供了一种机制，用于组织和管理AEM实施所需的CSS和JavaScript文件。

AEM Screens组件在编辑模式与预览/生产模式中的呈现方式有所不同。 创建了两个客户端库：一个用于编辑模式，另一个用于预览/生产模式。

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

    下 /apps/weretail-run/components/content/helloworld，创建一个名为的文件夹 clientlibs.

    2018-04-30_at_1046am

  2. 在 clientlibs 文件夹，创建名为的节点 shared 类型 cq:ClientLibraryFolder.

    2018-04-30_at_1115am

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

    • 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属性确保通过前缀of/etc.clientlibs引用客户端库CSS和JS。

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

    使用以下内容填充文件：

    #base=css

styles.less

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

    2018-04-30_at_3_11pm

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

  6. 填充 /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;
 }
}

  7. 复制并粘贴 shared 用于创建名为的客户端库的客户端库文件夹 production.

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

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

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

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

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

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

  9. 填充 /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%;
 }
}

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

第三种clientlibrary类别： cq.screens.components.edit 可用于向组件添加仅用于编辑的特定样式。

Clientlib类别 用途
cq.screens.components 在编辑模式和生产模式之间共享的样式和脚本
cq.screens.components.edit 仅在编辑模式下使用的样式和脚本
cq.screens.components.production 仅在生产模式下使用的样式和脚本

创建设计页面

AEM Screens使用 静态页面模板 和 设计配置 实现全球变革。 设计配置通常用于为通道上的Parsys配置允许的组件。 最佳做法是以特定于应用程序的方式存储这些配置。

将在下面创建We.Retail运行设计页面，该页面存储特定于We.Retail运行项目的所有配置。

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

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

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

    名称 类型 价值
    jcr:title 字符串 We.Retail运行
    sling:resourceType 字符串 wcm/core/components/designer
    cq：doctype 字符串 html_5

    位于/apps/settings/wcm/designs/we-retail-run的设计页面

    位于/apps/settings/wcm/designs/we-retail-run的设计页面

创建序列渠道

Hello World组件旨在用于序列频道。 要测试组件，将创建一个新的序列渠道。

  1. 从AEM的“开始”菜单中，导航到 Screens > We.Retail Ru n >并选择 渠道.

  2. 单击 创建 按钮

    1. 选择 创建实体

    2018-04-30_at_5_18pm

  3. 在创建向导中：

  4. 模板步骤 — 选择 序列渠道

    1. 属性步骤
    • 基本选项卡>标题= 空闲通道
    • 渠道选项卡>检查 使渠道联机

    空闲通道

  5. 打开“空闲通道”的页面属性。 更新设计字段，使其指向 /apps/settings/wcm/designs/we-retail-run,在上一部分中创建的设计页面。

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

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

  6. 编辑已创建的空闲通道，以将其打开。

  7. 将页面模式切换到 设计 模式。

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

    2. 选择 Screens 组和 We.Retail运行 — 内容 组。

    2018-04-30_at_5_43pm

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

    2018-04-30_at_5_53pm

  9. 在 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下的设计配置

自定义处理程序模板

如果您的自定义组件使用外部资源，如资产（图像、视频、字体和图标）、特定资产演绎版或客户端库（css和js），这些资源不会自动添加到离线配置。 原因在于，默认情况下，Adobe仅捆绑HTML标记。

为了让您自定义和优化下载到播放器的确切资源，Adobe为自定义组件提供了一个扩展机制，以向Screens中的离线缓存逻辑公开其依赖项。

以下部分展示了自定义离线资源处理程序的模板以及 pom.xml 用于特定项目。

package …;

import javax.annotation.Nonnull;

import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Reference;
import org.apache.felix.scr.annotations.Service;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceUtil;
import org.apache.sling.api.resource.ValueMap;

import com.adobe.cq.screens.visitor.OfflineResourceHandler;

@Service(value = OfflineResourceHandler.class)
@Component(immediate = true)
public class MyCustomHandler extends AbstractResourceHandler {

 @Reference
 private …; // OSGi services injection

 /**
  * The resource types that are handled by the handler.
  * @return the handled resource types
  */
 @Nonnull
 @Override
 public String[] getSupportedResourceTypes() {
     return new String[] { … };
 }

 /**
  * Accept the provided resource, visit and traverse it as needed.
  * @param resource The resource to accept
  */
 @Override
 public void accept(@Nonnull Resource resource) {
     ValueMap properties = ResourceUtil.getValueMap(resource);

     /* You can directly add explicit paths for offline caching using the `visit`
        method of the visitor. */

     // retrieve a custom property from the component
     String myCustomRenditionUrl = properties.get("myCustomRenditionUrl", String.class);
     // adding that exact asset/rendition/path to the offline manifest
     this.visitor.visit(myCustomRenditionUrl);


     /* You can delegate handling for dependent resources so they are also added to
        the offline cache using the `accept` method of the visitor. */

     // retrieve a referenced dependent resource
     String referencedResourcePath = properties.get("myOtherResource", String.class);
     ResourceResolver resolver = resource.getResourceResolver();
     Resource referencedResource = resolver.getResource(referencedResourcePath);
     // let the handler for that resource handle it
     if (referencedResource != null) {
         this.visitor.accept(referencedResource);
     }
   }
}

以下代码提供了 pom.xml 对于该特定项目：

   <dependencies>
        …
        <!-- Felix annotations -->
        <dependency>
            <groupId>org.apache.felix</groupId>
            <artifactId>org.apache.felix.scr.annotations</artifactId>
            <version>1.9.0</version>
            <scope>provided</scope>
        </dependency>

        <!-- Screens core bundle with OfflineResourceHandler/AbstractResourceHandler -->
        <dependency>
            <groupId>com.adobe.cq.screens</groupId>
            <artifactId>com.adobe.cq.screens</artifactId>
            <version>1.5.90</version>
            <scope>provided</scope>
        </dependency>
        …
      </dependencies>

融于一起

以下视频介绍了已完成的组件以及如何将其添加到序列渠道。 然后，该渠道会添加到位置显示中，并最终分配给Screens播放器。

完成的代码

以下是教程中完成的代码。 此 screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip 和 screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip 是编译的AEM包。 SRC-screens-weretail-run-0.0.1.zip ​ 是可以使用Maven部署的未编译的源代码。

获取文件

获取文件

获取文件

上一页
Next page

在此页面上