开发AEM组件 developing-aem-components
AEM组件用于保存、格式化和渲染网页上提供的内容。
/libs/cq/gui/components/authoring/dialog
只能在编辑器(创作中的组件对话框)中使用。 如果在其他位置(例如在向导对话框中)使用它们,则它们可能无法按预期运行。代码示例 code-samples
本页提供了为AEM开发新组件所需的参考文档(或引用文档的链接)。 请参阅 开发AEM组件 — 代码示例 一些实际例子。
结构 structure
页面上介绍了组件的基本结构 AEM组件 — 基础知识. 该文档涵盖触屏UI和经典UI。 即使您不需要在新组件中使用经典设置,在继承现有组件时,也需要注意这些设置。
扩展现有组件和对话框 extending-existing-components-and-dialogs
根据要实施的组件,可能会扩展或自定义现有实例,而不是定义和开发整个实例 结构 白手起家。
扩展或自定义现有组件或对话框时,您可以在进行更改之前复制或复制对话框所需的整个结构或结构。
扩展现有组件 extending-an-existing-component
扩展现有组件可以通过 资源类型层次结构 以及相关的继承机制。
/apps
必须定义整个叠加。自定义现有组件对话框 customizing-a-existing-component-dialog
也可以覆盖 组件对话框 使用 Sling资源合并器 和定义属性 sling:resourceSuperType
.
这表示您只需重定义所需的差异,而不是重定义整个对话框(使用 sling:resourceSuperType
)。 现在建议使用此方法来扩展组件对话框
请参阅 Sling资源合并器 以了解更多详细信息。
定义标记 defining-the-markup
您的组件将通过 HTML. 您的组件需要定义获取所需内容所需的HTML,然后在创作和发布环境中根据需要进行渲染。
使用HTML模板语言 using-the-html-template-language
的 HTML模板语言(HTL),在AEM 6.0中引入,取代了JSP(JavaServer Pages),成为首选和推荐的服务器端模板系统,用于HTML。 对于需要构建强大企业网站的Web开发人员,HTL有助于提高安全性和开发效率。
开发内容逻辑 developing-the-content-logic
此可选逻辑选择和/或计算要渲染的内容。 它可通过相应的Use-API模式从HTL表达式中调用。
将逻辑与外观分离的机制有助于阐明对给定视图所调用的内容。 它还允许对同一资源的不同视图使用不同的逻辑。
使用Java using-java
HTL Java Use-API允许HTL文件访问自定义Java类中的Helper方法. 这允许您使用Java代码实施用于选择和配置组件内容的逻辑。
使用JavaScript using-javascript
HTL JavaScript Use-API允许HTL文件访问使用JavaScript编写的帮助程序代码. 这允许您使用JavaScript代码实施用于选择和配置组件内容的逻辑。
使用客户端HTML库 using-client-side-html-libraries
现代网站严重依赖由复杂的JavaScript和CSS代码驱动的客户端处理。 组织和优化此代码的服务可能是一个复杂的问题。
为帮助处理此问题,AEM提供 客户端库文件夹,用于在存储库中存储客户端代码,将其整理为不同的类别,并定义何时以及如何将每类代码提供给客户端。 然后,客户端库系统会负责在最终网页中生成正确的链接,以加载正确的代码。
读取 使用客户端HTML库 以了解更多信息。
配置编辑行为 configuring-the-edit-behavior
您可以配置组件的编辑行为,包括组件可用的操作等属性、就地编辑器的特性以及与组件上的事件相关的侦听器。 触屏UI和经典UI都使用此配置,尽管这两种配置存在某些特定差异。
的 配置了组件的编辑行为 通过添加 cq:editConfig
类型节点 cq:EditConfig
组件节点下(类型 cq:Component
)和添加特定属性和子节点。
配置预览行为 configuring-the-preview-behavior
的 WCM模式 在切换到 预览 模式,即使页面未刷新。
对于呈现的对WCM模式敏感的组件,需要定义它们以专门刷新它们,然后依赖Cookie的值。
创建和配置对话框 creating-and-configuring-a-dialog
对话框用于允许作者与组件进行交互。 使用对话框,作者和/或管理员可以编辑内容、配置组件或定义设计参数(使用 “设计”对话框)
Coral用户界面和Granite用户界面 coral-ui-and-granite-ui
Coral用户界面 和 Granite用户界面 定义AEM的现代外观。
Granite UI提供了大量基本组件(小组件) 需要在创作环境中创建对话框。 必要时,您可以扩展此选择并创建自己的小组件。
有关完整详细信息,请参阅:
-
Coral用户界面
- 在所有云解决方案中提供一致的UI
- AEM触屏优化UI的概念 — Coral UI
- Coral用户界面指南
-
Granite用户界面
- 提供封装在Sling组件中的Coral UI标记,以用于构建UI控制台和对话框
- AEM触屏优化UI的概念 — Granite UI
- Granite用户界面文档
创建新对话框 creating-a-new-dialog
触屏UI的对话框:
-
已命名
cq:dialog
. -
定义为
nt:unstructured
节点sling:resourceType
属性集。 -
位于
cq:Component
节点,且位于其组件定义旁边。 -
基于其内容结构和
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
自定义对话框字段 customizing-dialog-fields
创建新字段 creating-a-new-field
触屏UI的小组件作为Granite UI组件实施。
要在触屏UI的组件对话框中创建新小组件,需要您 创建新的Granite UI字段组件.
如果将对话框视为表单元素的简单容器,则还可以将对话框内容的主要内容视为表单字段。 创建新表单字段需要创建资源类型;这等同于创建新组件。 为了帮助您完成该任务,Granite UI提供了一个要继承的通用字段组件(使用 sling:resourceSuperType
):
/libs/granite/ui/components/coral/foundation/form/field
更具体地说,Granite UI提供了一系列字段组件,这些组件适合在对话框(或更一般地,在 表单)。
cq:Widgets
节点,每个节点具有特定 xtype
以建立与相应ExtJS小组件的关系。 从实施角度来看,这些小组件是通过ExtJS框架在客户端渲染的。创建资源类型后,您可以使用属性在对话框中添加新节点,以实例化字段 sling:resourceType
引用您刚才引入的资源类型。
为样式和行为创建客户端库 creating-a-client-library-for-style-and-behavior
如果要为组件定义样式和行为,可以创建专用 客户端库 定义自定义CSS/LESS和JS的附加内容。
要仅为组件对话框加载客户端库(即不会为其他组件加载),您需要设置属性 extraClientlibs
对话框的类别名称。 如果您的客户端库非常大,并且/或您的字段特定于该对话框,而在其他对话框中不需要,则建议使用此方法。
要为所有对话框加载客户端库,请将客户端库的category属性设置为 cq.authoring.dialog
. 这是客户端库的类别名称,默认情况下,在渲染所有对话框时会包含此名称。 如果客户端库很小,并且/或您的字段是通用的,并且可以在其他对话框中重复使用,则需要执行此操作。
有关示例,请参阅:
-
cqgems/customizingfield/components/colorpicker/clientlibs
- 由提供 代码示例
扩展(继承)字段 extending-inheriting-from-a-field
根据您的要求,您可以:
- 通过组件继承扩展给定的Granite UI字段(
sling:resourceSuperType
) - 通过遵循小组件库API(JS/CSS继承),从基础小组件库扩展给定小组件(对于Granite UI,即Coral UI)
对对话框字段的访问权限 access-to-dialog-fields
您还可以使用渲染条件( rendercondition
)控制谁有权访问对话框中的特定选项卡/字段;例如:
+ mybutton
- sling:resourceType = granite/ui/components/coral/foundation/button
+ rendercondition
- sling:resourceType = myapp/components/renderconditions/group
- groups = ["administrators"]
处理字段事件 handling-field-events
处理对话框字段中事件的方法现已完成 自定义客户端库中的侦听器. 这是与以前的 内容结构中的侦听器.
自定义客户端库中的侦听器 listeners-in-a-custom-client-library
要在字段中插入逻辑,您应:
- 使用给定的CSS类标记您的字段( 钩钩)。
- 在客户端库中定义一个挂接到该CSS类名称的JS侦听器(这可确保自定义逻辑的范围仅限您的字段,并且不会影响其他相同类型的字段)。
要实现此目的,您需要了解要与之交互的底层小组件库。 请参阅 Coral用户界面文档 以确定要对哪个事件做出反应。 这与您过去使用ExtJS执行的过程非常相似:找到给定小组件的文档页面,然后查看其事件API的详细信息。
有关示例,请参阅:
-
cqgems/customizingfield/components/clientlibs/customizingfield
- 由提供 代码示例
内容结构中的侦听器 listeners-in-the-content-structure
在使用ExtJS的经典UI中,通常会在内容结构中为给定小组件设置侦听器。 由于JS侦听器代码(或根本不是任何代码)不再在内容中定义,因此在触屏UI中实现相同的方式有所不同。
内容结构描述语义结构;它不应(必须)暗示基础小组件的性质。 通过在内容结构中不包含JS代码,您可以更改实施详细信息,而无需更改内容结构。 换言之,您无需触摸内容结构即可更改小组件库。
检测对话框的可用性 dialog-ready
如果您有自定义JavaScript,并且需要仅在对话框可用且准备就绪后才执行,则应当监听 dialog-ready
事件。
当对话框加载(或重新加载)并准备就绪以供使用时,将触发此事件,这意味着每当对话框的DOM中发生更改(创建/更新)时。
dialog-ready
可用于挂接JavaScript自定义代码,该代码可对对话框或类似任务中的字段执行自定义。
字段验证 field-validation
必填字段 mandatory-field
要将给定字段标记为必填字段,请在字段的内容节点上设置以下属性:
- 名称:
required
- 类型:
Boolean
有关示例,请参阅:
/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title
字段验证(Granite UI) field-validation-granite-ui
在Granite UI和Granite UI组件(等效于小组件)中,使用 foundation-validation
API。 请参阅 foundation-valdiation
Granite文档以了解详细信息。
有关示例,请参阅:
-
cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js
- 由提供 代码示例
-
/libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js
创建和配置设计对话框 creating-and-configuring-a-design-dialog
当组件具有可在中编辑的设计详细信息时,会提供“设计”对话框 设计模式.
定义与 用于编辑内容的对话框,其区别在于它被定义为节点:
- 节点名称:
cq:design_dialog
- 类型:
nt:unstructured
创建和配置就地编辑器 creating-and-configuring-an-inplace-editor
就地编辑器允许用户直接在段落流中编辑内容,而无需打开对话框。 例如,标准的文本组件和标题组件都具有就地编辑器。
并非每个组件类型都需要/有意义的就地编辑器。
请参阅 扩展页面创作 — 添加新的就地编辑器 以了解更多信息。
自定义组件工具栏 customizing-the-component-toolbar
的 组件工具栏 允许用户访问组件的一系列操作,如编辑、配置、复制和删除。
请参阅 扩展页面创作 — 向组件工具栏添加新操作 以了解更多信息。
为引用边栏配置组件(借入/借出) configuring-a-component-for-the-references-rail-borrowed-lent
如果新组件引用了来自其他页面的内容,则您可以考虑是否希望该组件对 借入内容 和 借出内容 部分 引用 边栏。
现成的AEM仅检查引用组件。 要添加组件,您需要配置OSGi包 WCM创作内容引用配置.
在定义中创建新条目,指定组件以及要检查的属性。 例如:
/apps/<your-Project>/components/reference@parentPath
启用组件并将其添加到段落系统 enabling-and-adding-your-component-to-the-paragraph-system
开发组件后,需要启用该组件以在相应的段落系统中使用,以便在所需的页面上使用。
这可以通过以下任一方式完成:
配置段落系统以便拖动资产可创建组件实例 configuring-a-paragraph-system-so-that-dragging-an-asset-creates-a-component-instance
AEM允许您在页面上配置段落系统,以便 当用户将(相应)资产拖动到该页面的实例上时,将自动创建新组件的实例 (而不是始终将空组件拖到页面中)。
可以配置此行为和所需的资产到组件关系:
-
在页面设计的段落定义下。 例如:
/etc/designs/<myApp>/page/par
创建新节点:
- 名称:
cq:authoring
- 类型:
nt:unstructured
-
在此下,创建一个新节点以保存所有资产到组件映射:
- 名称:
assetToComponentMapping
- 类型:
nt:unstructured
- 名称:
-
对于每个资产到组件映射,创建一个节点:
- 名称:文本;建议名称指示资产及相关组件类型;例如,图像
- 类型:
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上找到此页面的代码
使用AEM Brackets扩展 using-the-aem-brackets-extension
的 AEM Brackets扩展 提供了编辑AEM组件和客户端库的顺畅工作流。 它基于 括号 代码编辑器。
扩展:
- 简化了同步(不需要Maven或File Vault),以帮助提高开发人员效率,并帮助知识有限的前端开发人员参与项目。
- 提供一些 HTL 支持,模板语言旨在简化组件开发并提高安全性。
从经典组件迁移 migrating-from-a-classic-component
将专为与经典UI一起使用而设计的组件迁移到可与触屏UI一起使用的组件(单独或联合使用)时,应考虑以下问题:
-
HTL
- 使用 HTL 不是强制的,但如果您的组件需要更新,则最好考虑 从JSP迁移到HTL.
-
组件
- 迁移
cq:listener
使用经典UI特定函数的代码 - RTE插件,以了解更多信息,请参阅 配置富文本编辑器.
- 迁移
cq:listener
代码 使用经典UI特有的函数
- 迁移
-
对话框
- 您需要创建一个新对话框以在触屏UI中使用。 但是,出于兼容目的,当未为触屏UI定义任何对话框时,触屏UI可以使用经典UI对话框的定义。
- 的 AEM现代化工具 旨在帮助您扩展现有组件。
- 将ExtJS映射到Granite UI组件 提供了ExtJS xtypes和节点类型及其等效Granite UI资源类型的简便概述。
- 自定义字段,有关更多信息,请参阅AEM Gems会议 自定义对话框字段.
- 从类型迁移到 Granite UI验证
- 使用JS侦听器,有关更多信息,请参阅 处理字段事件 和AEM Gem会议 自定义对话框字段.
迁移cq:listener代码 migrating-cq-listener-code
如果您正在迁移专为经典UI设计的项目,则 cq:listener
代码(和与组件相关的clientlib)可能使用特定于经典UI的函数(例如 CQ.wcm.*
)。 对于迁移,必须使用触屏UI中的对等对象/函数来更新此类代码。
如果您的项目完全迁移到触屏优化UI,您需要替换此类代码,以使用与触屏优化UI相关的对象和函数。
但是,如果您的项目在迁移期间(通常情况下)必须同时满足经典UI和触屏优化UI的需求,则您需要实施一个开关以区分引用相应对象的单独代码。
此切换机制可实现为:
if (Granite.author) {
// touch UI
} else {
// classic UI
}
记录组件 documenting-your-component
作为开发人员,您希望轻松访问组件文档,以便快速了解:
- 描述
- 预期用途
- 内容结构和属性
- 公开的API和扩展点
- 等等
因此,很容易就会在组件中使用您现有的任何文档标记。
你只需在 README.md
文件。 然后,此标记将显示在 组件控制台.
支持的Markdown与 内容片段.