开发AEM组件

AEM组件用于保存、格式化和呈现网页上提供的内容。

  • 创作 页面时,组件允许作者编辑和配置内容。

  • 在发布实例中,组件会呈现您的内容,并根据您的要求将其呈现给网站访客。

注意

本页是文档AEM组件——基 础知识的继续

注意

以下组 /libs/cq/gui/components/authoring/dialog 件仅用于编辑器(“创作”中的组件对话框)。 如果在其他位置使用它们(例如在向导对话框中),它们的行为可能不按预期方式显示。

代码样本

本页提供为AEM开发新组件所需的参考文档(或指向参考文档的链接)。 有关 实际示例,请参阅开发AEM 组件——代码示例。

结构

AEM组件——基础知识页面介绍了组件 的基本结构。 该文档涵盖触屏优化和经典UI。 即使您不需要在新组件中使用经典设置,在从现有组件继承时也可以了解这些设置。

扩展现有组件和对话框

根据要实现的组件,可以扩展或自定义现有实例,而不是从头定义和开发整个 结构

在扩展或自定义现有组件或对话框时,您可以复制或复制对话框所需的整个结构或结构,然后再进行更改。

扩展现有组件

可以使用资源类型层次结构和相 关的继承机制 ,扩展现有组件。

注意

还可以使用基于搜索路径逻辑的叠加来重新定义元件。 但是,在这种情况下, 将不会触发 Sling Resource Merage /apps ,并且必须定义整个叠加。

注意

内容 片段组件 ,也可以进行自定义和扩展,但必须考虑完整结构和与资产的关系。

自定义现有组件对话框

也可以使用Sling Resource Merabile 来覆盖​组件对话框 , sling:resourceSuperType并定义属性。

这意味着您只需重新定义所需的差异,而不是重新定义整个对话框(使用 sling:resourceSuperType)。 现在建议使用此方法来扩展组件对话框

有关更多 详细信息,请参 阅Sling资源合并。

定义标记

组件将使用HTML 呈现。 您的组件需要定义需要的HTML,以获取所需内容,然后根据需要在创作和发布环境上呈现它。

使用HTML模板语言

The HTML Templating Language (HTL), introduced with AEM 6.0, takes the place of JSP (JavaServer Pages) as the preferred and recommended server-side template system for HTML. 对于需要构建强大企业网站的Web开发人员,HTL有助于提高安全性和开发效率。

注意

虽然HTL和JSP都可用于开发组件,但我们将在本页用HTL来说明开发,因为它是AEM的推荐的脚本语言。

开发内容逻辑

此可选逻辑选择和/或计算要呈现的内容。 它从HTL表达式中调用,使用相应的Use-API模式。

将逻辑与外观分离的机制有助于阐明对给定视图所调用的内容。 它还允许同一资源的不同视图有不同的逻辑。

使用Java

HTL Java Use-API使HTL文件能够访问自定义Java类中的帮助程序方法。 这允许您使用Java代码实现用于选择和配置组件内容的逻辑。

使用JavaScript

HTL JavaScript Use-API使HTL文件能够访问用JavaScript编写的帮助代码。 这允许您使用JavaScript代码实现用于选择和配置组件内容的逻辑。

使用客户端HTML库

现代网站严重依赖由复杂的JavaScript和CSS代码驱动的客户端处理。 组织和优化此代码的服务可能是一个复杂的问题。

为帮助解决此问题,AEM提 供了客户端库文件夹,允许您将客户端代码存储在存储库中,将其组织到类别中,并定义何时以及如何将每个类别代码提供给客户端。 然后,客户端库系统负责在最终网页中生成正确的链接,以加载正确的代码。

读使用客户端HTML库 ,了解更多信息。

配置编辑行为

您可以配置组件的编辑行为,包括组件可用的操作、就地编辑器的特性以及与组件上的事件相关的监听器等属性。 该配置对于触屏优化UI和经典UI都是通用的,尽管有某些特定的差异。

过在组件节点 (类型)下添加类型的节点 cq:editConfig ,并添加特定属性和子节 cq:EditConfig cq:Component点,可配置组件的编辑行为。

配置预览行为

切换 到预览模式 时,即使页面未刷新, 也会设置 WCM模式Cookie。

对于呈现对WCM模式敏感的组件,需要定义它们以专门刷新它们,然后依赖cookie的值。

注意

在触屏优化UI中,只有值 EDITPREVIEW 用于WCM模 式Cookie

创建和配置对话框

对话框用于允许作者与组件进行交互。 使用对话框,作者和/或管理员可以编辑内容、配置组件或定义设计参数(使用“设 计”对话框)

Coral UI和Granite UI

Coral UIGranite UI 定义AEM的现代外观。

Granite UI提供了在创作环境下创建对话框所需的大 量基本组件(构件)。 必要时,您可以扩展此选择并创建您自己的构件。

有关使用Coral和Granite资源类型开发组件的详细信息,请参阅: 使用Coral/Granite资源类型构建Experience Manager组件

有关完整详细信息,请参阅:

注意

由于Granite UI组件的性质(以及与ExtJS构件的不同),组件与触屏优化UI和经典UI的交互方式存在一 些差异

Creating a New Dialog

触屏优化UI的对话框:

  • 名称 cq:dialog

  • 定义为具有 nt:unstructured 属性集的 sling:resourceType 节点。

  • 位于其节点 cq:Component 下,并位于其组件定义旁。

  • 根据其内容结构和属性在服务器端呈现(作为Sling组件) sling:resourceType

  • 使用Granite UI框架。

  • 包含描述对话框中字段的节点结构。

    • 这些节点 nt:unstructured 具有所需的 sling:resourceType 属性。

示例节点结构可能是:

newComponent (cq:Component)
  cq:dialog (nt:unstructured)
    content 
      layout 
      items 
        column 
          items 
            file 
            description  

自定义对话框与开发组件相似,因为对话框本身是组件(即组件脚本呈现的标记以及客户端库提供的行为/样式)。

有关示例,请参阅:

  • /libs/foundation/components/text/cq:dialog
  • /libs/foundation/components/download/cq:dialog
注意

如果组件没有为触屏优化UI定义对话框,则经典UI对话框将用作兼容性层内的回退。 要自定义此类对话框,您需要自定义经典UI对话框。 请参 阅经典UI的AEM组件

自定义对话框字段

注意

请参阅:

Creating a New Field

触屏优化UI的构件作为Granite UI组件实现。

要在触屏优化UI的组件对话框中创建新的构件,您需 要创建新的Granite UI字段组件

注意

有关Granite UI的完整详细信息,请参阅 Granite UI文档

如果您将对话框视为表单元素的简单容器,则还可以将对话框内容的主要内容看作表单字段。 创建新表单字段需要创建资源类型; 这等效于创建新组件。 为了在该任务中帮助您,Granite UI会优惠一个要继承的通用字段组件(使用 sling:resourceSuperType):

/libs/granite/ui/components/coral/foundation/form/field

更具体而言,Granite UI提供了一系列适用于对话框(或更一般地,以表单形式)的字段 组件

注意

这与经典UI不同,在经典UI中,构件由节点 cq:Widgets 表示,每个节点都具有特定的 xtype 节点,以建立与相应ExtJS构件的关系。 从实现角度来看,这些构件是由ExtJS框架在客户端呈现的。

创建资源类型后,您可以通过在对话框中添加新节点来实例化字段,该节 sling:resourceType 点的属性引用您刚引入的资源类型。

为样式和行为创建客户端库

如果要为组件定义样式和行为,可创建专用的客 户端库 ,用于定义自定义CSS/LESS和JS。

要仅为组件对话框加载客户端库(即不为其他组件加载它),您需要将对话框的属性设置为刚刚创建的客户端库的类别名。 extraClientlibs 如果客户端库很大,且/或字段特定于该对话框,而在其他对话框中不需要,则此选项是可取的。

要为所有对话框加载客户端库,请将客户端库的类别属性设置为 cq.authoring.dialog。 这是显示所有对话框时默认包含的客户端库的类别名。 如果客户端库很小,且/或字段是通用字段,并且可能会在其他对话框中重用,则您希望这样做。

有关示例,请参阅:

  • cqgems/customizingfield/components/colorpicker/clientlibs

扩展(继承自)字段

根据您的要求,您可以:

  • 按组件继承扩展给定的Granite UI字段( sling:resourceSuperType)
  • 通过遵循构件库API(JS/CSS继承),从基础构件库扩展给定构件(对于Granite UI,此为Coral UI)

访问对话框字段

您还可以使用渲染条 rendercondition件()控制谁有权访问对话框中的特定选项卡/字段; 例如:

+ mybutton
  - sling:resourceType = granite/ui/components/coral/foundation/button
  + rendercondition
    - sling:resourceType = myapp/components/renderconditions/group
    - groups = ["administrators"]

处理字段事件

现在,在自定义客户端库中对监听器进行对 话字段事件的处理。 这与在内容结构中设置监听器 的旧方法有所不同

自定义客户端库中的监听器

要将逻辑注入您的领域,您应:

  1. 将您的字段标记为给定的CSS类( 挂接)。
  2. 在客户端库中定义一个挂接到该CSS类名的JS监听器(这可确保自定义逻辑仅限于您的字段,不会影响同一类型的其他字段)。

要实现此目的,您需要了解要与之交互的底层构件库。 请参 阅Coral UI文档 ,确定要对哪个事件做出响应。 这与您过去使用ExtJS执行的过程非常相似: 查找给定构件的文档页面,然后检查其事件API的详细信息。

有关示例,请参阅:

  • cqgems/customizingfield/components/clientlibs/customizingfield

内容结构中的监听器

在具有ExtJS的经典UI中,通常在内容结构中具有给定构件的监听器。 在触屏优化UI中实现相同效果是不同的,因为JS监听器代码(或任何代码)在内容中不再定义。

内容结构描述了语义结构; 它不应(必须)暗示基础构件的性质。 如果内容结构中没有JS代码,则无需更改内容结构即可更改实施详细信息。 换言之,您无需触摸内容结构即可更改构件库。

字段验证

必填字段

要将给定字段标记为必填字段,请在字段的内容节点上设置以下属性:

  • 名称: required
  • 类型: Boolean

有关示例,请参阅:

/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title

字段验证(Granite UI)

Granite UI和Granite UI组件(等效于构件)中的字段验证是使用API完 foundation-validation 成的。 有关详细信息, foundation-valdiation 请参阅Granite文档。

有关示例,请参阅:

  • cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js

  • /libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js

创建和配置设计对话框

当组件具有可在设计模式下编辑的设计详细信息时,将提供“设 计”对话框

该定义与用于编辑内容的 对话框的定义非常相似,区别在于它被定义为节点:

  • Node name: cq:design_dialog
  • 类型: nt:unstructured

创建和配置就地编辑器

就地编辑器允许用户直接编辑段落流中的内容,无需打开对话框。 例如,标准文本和标题组件都具有就地编辑器。

对于每个组件类型,就地编辑器并非必需/有意义。

有关详 细信息,请参阅扩展页面创作——添加新的就地 编辑器。

自定义组件工具栏

件工具栏 ,使用户能够访问组件的一系列操作,如编辑、配置、复制和删除。

有关 详细信息,请参阅扩展页面创作——向组件工具栏添加 “新操作”。

为引用边栏配置组件(借入/借出)

如果您的新组件引用了来自其他页面的内容,则您可以考虑是否希望它影响引 用边栏的 “借 用内容 ”和“借 用内容​”部分。

现成的AEM仅检查引用组件。 要添加组件,您需要配置OSGi捆绑WCM 创作内容引用配置

在定义中创建一个新条目,指定您的组件以及要检查的属性。 例如:

/apps/<your-Project>/components/reference@parentPath

注意

When working with AEM there are several methods of managing the configuration settings for such services. See Configuring OSGi for more details and the recommended practices.

启用组件并将其添加到段落系统

开发组件后,需要启用该组件以在相应的段落系统中使用,以便在所需的页面上使用。

可通过以下任一方式执行此操作:

Configuring a Paragraph System so that Dragging an Asset Creates a Component Instance

AEM优惠在页面上配置段落系统 的可能性,当用户将(适当)资产拖动到该页面的实例时,系统会自动创建新组件的实例 (而不是始终将空组件拖动到页面)。

可以配置此行为以及所需的资产对组件关系:

  1. 在页面设计的段落定义下。 例如:

    • /etc/designs/<myApp>/page/par

    创建新节点:

    • 名称: cq:authoring
    • 类型: nt:unstructured
  2. 在此下,创建一个新节点以保存所有资产到组件映射:

    • 名称: assetToComponentMapping
    • 类型: nt:unstructured
  3. 对于每个资产到组件映射,请创建一个节点:

    • 名称: 文本; 建议名称指示资产和相关组件类型; 例如,图像
    • 类型: nt:unstructured

    每个组件都具有以下属性:

    • assetGroup:

      • 类型: String
      • 值: 相关资产所属的组; 例如, media
    • assetMimetype:

      • 类型: String
      • 值: 相关资产的mime类型; 示例 image/*
    • droptarget:

      • 类型: String
      • 值: 投降目标; 例如, image
    • resourceType:

      • 类型: String
      • 值: 相关组件资源; 例如, foundation/components/image
    • type:

      • 类型: String
      • 值: 例如, Images

有关示例,请参阅:

  • /etc/designs/geometrixx/jcr:content/page/par/cq:authoring
  • /etc/designs/geometrixx-outdoors/jcr:content/page/par/cq:authoring
  • /etc/designs/geometrixx-media/jcr:content/article/article-content-par/cq:authoring

GITHUB上的代码

您可以在GitHub上找到此页面的代码

注意

现在,使用核心组件和可编辑模板时,可以在UI中轻松配置 组件实例 的自动创建。 有关 定义与给定媒体类型 自动关联的组件的详细信息,请参阅创建页面模板。

使用AEM Brackets扩展

AEM Brackets Extension 提供了编辑AEM组件和客户端库的流畅工作流程。 它基于Brackets代 码编 辑器。

扩展:

  • 简化同步(无需Maven或File Vault),以帮助提高开发人员效率,并帮助具有有限AEM知识的前端开发人员参与项目。
  • 提供一 些HTL 支持,该模板语言旨在简化组件开发并提高安全性。
注意

建议使用Brackets创建组件。 它替换了专为经典UI设计的CRXDE Lite-创建组件功能。

从经典组件迁移

将设计用于经典UI的组件迁移到可与触屏优化UI一起使用的组件(单独或联合使用)时,应考虑以下问题:

迁移cq:监听器代码

如果您正在迁移专为经典UI设计的项目,则代 cq:listener 码(和与组件相关的客户端库)可能使用特定于经典UI的函数( CQ.wcm.*如)。 对于迁移,必须使用触屏优化UI中的等效对象/函数更新此类代码。

如果您的项目正完全迁移到触屏优化UI,您需要替换此类代码以使用与触屏优化UI相关的对象和功能。

但是,如果您的项目在迁移期间(通常情况)必须同时满足经典UI和触屏优化UI的需求,则需要实现一个切换,以区分引用相应对象的单独代码。

此切换机制可实现为:

if (Granite.author) {
    // touch UI
} else {
    // classic UI
}

对组件进行文档化

作为开发人员,您希望轻松访问组件文档,以便快速了解:

  • 描述
  • 预期用途
  • 内容结构和属性
  • 暴露的API和扩展点
  • 等等。

因此,很容易将您在组件本身中提供的任何现有文档标记公开。

您只需在组件结构中 README.md 放置一个文件。 此标记随后将显示在组件控 制台中

chlimage_1-225

支持的标记与内容片段的标 记相同

在此页面上