组件是在AEM构建体验的核心。 核心组件和AEM项目原型使您能轻松开始使用一套现成的、强大的组件。 WKND Tutorial将指导开发人员如何使用这些工具以及如何构建自定义组件以创建新的AEM站点。
由于WKND教程涵盖大多数使用案例,因此此文档仅作为这些资源的补充。 它详细说明了组件在AEM中的结构和配置方式,并非作为入门指南。
本部分介绍开发您自己的组件时所需的详细信息,包括主要概念和问题。
在开始实际配置或编码组件之前,您应该询问:
在花费时间创建全新组件之前,请考虑自定义或扩展现有组件。 核心组 件提供一套灵活、强大且经过测试的生产就绪型组件。
核心组件还优惠清晰的自定义模式,您可以使用这些模式根据您自己的项目的需要进行调整。
还可以基于搜索路径逻辑使用叠加来重新定义组件。 但是,在这种情况下,将不会触发Sling资源合并,并且/apps
必须定义整个叠加。
也可以使用Sling Resource Merage(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 UI库中标准图标的字符串属 性, 要在组件浏览器中显示
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 |
此值指向组件](#component-icon)的[图标,并显示在组件浏览器中。 |
如果我们查看Text组件,可以看到以下许多元素:
特定权益的物业包括:
jcr:title
-这是用于在组件浏览器中标识组件的组件的标题。jcr:description
-这是组件的说明。sling:resourceSuperType
-这表示在扩展组件(通过覆盖定义)时的继承路径。特定感兴趣的子节点包括:
cq:editConfig
-此操作控制编辑时组件的可视方面。cq:dialog
-这定义用于编辑此组件内容的对话框。cq:design_dialog
-它指定此组件的设计编辑选项。对话框是组件的关键元素,因为它们为作者提供了在内容页面上配置组件并提供该组件的输入的界面。 有关内容作者如何与组件交互的详细信息,请参阅创作文档。
根据组件的复杂性,对话框可能需要一个或多个选项卡。
AEM组件的对话框:
cq:dialog
类型nt:unstructured
的节点。cq:Component
节点下,并位于其组件定义旁。sling:resourceType
属性呈现服务器端(作为Sling组件)。nt:unstructured
,具有必需的sling:resourceType
属性。在对话框中,定义了单个字段:
设计对话框与用于编辑和配置内容的对话框类似,但它们为模板作者提供了界面,用于在页面模板上预配置和提供该组件的设计详细信息。 然后,内容作者使用页面模板创建内容页面。 有关如何创建模板的详细信息,请参阅模板文档。
编辑页面模板时会使用设计对话框,但并非所有组件都需要设计对话框。例如,标题和图像组件都具有设计对话框,而社交媒体共享组件没有。
Coral UI和Granite UI定义AEM的外观。
Granite UI提供了在创作环境下创建对话框所需的大量基本构件。 必要时,您可以扩展此选择并创建您自己的构件。
有关其他详细信息,请参阅以下资源:
有关自定义对话框字段,请参见AEM Gems会话。
要创建要在组件对话框中使用的新构件,需要创建新的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"]
创建组件后,您需要启用它才能使用它。 使用它可显示组件结构与存储库中生成内容的结构之间的关系。
定义组件后,必须允许其使用。 要使组件可在模板中使用,必须在模板的布局容器策略中启用该组件。
有关如何创建模板的详细信息,请参阅模板文档。
如果我们在页面上创建并配置Title组件的实例:/content/wknd/language-masters/en/adventures/extreme-ironing.html
然后,我们可以看到在存储库中创建的内容的结构:
尤其是,如果您查看标题组件的实际文本:
jcr:title
属性,其中包含作者输入的标题的实际文本。sling:resourceType
引用。定义的属性取决于各个定义。 虽然比起上面更复杂,但也遵循相同的基本原则。
AEM中的组件受资源类型层次结构的约束。 它用于使用属性sling:resourceSuperType
扩展组件。 这允许组件继承其他组件。
有关详细信息,请参阅重用组件一节。
本节介绍如何配置组件的编辑行为。 这包括可用于组件的操作、in.place编辑器的特性以及与组件上的事件相关的监听器等属性。
通过在组件节点(类型cq:Component
)下添加cq:editConfig
类型cq:EditConfig
的节点,并添加特定属性和子节点,可配置组件的编辑行为。 以下属性和子节点可用:
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
的子节点定义组件中的放置目标。
就地编辑器允许用户直接在内容流中编辑内容,无需打开对话框。 例如,标准Text和Title组件都具有内置编辑器。
对于每个组件类型,就地编辑器并非必需/有意义。
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 UI文 档,以确定要对哪个事件做出反应。
cq:listeners
节点(节点类型cq:EditListenersConfig
)定义在组件上执行操作之前或之后发生的情况。 下表定义了其可能的属性。
属性名称 | 属性值 |
---|---|
beforedelete |
在删除组件之前将触发处理程序。 |
beforeedit |
在编辑组件之前将触发该处理函数。 |
beforecopy |
在复制组件之前将触发该处理函数。 |
beforeremove |
在移动组件之前触发处理程序。 |
beforeinsert |
在插入组件之前将触发处理程序。 |
beforechildinsert |
在将组件插入另一个组件之前,将触发该处理程序(仅容器)。 |
afterdelete |
删除组件后将触发处理程序。 |
afteredit |
编辑组件后将触发处理程序。 |
aftercopy |
在复制组件后将触发处理程序。 |
afterinsert |
插入组件后将触发处理程序。 |
aftermove |
在移动组件后将触发处理程序。 |
afterchildinsert |
该处理函数在组件插入另一个组件后触发(仅容器)。 |
对于嵌套组件,对于定义为cq:listeners
节点上的属性的操作有一些限制。 对于嵌套组件,以下属性的值必须为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
文件放入组件结构中。
此标记随后将显示在组件控制台中。
支持的标记与内容片段的标记相同。