AEM组件 — 基础

开始开发新组件时,您需要了解其结构和配置的基础知识。

此过程涉及阅读理论并查看标准AEM实例中的各种组件实现。 后一种方法略有复杂,因为尽管AEM已转向新的标准、新式触屏优化UI,但它仍支持经典UI。

概述

本节介绍开发自己的组件时所需的详细信息,包括主要概念和问题。

规划

在开始实际配置或编码您的组件之前,您应该询问:

  • 您到底需要新组件做什么?

    • 清晰的规范有助于开发、测试和移交的所有阶段。

      详细信息可能随时间而改变,但规范可以更新(但更改也应记录在案)。

  • 您是需要从头开始创建组件,还是可以从现有组件继承基础知识?

    • 没有必要再费力去开发一个。
    • AEM提供了多种机制,允许您继承和扩展其他组件定义的详细信息,包括覆盖、叠加和Sling Resource Mergare
  • 您的组件是否需要选择/操作内容的逻辑?

    • 逻辑应与用户界面层分开。 HTL旨在帮助确保此情况发生。
  • 您的组件是否需要CSS格式?

    • CSS格式应与组件定义分开。 定义命名HTML元素的约定,以便通过外部CSS文件修改它们。
  • 我应该考虑哪些安全方面?

触屏优化与经典UI

在进行任何有关开发组件的严肃讨论开始之前,您需要了解作者将使用的UI:

  • 触屏优化 UI
    AEM 5. 6.0中作为预览引入并在6.x中扩展的标准用户界面。它基于Adobe Marketing Cloud的统一用户体验,使用Coral UI和Granite UI 层技术


  • 于ExtJS技术的经典UIser接口,CQ 5.1中引入了该接口。

有关详细信息,请参阅客户的UI界面Recommendations

可以实施组件以支持触屏优化UI和经典UI,也可以同时支持这两者。 查看标准实例时,您还会看到最初为经典UI或触屏优化UI设计的现成组件,或者两者兼有。

因此,本页中将介绍这两种工具的基础知识以及如何识别它们。

注意

Adobe建议利用触屏优化UI从最新技术中受益。 AEM Moderization Toolscan使迁移更简单。

内容逻辑和渲染标记

建议将负责标记和渲染的代码与控制用于选择组件内容的逻辑的代码分开。

此理念得到HTL的支持,该模板语言被有意限制以确保使用真正的编程语言来定义底层业务逻辑。 此(可选)逻辑从HTL中使用特定命令调用。 此机制会突出显示为给定视图调用的代码,并根据需要允许为同一组件的不同视图使用特定逻辑。

HTL与JSP

HTL是AEM 6.0引入的HTML模板语言。

开发您自己的组件时是否使用HTL或JSP(Java Server Pages)的讨论应该很简单,因为HTL现在是AEM的推荐脚本语言。

HTL和JSP都可用于为经典和触屏优化UI开发组件。 尽管有一种倾向认为HTL仅适用于经典UI的触屏优化UI和JSP,但这是一种误解,更多是由于时间原因。 触屏优化UI和HTL大约在同一时间段内并入AEM。 由于现在推荐使用HTL语言,因此它用于新组件,而新组件通常用于触屏优化UI。

注意

除Granite UI基础表单域(在对话框中使用)外。 这些仍需使用JSP。

开发您自己的组件

要为相应的UI创建您自己的组件,请参阅(在阅读此页面后):

快速入门的方法是复制现有组件,然后进行所需的更改。 要了解如何创建您自己的组件并将其添加到段落系统,请参阅:

将组件移到Publish实例

渲染内容的组件必须部署在与内容相同的AEM实例上。 因此,必须在发布实例上部署用于创作和呈现页面的所有组件。 部署后,组件可用于呈现已激活的页面。

使用以下工具将组件移动到发布实例:

注意

这些机制还可用于在其他实例之间传输组件,例如从开发到测试实例。

要从开始中识别的组件

  • 页面:

    • AEM具有​page​组件(cq:Page)。
    • 这是对内容管理很重要的特定类型的资源。
      • 页面对应于包含网站内容的网页。
  • 段落系统:

    • 段落系统是网站的关键部分,因为它管理段落列表。 它用于保存和构建保存实际内容的各个组件。
    • 您可以在段落系统中创建、移动、复制和删除段落。
    • 您还可以选择可在特定段落系统中使用的组件。
    • 标准实例中有各种可用的段落系统(例如parsys [responsivegrid](/docs/experience-manager-64/sites-authoring/responsive-layout.html?lang=zh-Hans))。

结构

AEM组件的结构强大而灵活,主要考虑事项有:

  • 资源类型
  • 组件定义
  • 组件的属性和子节点
  • 对话框
  • 设计对话框
  • 组件可用性
  • 组件及其创建的内容

资源类型

结构的关键元素是资源类型。

  • 内容结构声明意图。
  • 资源类型将实现它们。

这是一个抽象,有助于确保即使外观随着时间而改变,意图也会保持时间。

组件定义

组件基础知识

组件的定义可以按如下方式划分:

  • AEM组件基于Sling

  • AEM组件位于(通常位于)下:

    • HTL: /libs/wcm/foundation/components
    • JSP:/libs/foundation/components
  • 项目/站点特定组件(通常)位于:

    • /apps/<myApp>/components
  • AEM标准组件定义为cq:Component,并具有以下关键元素:

    • jcr属性:

      一列表jcr属性;这些是变量,某些是可选的,尽管组件节点的基本结构,其属性和子节点由cq:Component定义定义

    • 资源:

      这些组件定义组件使用的静态元素。

    • 脚本:

    用于实现组件的结果实例的行为。

  • 根节点:

    • <mycomponent> (cq:Component) — 组件的层次结构节点。
  • 重要属性:

    • jcr:title — 组件标题;例如,当组件在组件浏览器或Sidekick中列出时,用作标签。

    • jcr:description — 组件说明;可用作组件浏览器或Sidekick中的鼠标悬停提示。

    • 经典 UI:

      • icon.png — 此组件的图标。
      • thumbnail.png — 如果此组件列在段落系统中,则显示的图像。
    • 触屏 UI

      • 有关详细信息,请参阅Touch UI🔗中的组件图标部分。
  • 重要子节点:

    • cq:editConfig (cq:EditConfig) — 定义组件的编辑属性,并允许组件显示在组件浏览器或Sidekick中。

      注意:如果组件包含对话框,则它将自动显示在组件浏览器或Sidekick中,即使cq:editConfig不存在也是如此。

    • cq:childEditConfig (cq:EditConfig) — 控制未定义其自身的子组件的创作UI方面 cq:editConfig

    • 触屏优化 UI:

      • cq:dialog ( nt:unstructured) — 此组件的对话框。定义允许用户配置组件和/或编辑内容的界面。
      • cq:design_dialog ( nt:unstructured) — 此组件的设计编辑
    • 经典 UI:

      • dialog ( cq:Dialog) — 此组件的对话框。定义允许用户配置组件和/或编辑内容的界面。
      • design_dialog ( cq:Dialog) — 设计编辑此组件。

触屏UI中的组件图标

当开发人员创建组件时,组件的图标或缩写是通过组件的JCR属性定义的。 这些属性按以下顺序计算,并使用找到的第一个有效属性。

  1. cq:icon — 指向要在组件浏览器中显示的Coral UI库 中标 准图标的字符串属性

    • 使用Coral图标的HTML属性值。
  2. abbreviation - String属性,用于自定义组件浏览器中组件名称的缩写

    • 缩写应限于两个字符。

    • 如果提供空字符串,将从jcr:title属性的前两个字符生成缩写。

      • 例如,“Image”的“Im”
      • 本地化标题将用于构建缩写。
    • 仅当组件具有abbreviation_commentI18n属性时,缩写才被翻译,然后该属性用作翻译提示。

  3. cq:icon.png 或 — cq:icon.svg 此组件的图标,该图标显示在组件浏览器中

    • 20 x 20像素是标准组件图标的大小。

      • 将缩小较大的图标(客户端)。
    • 建议的颜色为rgb(112, 112, 112)> #707070

    • 标准组件图标的背景是透明的。

    • 仅支持.png.svg文件。

    • 如果通过Eclipse插件从文件系统导入,则文件名需要转义为_cq_icon.png_cq_icon.svg

    • .png 如果两者都 .svg 存在,就先例

如果在组件上找不到上述属性(cq:iconabbreviationcq:icon.pngcq:icon.svg):

  • 系统将在超级组件上搜索与sling:resourceSuperType属性后相同的属性。
  • 如果在超级组件级别找不到任何缩写或空缩写,则系统将从当前组件的jcr:title属性的第一个字母构建缩写。

要取消超级组件中图标的继承,在组件上设置空abbreviation属性将恢复为默认行为。

组件控制台显示如何定义特定组件的图标。

SVG图标示例

<?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)或Sidekick(经典UI)中选择组件的组。
某个值用 .hidden 于无法从UI(例如实际段落系统)中进行选择的组件。
cq:isContainer Boolean 指示该组件是否为容器组件,因此可包含其他组件,如段落系统。
cq:dialog nt:unstructured 触屏优化UI的编辑对话框定义。
dialog cq:Dialog 经典UI的编辑对话框的定义。
cq:design_dialog nt:unstructured 触屏优化UI的设计对话框的定义。
design_dialog cq:Dialog 经典UI的设计对话框的定义。
dialogPath String 当组件没有对话框节点时要涵盖该情况的对话框路径。
cq:cellName String 如果设置,则此属性将作为单元格ID。 有关详细信息,请参阅知识库文章如何构建设计单元格ID
cq:childEditConfig cq:EditConfig 当组件是容器(例如段落系统)时,这将驱动子节点的编辑配置。
cq:editConfig cq:EditConfig 编辑组件的配置
cq:htmlTag nt:unstructured 返回添加到周围html标签的其他标签属性。 允许向自动生成的显示添加属性。
cq:noDecoration Boolean 如果为true,则不使用自动生成的div和css类呈现组件。
cq:template nt:unstructured 如果找到此节点,则当从组件浏览器或Sidekick添加组件时,此节点将用作内容模板。
cq:templatePath String 当从组件浏览器或Sidekick添加组件时,要用作内容模板的节点的路径。 这必须是绝对路径,而不是相对于组件节点。
除非您希望重复使用其他位置已有的内容,否则这不是必需的,而 cq:template 且已足够(请参阅下文)。
jcr:created Date 组件的创建日期。
jcr:description String 组件说明。
jcr:title String 组件的标题。
sling:resourceSuperType String 设置后,组件会从此组件继承内容。
virtual sling:Folder 支持创建虚拟组件。 要查看示例,请访问以下联系人组件:
/libs/foundation/components/profile/form/contact
<breadcrumb.jsp> nt:file 脚本文件。
icon.png nt:file 组件的图标,显示在Sidekick中标题的旁边。
thumbnail.png nt:file 从Sidekick将组件拖动到位时显示的可选缩略图。

如果我们查看​Text​组件(任一版本),可以看到以下元素:

  • HTL ( /libs/wcm/foundation/components/text)

    chlimage_1-241

  • JSP(/libs/foundation/components/text)

    screen_shot_2012-02-13at60457pm

特定权益物业包括:

  • jcr:title — 组件标题;这可用于标识组件,例如,组件列表中显示在组件浏览器或Sidekick中的组件

  • jcr:description — 组件说明;可用作sidekick中组件列表中的鼠标悬停提示

  • sling:resourceSuperType:这表示在扩展组件(通过覆盖定义)时继承的路径

特别感兴趣的子节点包括:

  • cq:editConfig ( cq:EditConfig — 此控制视觉方面;例如,它可以定义条形或构件的外观,也可以添加自定义控件

  • cq:childEditConfig ( cq:EditConfig) — 这控制子组件没有其自己定义的可视方面

  • 触屏优化 UI:

    • cq:dialog ( nt:unstructured) — 定义用于编辑此组件内容的对话框
    • cq:design_dialog ( nt:unstructured) — 指定此组件的设计编辑选项
  • 经典 UI:

    • dialog ( cq:Dialog) — 定义用于编辑此组件内容的对话框(特定于经典UI)
    • design_dialog ( cq:Dialog) — 指定此组件的设计编辑选项
    • icon.png — 图形文件,用作Sidekick中组件的图标
    • thumbnail.png — 从Sidekick拖动组件时用作组件缩略图的图形文件

对话框

对话框是组件的关键元素,因为它们为作者提供了一个界面,供其配置和向该组件提供输入。

根据组件的复杂性,您的对话框可能需要一个或多个选项卡 — 以使对话框保持简短并对输入字段进行排序。

对话框定义特定于UI:

注意
  • 出于兼容性考虑,当未为触屏优化UI定义对话框时,触屏优化UI可以使用经典UI对话框的定义。
  • 还提供了AEM现代化工具,以帮助您扩展/转换仅为经典UI定义了对话框的组件。
  • 触屏优化 UI

    • cq:dialog ( nt:unstructured节点):

      • 定义用于编辑此组件内容的对话框

      • 特定于触屏优化UI

      • 是使用Granite UI组件定义的

      • 具有属性sling:resourceType,作为标准Sling内容结构

      • 可以具有属性helpPath来定义当帮助图标(? 图标)。

        • 对于开箱即用的组件,这通常引用文档中的页面。
        • 如果未指定helpPath,则显示默认URL(文档概述页面)。

    chlimage_1-242

    在对话框中,定义了单个字段:

    screen_shot_2012-02-13at60937pm

  • 经典 UI

    • dialog ( cq:Dialog)节点

      • 定义用于编辑此组件内容的对话框

      • 特定于经典UI

      • 是使用ExtJS构件定义的

      • 具有xtype属性,该属性引用ExtJS

      • 可以具有属性helpPath来定义选择​帮助​按钮时访问的上下文相关帮助资源(绝对或相对路径)。

        • 对于开箱即用的组件,这通常引用文档中的页面。
        • 如果未指定helpPath,则显示默认URL(文档概述页面)。

    chlimage_1-243

    在对话框中,定义了单个字段:

    chlimage_1-244

    在经典对话框中:

    • 您可以创建cq:Dialog对话框,该对话框将提供单个选项卡 — 如文本组件中所示,或者,如果您需要多个选项卡,如textimage组件所示,该对话框可定义为cq:TabPanel
    • a cq:WidgetCollection(items)用于为输入字段(cq:Widget)或更多选项卡(cq:Widget)提供基。 可以扩展此层次结构。

设计对话框

设计对话框与用于编辑和配置内容的对话框非常相似,但它们为作者提供了配置和提供该组件设计详细信息的界面。

设计对话框在设计模式中可用,但并非所有组件(如“标题”和“图像”)都 ​有 ​设计对话框,而文本则 ​不需要。

段落系统(例如parsys)的设计对话框是一个特例,因为它允许用户在页面上选择特定的其他组件(从组件浏览器或Sidekick中)。

将组件添加到段落系统

定义组件后,必须使组件可供使用。 要使组件可用于段落系统,您可以执行以下任一操作:

  1. 打开页面的设计模式并启用所需的组件。

  2. 将所需的组件添加到模板定义的components属性中:

    /etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par

    例如,请参阅:

    /etc/designs/geometrixx/jcr:content/contentpage/par

    chlimage_1-245

组件及其创建的内容

如果我们在页面上创建并配置​Title​组件的实例:<content-path>/Prototype.html

  • 触屏优化 UI

    chlimage_1-246

  • 经典 UI

    screen_shot_2012-02-01at34257pm

然后,我们可以看到在存储库中创建的内容的结构:

screen_shot_2012-02-13at61405pm

尤其是,如果您查看​Title​的实际文本:

  • 定义(对于两个UI)具有属性name= ./jcr:title

    • /libs/foundation/components/title/cq:dialog/content/items/column/items/title
    • /libs/foundation/components/title/dialog/items/title
  • 在内容中,它会生成包含作者内容的属性jcr:title

定义的属性取决于各个定义。 尽管它们可能比之前更为复杂,但它们仍遵循相同的基本原则。

组件层次和继承

AEM中的组件受3个不同层次的约束:

  • 资源类型层次结构

    这用于使用属性sling:resourceSuperType扩展组件。 这允许组件继承。 例如,文本组件将从标准组件继承各种属性。

    • 脚本(由Sling解析)
    • 对话
    • 描述(包括缩略图图像、图标等)
  • 容器层次

    它用于将配置设置填充到子组件,最常用于parsys方案。

    例如,可以在父组件上定义编辑栏按钮、控制集布局(编辑栏、翻转)、对话框布局(内联、浮动)的配置设置并传播到子组件。

    将传播cq:editConfigcq:childEditConfig中的配置设置(与编辑功能相关)。

  • 包括层次

    在运行时,这由包含序列强加。

    该层次结构由设计人员使用,而设计人员又作为渲染各个设计方面的基础;包括布局信息、css信息、parsys中的可用组件等。

编辑行为

本节介绍如何配置组件的编辑行为。 这包括一些属性,如可用于组件的操作、就地编辑器的特性以及与组件上的事件相关的侦听器。

该配置对触屏优化UI和经典UI都是通用的,尽管有某些特定的差异。

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

  • cq:editConfig 节点属性:

    • cq:actions ( String array):定义可对组件执行的操作。

    • cq:layout ( String)::定义如何在经典UI中编辑组件。

    • cq:dialogMode ( String):定义组件对话框在经典UI中的打开方式

      • 在触屏优化UI中,对话框始终在桌面模式下浮动,并在移动设备中自动以全屏方式打开。
    • cq:emptyText ( String):定义在不存在可视内容时显示的文本。

    • cq:inherit ( Boolean):定义是否从它继承的组件继承了缺失值。

    • dialogLayout (字符串):定义对话框的打开方式。

  • cq:editConfig 子节点:

    • cq:dropTargets (节点类 nt:unstructured型):定义放置列表目标,以接受从内容查找器的资产中放置

      • 多个拖放目标仅在经典UI中可用。
      • 在触屏优化UI中,允许使用单次放置目标。
    • cq:actionConfigs (节点类 nt:unstructured型):定义附加到cq:actions列表的新操作列表。

    • cq:formParameters (节点类 nt:unstructured型):定义添加到对话框表单的其他参数。

    • cq:inplaceEditing (节点类 cq:InplaceEditingConfig型):为组件定义就地编辑配置。

    • cq:listeners (节点类 cq:EditListenersConfig型):定义在组件上执行操作之前或之后发生的情况。

注意

在本页中,一个节点(属性和子节点)表示为XML,如以下示例中所示。

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afteredit="REFRESH_PAGE"/>
</jcr:root>

存储库中有许多现有配置。 您可以轻松搜索特定属性或子节点:

  • 要查找cq:editConfig节点的属性,例如cq:actions,您可以在​CRXDE Lite​中使用查询工具,并使用以下XPath查询字符串进行搜索:

    //element(cq:editConfig, cq:EditConfig)[@cq:actions]

  • 要查找cq:editConfig的子节点,例如,可以搜索cq:dropTargets,该节点的类型为cq:DropTargetConfig;您可以在 CRXDE Lite​中使用查询工具,并使用以下XPath查询字符串进行搜索:

    //element(cq:dropTargets, cq:DropTargetConfig)

组件占位符

组件必须始终呈现作者可见的某些HTML,即使组件没有内容也是如此。 否则,它可能会从编辑器的界面中以可视方式消失,从而使它在技术上存在,但在页面和编辑器中不可见。 在这种情况下,作者将无法选择空组件并与之交互。

因此,当页面在页面编辑器中呈现时(当WCM模式为editpreview时),组件应呈现占位符,只要它们不呈现任何可见输出。
占位符的典型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:EditConfig属性进行配置

cq:actions

cq:actions属性(String array)定义可对组件执行的一个或多个操作。 以下值可用于配置:

属性值 描述
text:<some text> 显示静态文本值<some text>
仅在经典UI中可见。 触屏优化UI不在上下文菜单中显示动作,因此不适用。
- 添加间隔符。
仅在经典UI中可见。触屏优化UI不在上下文菜单中显示动作,因此不适用。
edit 添加用于编辑组件的按钮。
editannotate 添加一个按钮以编辑组件并允许注释
delete 添加用于删除组件的按钮
insert 在当前组件之前添加一个按钮以插入新组件
copymove 添加一个按钮以复制和剪切组件。

以下配置将编辑按钮、分隔条、删除和插入按钮添加到组件编辑栏:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit,-,delete,insert]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

以下配置将文本“从Base Framework继承的配置”添加到组件编辑栏:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[text:Inherited Configurations from Base Framework]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

cq:layout(仅限经典UI)

cq:layout属性(String)定义如何在经典UI中编辑组件。 以下值可用:

属性值 描述
rollover 默认值。 组件版本可通过单击和/或上下文菜单“鼠标悬停”访问。
对于高级使用,请注意相应的客户端对象是: CQ.wcm.EditRollover.
editbar 组件版本可通过工具栏访问。
对于高级使用,请注意相应的客户端对象是: CQ.wcm.EditBar.
auto 选择由客户端代码决定。
注意

翻转和编辑栏的概念在触屏优化UI中不适用。

以下配置会向组件编辑栏中添加一个编辑按钮:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:dialogMode(仅限经典UI)

组件可以链接到编辑对话框。 cq:dialogMode属性(String)定义如何在经典UI中打开组件对话框。 以下值可用:

属性值 描述
floating 对话框是浮动的。
inline (默认值). 对话框锚定在组件上。
auto 如果组件宽度小于客户端CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH值,则对话框是浮动的,否则它是内联的。
注意

在触屏优化UI中,对话框始终在桌面模式下浮动,并在移动设备中自动以全屏方式打开。

以下配置定义了一个带有编辑按钮的编辑栏和一个浮动对话框:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:emptyText

cq:emptyText属性(String)定义在不存在可视内容时显示的文本。 默认为:Drag components or assets here

cq:inherit

cq:inherit属性(boolean)定义是否从其继承的组件继承了缺少的值。 默认为false

dialogLayout

默认情况下,dialogLayout属性定义如何打开对话框。

  • fullscreen将全屏打开对话框。
  • 默认值为空或缺少属性,以正常打开对话框。
  • 请注意,用户始终可以在对话框中切换全屏模式。
  • 不适用于经典UI。

使用cq:EditConfig子节点进行配置

cq:dropTargets

cq:dropTargets节点(节点类型nt:unstructured)定义了放置目标列表,该可以接受从内容查找器中拖动的资产中的放置。 它用作cq:DropTargetConfig类型节点的集合。

注意

多个拖放目标仅在经典UI中可用。

在触屏优化UI中,仅使用第一个目标。

类型cq:DropTargetConfig的每个子节点定义组件中的放置目标。 节点名很重要,因为必须在JSP中使用它,以生成分配给DOM元素(作为有效放置目标)的CSS类名:

<drop target css class> = <drag and drop prefix> + 
 <node name of the drop target in the edit configuration>

<*drag and drop prefix*>由Java属性定义:

com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX

例如,类名称在下载组件的JSP中定义如下
(/libs/foundation/components/download/download.jsp),其中file是“下载”组件编辑配置中放置目标的节点名:

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

类型cq:DropTargetConfig的节点需要具有以下属性:

属性名称 属性值
accept 对资产mime类型应用的正则表达式,以验证是否允许删除。
groups 放置目标组的数组。 每个组必须与内容查找器扩展中定义的、附加到资产的组类型相匹配。
propertyName 在有效删除后将更新的属性的名称。

以下配置是从下载组件中进行的。 它允许将media组中的任何资产(mime类型可以是任何字符串)从内容查找器拖放到组件中。 放置后,组件属性fileReference正在更新:

    <cq:dropTargets jcr:primaryType="nt:unstructured">
        <file
            jcr:primaryType="cq:DropTargetConfig"
            accept="[.*]"
            groups="[media]"
            propertyName="./fileReference"/>
    </cq:dropTargets>

cq:actionConfigs(仅限经典UI)

cq:actionConfigs节点(节点类型nt:unstructured)定义新操作的列表,这些操作附加到由cq:actions属性定义的列表。 cq:actionConfigs的每个子节点通过定义Widget定义新操作。

以下示例配置定义了一个新按钮(带经典UI的分隔符):

  • 由xtype tbseparator定义的分隔符;

    • 仅经典UI使用。
    • 触屏优化UI会忽略此定义,因为xtypes会被忽略(而且,由于在触屏优化UI中以不同方式构建操作工具栏,因此不必使用分隔符)。
  • 名为​管理注释​的按钮,该按钮运行处理函数CQ_collab_forum_openCollabAdmin()

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
    cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
    jcr:primaryType="cq:EditConfig">
    <cq:actionConfigs jcr:primaryType="nt:unstructured">
        <separator0
            jcr:primaryType="nt:unstructured"
            xtype="tbseparator"/>
        <manage
            jcr:primaryType="nt:unstructured"
            handler="function(){CQ_collab_forum_openCollabAdmin();}"
            text="Manage comments"/>
    </cq:actionConfigs>
</jcr:root>
注意

请参阅将新操作添加到组件工具栏作为触屏优化UI的示例。

cq:formParameters

cq:formParameters节点(节点类型nt:unstructured)定义添加到对话框表单的其他参数。 每个属性都映射到一个表单参数。

以下配置将名为name的参数(用值photos/primary设置)添加到对话框表单中:

    <cq:formParameters
        jcr:primaryType="nt:unstructured"
        name="photos/primary"/>

cq:inplaceEditing

cq:inplaceEditing节点(节点类型cq:InplaceEditingConfig)为组件定义就地编辑配置。 它可以具有以下属性:

属性名称 属性值
active (boolean)为True可启用组件的就地编辑。
configPath (String)编辑器配置的路径。 配置节点可以指定配置。
editorType

(String)编辑器类型。 可用类型有:

  • 纯文本:用于非HTML内容。
  • title:是一种增强的纯文本编辑器,在开始编辑之前,可将图形字幕转换为纯文本。 由Geometrixx标题组件使用。
  • 文本:用于HTML内容(使用富文本编辑器)。

以下配置启用了组件的就地编辑,并将plaintext定义为编辑器类型:

    <cq:inplaceEditing
        jcr:primaryType="cq:InplaceEditingConfig"
        active="{Boolean}true"
        editorType="plaintext"/>

cq:listeners

cq:listeners节点(节点类型cq:EditListenersConfig)定义在组件上执行操作之前或之后发生的情况。 下表定义了其可能的属性。

属性名称 属性值

默认值

(仅限经典UI)

beforedelete 在删除组件之前触发处理函数。
beforeedit 在编辑组件之前将触发该处理函数。
beforecopy 在复制组件之前触发处理函数。
beforemove 在移动组件之前触发处理函数。
beforeinsert 在插入组件之前触发处理函数。
仅适用于触屏优化UI。
beforechildinsert 该处理函数是在组件插入另一个组件之前触发的(仅容器)。
afterdelete 该处理函数在删除组件后触发。 REFRESH_SELF
afteredit 编辑组件后将触发该处理函数。 REFRESH_SELF
aftercopy 该处理函数在复制组件后触发。 REFRESH_SELF
afterinsert 插入组件后将触发处理函数。 REFRESH_INSERTED
aftermove 处理函数在移动组件后触发。 REFRESH_SELFMOVED
afterchildinsert 该处理函数是在组件插入另一个组件后触发的(仅容器)。
注意

REFRESH_INSERTEDREFRESH_SELFMOVED处理函数仅在经典UI中可用。

注意

侦听器的默认值仅在经典UI中设置。

注意

对于嵌套组件,对于定义为cq:listeners节点上属性的操作有一些限制:

  • 对于嵌套组件,以下属性​的值必须​为REFRESH_PAGE:

  • aftermove

  • aftercopy

事件处理函数可通过自定义实现实现。 例如(其中project.customerAction是静态方法):

afteredit = "project.customerAction"

下面的示例等效于REFRESH_INSERTED配置:

afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

注意

对于经典UI,要查看哪些参数可以在处理函数中使用,请参阅 CQ.wcm.EditBar CQ.wcm.EditRollover构件文档的before<action>after<action>事件部分。

使用以下配置,在删除、编辑、插入或移动组件后刷新页面:

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>

On this page

Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now