自定义和扩展内容片段 customizing-and-extending-content-fragments

内容片段扩展了标准资产;请参阅:

架构 architecture

内容片段的基本组成部分为:

  • 内容片段,
  • 包含一个或多个​ 内容元素
  • 并且可以具有一个或多个​ 内容变量 ​的服务器。

根据片段类型,还会使用模型或模板:

CAUTION
建议使用内容片段模型创建所有新片段。
内容片段模型用于WKND中的所有示例。
NOTE
在AEM 6.3之前,内容片段是基于模板而不是模型创建的。
现已弃用内容片段模板。 它们仍可用于创建片段,但建议改用内容片段模型。 不会向片段模板中添加任何新功能,并且会在未来版本中删除这些功能。
  • 内容片段模型:

    • 用于定义包含结构化内容的内容片段。
    • 内容片段模型在创建内容片段时定义其结构。
    • 片段引用模型;因此,对模型的更改可能/将影响任何依赖的片段。
    • 模型由数据类型构建。
    • 用于添加新变体的函数等,必须相应地更新片段。
    note caution
    CAUTION
    对现有内容片段模型所做的任何更改都会影响从属片段;这可能会导致这些片段中的属性孤立。
  • 内容片段模板:

    • 用于定义简单内容片段。
    • 模板在创建内容片段时定义内容片段的(基本、纯文本)结构。
    • 模板在创建时复制到片段;因此对模板的进一步更改将不会反映在现有片段中。
    • 用于添加新变体的函数等,必须相应地更新片段。
    • 内容片段模板的工作方式与AEM生态系统内的其他模板机制(例如,页面模板等)的工作方式不同。 因此,应单独审议这些问题。
    • 当基于模板时,内容的MIME类型根据实际内容进行管理;这意味着每个元素和变体可以具有不同的MIME类型。

与Assets集成 integration-with-assets

内容片段管理(CFM)是AEM Assets的一部分,如下所示:

  • 内容片段是资产。
  • 它们使用现有的Assets功能。
  • 它们与Assets(Admin Console等)完全集成。

将结构化内容片段映射到Assets mapping-structured-content-fragments-to-assets

片段到资产结构

包含结构化内容(即基于内容片段模型)的内容片段映射到单个资源:

  • 所有内容都存储在资源的jcr:content/data节点下:

    • 元素数据存储在主子节点下:

      jcr:content/data/master

    • 变体存储在子节点下,该子节点带有变体的名称:
      例如,jcr:content/data/myvariation

    • 每个元素的数据作为属性存储在相应的子节点中,该属性具有元素名称:
      例如,元素text的内容作为属性text存储在jcr:content/data/master

  • 元数据和关联内容存储在jcr:content/metadata
    除了标题和描述,它们不被视为传统元数据并存储在jcr:content

将简单内容片段映射到Assets mapping-simple-content-fragments-to-assets

chlimage_1-90

简单内容片段(基于模板)将映射到由主资产和(可选)子资产组成的组合:

  • 片段的所有非内容信息(例如标题、描述、元数据、结构)在主资产上专门进行管理。

  • 片段第一个元素的内容映射到主资源的原始演绎版。

    • 第一个元素的变体(如果有)映射到主资源的其他演绎版。
  • 其他元素(如果存在)将映射到主资产的子资产。

    • 这些附加元素的主要内容映射到相应子资产的原始演绎版。
    • 任何其他元素的其他变体(如果适用)映射到相应子资产的其他演绎版。

资产位置 asset-location

与标准资产一样,内容片段位于下:

/content/dam

资源权限 asset-permissions

有关详细信息,请参阅内容片段 — 删除注意事项

功能集成 feature-integration

  • 内容片段管理(CFM)功能以Assets核心为基础,但应尽可能独立于此核心。
  • CFM为卡片/列/列表视图中的项目提供自己的实施;这些实施可以插入现有的Assets内容呈现实施。
  • 扩展了多个Assets组件以满足内容片段的需求。

在页面中使用内容片段 using-content-fragments-in-pages

CAUTION
现在建议使用内容片段核心组件。 有关详细信息,请参阅开发核心组件

可以从AEM页面引用内容片段,就像任何其他资源类型一样。 AEM提供了​内容片段 ​核心组件 — 一个组件,它允许您在页面中包含内容片段。 您还可以扩展此​ 内容片段 ​核心组件。

  • 组件使用fragmentPath属性引用实际内容片段。 fragmentPath属性的处理方式与其他资产类型的类似属性相同;例如,当内容片段移动到其他位置时。

  • 利用组件,可选择要显示的变体。

  • 此外,可以选择一定范围的段落以限制输出;例如,这可用于多列输出。

  • 该组件允许中间内容

    • 在这里,利用组件可以在引用片段的段落之间放置其他资产(图像等)。

    • 对于中间内容,您需要:

      • 请注意,可能存在不稳定的引用;中间内容(在创作页面时添加)与其旁边的段落没有固定关系,在中间内容的位置可能丢失相对位置之前插入新段落(在内容片段编辑器中)
      • 请考虑使用其他参数(如变体和段落过滤器)以避免搜索结果中出现误报
NOTE
内容片段模型:
使用基于页面上的内容片段模型的内容片段时,会引用模型。 这意味着,如果在您发布页面时模型尚未发布,则会标记该模型,并将模型添加到要与页面一起发布的资源。
内容片段模板:
使用基于页面上的内容片段模板的内容片段时,没有引用,因为创建片段时复制了模板。

使用OSGi控制台进行配置 configuration-using-osgi-console

例如,内容片段的后端实施负责使页面上使用的片段实例可搜索,或管理混合媒体内容。 此实施需要知道哪些组件用于呈现片段以及如何对呈现进行参数化。

可以在Web控制台中为OSGi捆绑包​ 内容片段组件配置 ​配置此内容的参数。

  • 资源类型
    可提供sling:resourceTypes列表以定义用于呈现内容片段的组件以及应应用后台处理的位置。

  • 引用属性
    可以配置属性列表以指定在何处为各个组件存储对片段的引用。

NOTE
属性和组件类型之间没有直接映射。
AEM只采用可在段落上找到的第一个属性。 因此,您应该仔细选择属性。

screenshot_2019-03-18at100941

您还必须遵循以下一些准则,以确保组件与内容片段后台处理兼容:

  • 定义要呈现的元素的属性的名称必须是elementelementNames

  • 定义要呈现的变量的属性的名称必须是variationvariationName

  • 如果支持多个元素的输出(通过使用elementNames指定多个元素),则实际显示模式由属性displayMode定义:

    • 如果值为singleText(并且只配置了一个元素),则该元素将呈现为具有中间内容、布局支持等的文本。 这是仅呈现一个元素的片段的默认设置。
    • 否则,将使用一种更简单的方法(可以称为“表单视图”),这种方法不支持中间内容,并且片段内容按“原样”渲染。
  • 如果为displayMode==singleText(隐式或显式)呈现片段,则以下附加属性将发挥作用:

    • paragraphScope定义是应呈现所有段落,还是仅呈现段落范围(值:allrange

    • 如果paragraphScope==range,则属性paragraphRange定义要呈现的段落范围

与其他框架集成 integration-with-other-frameworks

内容片段可以与集成:

  • 翻译

    内容片段已与AEM翻译工作流完全集成。 在架构方面,这意味着:

    • 内容片段的各个翻译实际上是单独的片段;例如:

      • 它们位于不同的语言根下:

        /content/dam/<path>/en/<to>/<fragment>

        对比

        /content/dam/<path>/de/<to>/<fragment>

      • 但它们共享语言根目录下的完全相同的相对路径:

        /content/dam/<path>/en/<to>/<fragment>

        对比

        /content/dam/<path>/de/<to>/<fragment>

    • 除了基于规则的路径之外,内容片段的不同语言版本之间没有进一步的连接;它们作为两个单独的片段处理,尽管UI提供了在语言变体之间导航的方法。

    note note
    NOTE
    AEM翻译工作流适用于/content
    • 由于内容片段模型驻留在/conf中,因此这些翻译中不包含这些模型。 您可以国际化UI字符串

    • 将复制模板以创建片段,因此这是隐式的。

  • 元数据架构

    • 内容片段(重新)使用可以使用标准资源定义的元数据架构

    • CFM提供了自己的特定架构:

      /libs/dam/content/schemaeditors/forms/contentfragment

      如有必要,可以扩展此功能。

    • 相应的架构表单与片段编辑器集成。

内容片段管理API — 服务器端 the-content-fragment-management-api-server-side

您可以使用服务器端API访问内容片段;请参阅:

com.adobe.cq.dam.cfm

CAUTION
强烈建议使用服务器端API,而不是直接访问内容结构。

关键界面 key-interfaces

以下三个接口可用作入口点:

  • 片段模板 (FragmentTemplate)

    使用FragmentTemplate.createFragment()创建片段。

    code language-none
    Resource templateOrModelRsc = resourceResolver.getResource("...");
    FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
    ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");
    

    此界面表示:

    • 从中创建内容片段的内容片段模型或内容片段模板,
    • 以及(创建后)该片段的结构信息

    此信息可以包括:

    • 访问基本数据(标题、描述)

    • 访问片段元素的模板/模型:

      • 列表元素模板
      • 获取给定元素的结构信息
      • 访问元素模板(请参阅ElementTemplate
    • 访问片段变体的模板:

      • 列出变体模板
      • 获取给定变体的结构信息
      • 访问变体模板(请参阅VariationTemplate
    • 获取初始关联内容

    表示重要信息的接口:

    • ElementTemplate

      • 获取基本数据(名称、标题)
      • 获取初始元素内容
    • VariationTemplate

      • 获取基本数据(名称、标题、描述)
  • 内容片段 (ContentFragment)

    利用此界面,您可以以抽象方式处理内容片段。

    note caution
    CAUTION
    强烈建议通过此界面访问片段。 应避免直接更改内容结构。

    该界面为您提供了以下方法:

    • 管理基本数据(例如,获取名称;获取/设置标题/描述)

    • 访问元数据

    • 访问元素:

      • 列出元素

      • 按名称获取元素

      • 创建新元素(请参阅注意事项

      • 访问元素数据(请参阅ContentElement

    • 为片段定义的列表变量

    • 全局创建新变体

    • 管理关联内容:

      • 列出收藏集
      • 添加收藏集
      • 移除收藏集
    • 访问片段的模型或模板

    表示片段的主元素的接口包括:

    • Content元素 (ContentElement)

      • 获取基本数据(名称、标题、描述)

      • 获取/设置内容

      • 访问元素的变体:

        • 列表变量
        • 按名称获取变体
        • 创建新变体(请参阅注意事项
        • 删除变体(请参阅注意事项
        • 访问变量数据(请参阅ContentVariation
      • 解决变体的快捷方式(如果指定的变体不适用于元素,则应用一些其他特定于实施的回退逻辑)

    • 内容变量 (ContentVariation)

      • 获取基本数据(名称、标题、描述)
      • 获取/设置内容
      • 简单同步,基于上次修改的信息

    所有三个接口(ContentFragmentContentElementContentVariation)都扩展了Versionable接口,这添加了内容片段所需的版本控制功能:

    • 创建新版本的元素
    • 列出元素的版本
    • 获取版本化元素的特定版本的内容

适应 — 使用adaptTo() adapting-using-adaptto

可以调整以下内容:

  • ContentFragment可以适应:

    • Resource — 基础Sling资源;请注意,直接更新基础Resource需要重建ContentFragment对象。

    • Asset — 表示内容片段的DAM Asset抽象;请注意,直接更新Asset需要重建ContentFragment对象。

  • ContentElement可以适应:

    • ElementTemplate — 用于访问元素的结构信息。
  • FragmentTemplate可以适应:

    • Resource - Resource确定引用的模型或已复制的原始模板;

      • 通过Resource进行的更改不会自动反映到FragmentTemplate中。
  • Resource可以适应:

    • ContentFragment
    • FragmentTemplate

注意事项 caveats

应当指出:

  • 实施API是为了提供UI支持的功能。

  • 整个API设计为​ 而非 ​自动保留更改(除非在API JavaDoc中另有说明)。 因此,您将始终必须提交相应请求的资源解析程序(或您实际使用的解析程序)。

  • 可能需要额外工作的任务:

    • 创建/删除新元素将不会更新简单片段的数据结构(基于片段模板)。

    • ContentElement创建新变体将不会更新数据结构(但从ContentFragment全局创建变体将会)。

    • 删除现有变体将不会更新数据结构。

内容片段管理API — 客户端 the-content-fragment-management-api-client-side

CAUTION
对于AEM 6.5,客户端API是内部的。

附加信息 additional-information

请参阅以下内容:

  • filter.xml

    用于内容片段管理的filter.xml已配置为不与Assets核心内容包重叠。

编辑会话 edit-sessions

当用户在一个编辑器页面中打开内容片段时,会启动编辑会话。 当用户通过选择​ 保存 ​或​ 取消 ​离开编辑器时,编辑会话已完成。

要求 requirements

控制编辑会话的要求包括:

  • 编辑的内容片段可以跨越多个视图(=HTML页面),应为原子结构。
  • 编辑也应是​ 事务性;在编辑会话结束时,必须提交(保存)或回滚(取消)更改。
  • Edge案例应正确处理;这些案例包括用户通过手动输入URL或使用全局导航离开页面时的情况。
  • 应提供定期自动保存(每x分钟)以防止数据丢失。
  • 如果两个用户同时编辑内容片段,则他们不应覆盖彼此的更改。

进程 processes

涉及的过程包括:

  • 启动会话

    • 将创建内容片段的新版本。
    • 自动保存已启动。
    • 设置了Cookie;这些Cookie定义了当前编辑的片段,并打开了编辑会话。
  • 完成会话

    • 自动保存已停止。

    • 提交时:

      • 上次修改的信息已更新。
      • Cookie将被删除。
    • 回滚时:

      • 恢复在编辑会话启动时创建的内容片段的版本。
      • Cookie将被删除。
  • 编辑

    • 所有更改(包括自动保存)都是在活动内容片段上完成的,而不是在分隔的保护区中。
    • 因此,这些更改会立即反映在引用相应内容片段的AEM页面上

操作 actions

可能的操作包括:

  • 输入页面

    • 检查编辑会话是否已存在;通过检查相应的Cookie。

      • 如果存在,请验证是否已为当前正在编辑的内容片段启动编辑会话

        • 如果是当前片段,请重新建立会话。
        • 如果没有,请尝试取消对以前编辑的内容片段的编辑并删除Cookie(之后不存在编辑会话)。
      • 如果不存在编辑会话,请等待用户进行第一次更改(请参阅下文)。

    • 检查页面上是否已引用内容片段,如果是,则显示相应的信息。

  • 内容更改

    • 每当用户更改内容且不存在编辑会话时,都会创建一个新的编辑会话(请参阅启动会话)。
  • 离开页面

    • 如果存在编辑会话并且更改未保留,则会显示模式确认对话框,以通知用户内容可能丢失,并允许他们停留在页面上。

示例 examples

示例:访问现有内容片段 example-accessing-an-existing-content-fragment

要实现此目的,您可以使表示API的资源适应:

com.adobe.cq.dam.cfm.ContentFragment

例如:

// first, get the resource
Resource fragmentResource = resourceResolver.getResource("/content/dam/fragments/my-fragment");
// then adapt it
if (fragmentResource != null) {
    ContentFragment fragment = fragmentResource.adaptTo(ContentFragment.class);
    // the resource is now accessible through the API
}

示例:创建内容片段 example-creating-a-new-content-fragment

要以编程方式创建内容片段,您需要使用:

com.adobe.cq.dam.cfm.ContentFragmentManager#create

例如:

Resource templateOrModelRsc = resourceResolver.getResource("...");
FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");

示例:指定自动保存时间间隔 example-specifying-the-auto-save-interval

可以使用配置管理器(ConfMgr)定义自动保存时间间隔(以秒为单位):

  • 节点: <*conf-root*>/settings/dam/cfm/jcr:content

  • 属性名称: autoSaveInterval

  • 类型:Long

  • 默认值: 600 (10分钟);此默认值在/libs/settings/dam/cfm/jcr:content上定义

如果要将自动保存间隔设置为5分钟,则需要在节点上定义属性;例如:

  • 节点: /conf/global/settings/dam/cfm/jcr:content

  • 属性名称: autoSaveInterval

  • 类型:Long

  • 值: 300(5分钟等于300秒)

内容片段模板 content-fragment-templates

有关完整信息,请参阅内容片段模板

用于页面创作的组件 components-for-page-authoring

有关详细信息,请参阅

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2