Show Menu
主题×

开发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中,只有值 EDIT PREVIEW 用于WCM模 式Cookie

创建和配置对话框

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

Coral UI和Granite UI

Coral UI Granite 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 成的。 有关详细信息,
有关示例,请参阅:
  • 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 扩展提供了一个 、用于编辑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 放置一个文件。 此标记随后将显示在组件控 制台中
支持的标记与内容片段的标 记相同