组件是在AEM中构建体验的核心。 的 核心组件 和 AEM项目原型 使用一组现成、强大的组件,让您能够轻松入门。 的 WKND教程 指导开发人员如何使用这些工具以及如何构建自定义组件以创建新的AEM站点。
由于WKND教程涵盖大多数用例,因此本文档仅作为这些资源的补充。 本指南详细介绍了组件在AEM中的结构和配置方式,不是入门指南。
本节介绍一些关键概念和问题,并介绍开发您自己的组件时所需的详细信息。
在开始实际配置或编码组件之前,您应该先询问:
在花时间创建全新组件之前,请考虑自定义或扩展现有组件。 核心组件 提供一套灵活、强大且经过良好测试的生产就绪型组件。
核心组件还提供 清除自定义模式 以使其适应您自己项目的需求。
元件也可通过 叠加 基于搜索路径逻辑。 然而,在此情况下, Sling资源合并器 将不会触发, /apps
必须定义整个叠加。
还可以使用Sling资源合并器覆盖组件对话框并定义属性 sling:resourceSuperType
.
这表示您只需重定义所需的差异,而不需要重定义整个对话框。
您的组件将通过 HTML。 您的组件需要定义获取所需内容所需的HTML,然后在创作和发布环境中根据需要进行渲染。
建议将负责标记和渲染的代码与用于控制组件内容选择逻辑的代码分开。
这一理念得到了 HTL,一种模板语言,有意限制该语言,以确保使用真实的编程语言来定义底层业务逻辑。 此机制会突出显示为给定视图调用的代码,并在必要时,允许对同一组件的不同视图使用特定逻辑。
此(可选)逻辑可以通过不同方式实现,并可通过特定命令从HTL中调用:
AEM组件的结构强大而灵活。 主要部分包括:
结构的一个关键元素是资源类型。
这是一个抽象,有助于确保即使外观随时间而改变,意图也会保持不变。
组件的定义可按如下方式划分:
/libs/core/wcm/components
./apps/<myApp>/components
.cq:Component
并具有关键元素:
cq:Component
定义。<mycomponent> (cq:Component)
— 组件的层次结构节点。cq:editConfig (cq:EditConfig)
— 定义组件的编辑属性,并使组件显示在组件浏览器中
cq:childEditConfig (cq:EditConfig)
— 控制未定义其自身的子组件的创作UI方面 cq:editConfig
.cq:dialog (nt:unstructured)
— 此组件的对话框。 定义允许用户配置组件和/或编辑内容的界面。cq:design_dialog (nt:unstructured)
— 编辑此组件的设计组件的图标或缩写是在开发人员创建组件时,通过组件的JCR属性来定义的。 这些属性将按以下顺序计算,并使用找到的第一个有效属性。
cq:icon
— 指向 Coral用户界面库 在组件浏览器中显示
abbreviation
— 用于自定义组件浏览器中组件名称的缩写的字符串属性
jcr:title
属性。
abbreviation_commentI18n
属性,该属性随后用作翻译提示。cq:icon.png
或 cq:icon.svg
— 此组件的图标,该图标显示在组件浏览器中
.png
和 .svg
支持文件。_cq_icon.png
或 _cq_icon.svg
例如。.png
先例 .svg
如果两者都存在。如果上述属性均不存在(cq:icon
, abbreviation
, cq:icon.png
或 cq:icon.svg
)可在组件上找到:
sling:resourceSuperType
属性。jcr:title
当前组件的属性。要取消超级组件中图标的继承,请将 abbreviation
组件上的属性将还原为默认行为。
的 组件控制台 显示特定组件的图标的定义方式。
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www.w3.org/1999/xlink" x="0px" y="0px"
width="20px" height="20px" viewBox="0 0 20 20" enable-background="new 0 0 20 20" xml:space="preserve">
<ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
<ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
<ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
<ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>
定义组件所需的许多节点/属性对于两个UI都是通用的,其中差异仍保持独立,因此您的组件可以在这两个环境中工作。
组件是类型的节点 cq:Component
和具有以下属性和子节点:
名称 | 类型 | 描述 |
---|---|---|
. |
cq:Component |
这表示当前组件。 组件是节点类型 cq:Component . |
componentGroup |
String |
这表示可在其中选择组件的组 组件浏览器。 值以开头 . 用于无法从UI中进行选择的组件,例如其他组件从中继承的基础组件。 |
cq:isContainer |
Boolean |
这表示组件是否是容器组件,因此可以包含段落系统等其他组件。 |
cq:dialog |
nt:unstructured |
这是组件的编辑对话框的定义。 |
cq:design_dialog |
nt:unstructured |
这是组件的设计对话框的定义。 |
cq:editConfig |
cq:EditConfig |
这定义了 编辑组件的配置。 |
cq:htmlTag |
nt:unstructured |
这会返回添加到周围标记的其他标记属性HTML。 允许向自动生成的div中添加属性。 |
cq:noDecoration |
Boolean |
如果为true,则组件不会呈现为自动生成的div和css类。 |
cq:template |
nt:unstructured |
如果找到,则当从组件浏览器添加组件时,此节点将用作内容模板。 |
jcr:created |
Date |
这是组件的创建日期。 |
jcr:description |
String |
这是组件的描述。 |
jcr:title |
String |
这是组件的标题。 |
sling:resourceSuperType |
String |
设置后,组件会从此组件继承内容。 |
component.html |
nt:file |
这是组件的HTL脚本文件。 |
cq:icon |
String |
此值指向 组件的图标 和显示在组件浏览器中。 |
如果我们看看 文本 组件中,我们可以看到以下许多元素:
特定权益的物业包括:
jcr:title
— 这是用于在组件浏览器中标识组件的组件标题。jcr:description
— 此为组件的描述。sling:resourceSuperType
— 这表示扩展组件(通过覆盖定义)时的继承路径。特定感兴趣的子节点包括:
cq:editConfig
— 此操作可在编辑时控制组件的可视化方面。cq:dialog
— 这定义用于编辑此组件内容的对话框。cq:design_dialog
— 这可指定此组件的设计编辑选项。对话框是组件的关键元素,因为它们为作者提供了一个界面,用于在内容页面上配置组件并提供该组件的输入。 请参阅 创作文档 有关内容作者如何与组件交互的详细信息。
根据组件的复杂性,对话框可能需要一个或多个选项卡。
AEM组件的对话框:
cq:dialog
类型节点 nt:unstructured
.cq:Component
节点及其组件定义旁边。sling:resourceType
属性。nt:unstructured
,且为必需 sling:resourceType
属性。在对话框中,定义了各个字段:
设计对话框与用于编辑和配置内容的对话框类似,但它们为模板作者提供了界面,用于在页面模板上预配置和提供该组件的设计详细信息。 然后,内容作者使用页面模板来创建内容页面。 请参阅 模板文档 有关如何创建模板的详细信息。
编辑页面模板时使用设计对话框,但并非所有组件都需要这些参数。 例如, 标题 和 图像组件 都有设计对话框,而 社交媒体共享组件 不会。
Coral用户界面和Granite用户界面可定义AEM的外观。
Granite UI提供了在创作环境中创建对话框所需的一系列基本小组件。 必要时,您可以扩展此选择并创建自己的小组件。
有关更多详细信息,请参阅以下资源:
要创建在组件对话框中使用的新小组件,需要创建新的Granite UI字段组件。
如果将对话框视为表单元素的简单容器,则还可以将对话框内容的主要内容视为表单字段。 创建新表单字段需要创建资源类型;这等同于创建新组件。 为了帮助您完成该任务,Granite UI提供了一个要继承的通用字段组件(使用 sling:resourceSuperType
):
/libs/granite/ui/components/coral/foundation/form/field
更具体地说,Granite UI提供了一系列字段组件,这些组件适合在对话框中使用,或者更一般地适用于 表单。
创建资源类型后,您可以使用属性在对话框中添加新节点,以实例化字段 sling:resourceType
引用您刚才引入的资源类型。
您还可以使用渲染条件(rendercondition
)控制谁有权访问对话框中的特定选项卡/字段;例如:
+ mybutton
- sling:resourceType = granite/ui/components/coral/foundation/button
+ rendercondition
- sling:resourceType = myapp/components/renderconditions/group
- groups = ["administrators"]
创建组件后,您需要启用该组件才能使用它。 使用它可显示组件结构与存储库中生成内容的结构有何关系。
定义组件后,必须使其可供使用。 要使组件可在模板中使用,必须在模板布局容器的策略中启用该组件。
请参阅 模板文档 有关如何创建模板的详细信息。
如果我们创建并配置 标题 组件: /content/wknd/language-masters/en/adventures/extreme-ironing.html
然后,我们可以看到在存储库中创建的内容的结构:
特别是,如果您查看 标题组件:
jcr:title
属性,其中包含作者输入的标题的实际文本。sling:resourceType
引用组件定义。定义的属性取决于各个定义。 尽管它们可能比上面更复杂,但它们仍遵循相同的基本原则。
AEM中的组件受 资源类型层次结构. 用于使用属性扩展组件 sling:resourceSuperType
. 这允许组件继承其他组件。
请参阅部分 重用组件 以了解更多信息。
本节介绍如何配置组件的编辑行为。 这包括一些属性,例如组件可用的操作、in.place编辑器的特性,以及与组件上的事件相关的侦听器。
组件的编辑行为通过添加 cq:editConfig
类型节点 cq:EditConfig
组件节点下(类型 cq:Component
)和添加特定属性和子节点。 以下属性和子节点可用:
cq:editConfig
节点属性cq:editConfig
子节点:
cq:dropTargets
(节点类型) nt:unstructured
):定义可以接受内容查找器资产中删除的放置目标列表(允许单个放置目标)cq:inplaceEditing
(节点类型) cq:InplaceEditingConfig
):为组件定义就地编辑配置cq:listeners
(节点类型) cq:EditListenersConfig
):定义在组件上执行操作之前或之后发生的情况AEM中现有的配置很多。 您可以使用 CRXDE Lite.
组件必须始终呈现一些对作者可见的HTML,即使组件没有内容也是如此。 否则,它可能会从编辑器的界面中以可视方式消失,从而使其在技术上呈现,但在页面和编辑器中却不可见。 在这种情况下,作者将无法选择空组件并与之进行交互。
因此,只要组件在页面编辑器中呈现页面(当WCM模式为 edit
或 preview
)。
占位符的典型HTML标记如下所示:
<div class="cq-placeholder" data-emptytext="Component Name"></div>
呈现上述占位符HTML的典型HTL脚本如下所示:
<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}"
data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}"></div>
在上一个示例中, isEmpty
是一个变量,仅当组件没有内容且作者不可见时,才为true。
为避免重复,Adobe建议组件实施人员对这些占位符使用HTL模板。 与核心组件提供的类似。
然后,使用以下HTL行完成模板在上一个链接中的使用:
<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html"
data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly>
在上一个示例中, model.text
是仅当内容包含且可见时才为true的变量。
可在核心组件中查看此模板的使用示例, 例如在标题组件中。
的 cq:dropTargets
节点(节点类型) nt:unstructured
)定义可接受从内容查找器中拖动的资产中拖放的放置目标。 它是类型的节点 cq:DropTargetConfig
.
类型的子节点 cq:DropTargetConfig
在组件中定义放置目标。
就地编辑器允许用户直接在内容流中编辑内容,而无需打开对话框。 例如, 文本 和 标题 组件均具有嵌入式编辑器。
对于每种组件类型,并非都需要/有意义的就地编辑器。
的 cq:inplaceEditing
节点(节点类型) cq:InplaceEditingConfig
)为组件定义就地编辑配置。 它可以具有以下属性:
属性名称 | 属性类型 | 属性值 |
---|---|---|
active |
Boolean |
true 以启用组件的就地编辑。 |
configPath |
String |
编辑器配置的路径,可由配置节点指定 |
editorType |
String |
可用类型包括: plaintext 对于非HTML内容, title 在开始编辑之前将图形标题转换为纯文本,并 text 使用富文本编辑器 |
以下配置允许对组件进行嵌入式编辑,并定义 plaintext
作为编辑器类型:
<cq:inplaceEditing
jcr:primaryType="cq:InplaceEditingConfig"
active="{Boolean}true"
editorType="plaintext"/>
处理对话框字段中事件的方法在自定义中通过监听器完成 客户端库。
要在字段中插入逻辑,您应:
要实现此目的,您需要了解要与之交互的底层小组件库。 请参阅Coral用户界面文档 以确定要对哪个事件做出反应。
的 cq:listeners
节点(节点类型) cq:EditListenersConfig
)定义对组件执行操作之前或之后所发生的情况。 下表定义了其可能的属性。
属性名称 | 属性值 |
---|---|
beforedelete |
处理程序在删除组件之前触发。 |
beforeedit |
处理程序在编辑组件之前触发。 |
beforecopy |
在复制组件之前触发处理程序。 |
beforeremove |
在移动组件之前触发处理程序。 |
beforeinsert |
在插入组件之前触发处理程序。 |
beforechildinsert |
在将组件插入其他组件(仅限容器)之前,会触发处理程序。 |
afterdelete |
处理程序在删除组件后触发。 |
afteredit |
编辑组件后会触发处理程序。 |
aftercopy |
处理程序在复制组件后触发。 |
afterinsert |
在插入组件后触发处理程序。 |
aftermove |
处理程序在组件移动后触发。 |
afterchildinsert |
将组件插入另一个组件(仅限容器)后,将触发处理程序。 |
对于嵌套的组件,对于定义为 cq:listeners
节点。 对于嵌套的组件,以下属性的值 必须 be REFRESH_PAGE
:
aftermove
aftercopy
事件处理程序可以通过自定义实施来实施。 例如(其中 project.customerAction
是静态方法):
afteredit = "project.customerAction"
以下示例等效于 REFRESH_INSERTED
配置:
afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"
通过以下配置,在删除、编辑、插入或移动组件后会刷新页面:
<cq:listeners
jcr:primaryType="cq:EditListenersConfig"
afterdelete="REFRESH_PAGE"
afteredit="REFRESH_PAGE"
afterinsert="REFRESH_PAGE"
afterMove="REFRESH_PAGE"/>
在Granite UI和Granite UI小组件中,使用 foundation-validation
API。 请参阅 foundation-valdiation
Granite文档 以了解详细信息。
如果您有自定义JavaScript,并且需要仅在对话框可用且准备就绪后才执行,则应当监听 dialog-ready
事件。
当对话框加载(或重新加载)并准备就绪以供使用时,将触发此事件,这意味着每当对话框的DOM中发生更改(创建/更新)时。
dialog-ready
可用于挂接JavaScript自定义代码,该代码可对对话框或类似任务中的字段执行自定义。
的 WCM模式 在切换到预览模式时,即使页面未刷新,也会设置cookie。
对于呈现的对WCM模式敏感的组件,需要定义它们以专门刷新它们,然后依赖Cookie的值。
作为开发人员,您希望轻松访问组件文档,以便快速了解组件的以下功能:
因此,很容易就会在组件中使用您现有的任何文档标记。
你只需在 README.md
文件。
然后,此标记将显示在 组件控制台。
支持的Markdown与 内容片段.