自訂和擴充內容片段

內容片段延伸了標準資產;請參閱:

架構

內容片段的基本組成部分為:

  • A 內容片段,
  • 由一個或多個​內容元素 s組成,
  • 可以具有一個或多個​內容變化 s。

視片段類型而定,也會使用模型或範本:

注意

現在建議 建立內容片段模型以建立所有片段。

We.Retail中的所有範例都使用內容片段模型。

  • 內容片段模型:

    • 用於定義包含結構化內容的內容片段。
    • 內容片段模型會定義內容片段建立時的結構。
    • 片段參照模型;因此,對模型的更改可能會/會影響任何相依片段。
    • 模型是由資料類型組成。
    • 新增變數等的函式必須相應地更新片段。
    注意

    對現有內容片段模型所做的任何變更都會影響相關片段;這會導致這些片段中的孤立屬性。

  • 內容片段範本:

    • 用於定義簡單內容片段。
    • 範本可定義內容片段建立時的(基本、僅限文字)結構。
    • 模板建立時被複製到片段;因此,範本的進一步變更將不會反映在現有片段中。
    • 新增變數等的函式必須相應地更新片段。
    • 內容片 段範本的運作方式與AEM生態系統中其他範本機制(例如頁面範本等)的運作方式不同。因此,應單獨考慮。
    • 根據範本管理內容的MIME類型;這表示每個元素和變數都可以有不同的MIME類型。

與資產整合

內容片段管理(CFM)是AEM資產的一部份,其格式為:

  • 內容片段是資產。
  • 他們使用現有的資產功能。
  • 它們與資產(管理控制台等)完全整合。

將結構化內容片段對應至資產

片段至資產結構

具有結構化內容的內容片段(即基於內容片段模型)被映射到單一資產:

  • 所有內容都儲存在資產的jcr:content/data節點下:

    • 元素資料儲存在主子節點下:

      jcr:content/data/master

    • 變數會儲存在子節點下,子節點會攜帶變數的名稱:
      例如,jcr:content/data/myvariation

    • 每個元素的資料作為具有元素名稱的屬性儲存在相應的子節點中:
      例如,元素text的內容儲存為jcr:content/data/master上的屬性text

  • 中繼資料和相關內容會儲存在jcr:content/metadata下方
    除標題和說明外,標題和說明不被視為傳統中繼資料,並儲存在
    jcr:content

將簡單內容片段對應至資產

chlimage_1-90

簡單內容片段(以範本為基礎)會對應至由主要資產和(選用)子資產組成的組合:

  • 片段的所有非內容資訊(例如標題、說明、中繼資料、結構)都會專門管理在主資產上。

  • 片段的第一元素的內容被映射到主資產的原始格式副本。

    • 第一個元素的變化(如果有的話)會對應至主要資產的其他轉譯。
  • 其他元素(如果現有)會對應至主要資產的子資產。

    • 這些附加元素的主要內容映射到相應子資產的原始格式副本。
    • 其他元素的其他變動(如適用)會對應至個別子資產的其他轉譯。

資產位置

與標準資產一樣,內容片段的持有方式如下:

/content/dam

資產權限

如需詳細資訊,請參閱內容片段——刪除考量事項

功能整合

  • 內容片段管理(CFM)功能建立在Assets核心上,但應盡可能獨立於它。
  • CFM針對卡片/欄/清單檢視中的項目提供其專屬的實作;這些外掛程式可插入現有的Assets內容轉譯實作。
  • 已擴充數個「資產」元件,以迎合內容片段的需求。

在頁面中使用內容片段

注意

現在建議使用內容片段核心元件。 如需詳細資訊,請參閱開發核心元件

您可從AEM頁面參考內容片段,就像任何其他資產類型一樣。 AEM提供​內容片段​核心元件 - 元件,可讓您將內容片段包含在您的頁面上。 您也可以延伸此​內容片段​核心元件。

  • 元件使用fragmentPath屬性來引用實際內容片段。 fragmentPath屬性的處理方式與其他資產類型的相似屬性相同;例如,當內容片段移至其他位置時。

  • 該元件允許您選擇要顯示的變化。

  • 此外,還可以選擇一系列段落來限制輸出;例如,這可用於多欄輸出。

  • 該元件允許in-between content :

    • 此元件可讓您放置其他資產(影像等) 在引用片段的段落之間。

    • 對於中介內容,您需要:

      • 注意參考資料不穩定的可能性;內容之間(在編寫頁面時新增)與其旁邊的段落沒有固定關係,在內容之間位置之前插入新段落(在內容片段編輯器中)可能會失去相對位置
      • 考慮其他參數(例如變數和段落篩選),以避免搜尋結果中的誤報
注意

內容片段模型:

當使用以頁面上的內容片段模型為基礎的內容片段時,會參考模型。 這表示如果模型在您發佈頁面時尚未發佈,則會標籤此模型,並將模型新增至要隨頁面一起發佈的資源。

內容片段範本:

當使用以頁面上的內容片段範本為基礎的內容片段時,建立片段時,沒有範本複製時的參考。

使用OSGi控制台進行配置

例如,內容片段的後端實作負責讓頁面上使用的片段執行個體可供搜尋,或管理混合媒體內容。 此實作需要知道哪些元件用於轉換片段,以及轉換的參數化方式。

此參數可在Web控制台中配置,用於OSGi捆綁​內容片段元件配置

  • 資源
    類型清單
    sling:resourceTypes 可用來定義用於呈現內容片段的元件,以及應套用背景處理的元件。

  • 參考
    屬性可以配置屬性清單,以指定對相應元件的片段的參考儲存位置。

注意

屬性和元件類型之間沒有直接映射。

AEM只會擷取可在段落上找到的第一個屬性。 因此,您應謹慎選擇屬性。

screenshop_2019-03-18at100941

您仍需遵循一些准則,以確保元件與內容片段背景處理相容:

  • 定義要呈現的元素的屬性名稱必須為elementelementNames

  • 定義要呈現的變數的屬性名稱必須是variationvariationName

  • 如果支援多個元素的輸出(通過使用elementNames指定多個元素),則實際顯示模式由屬性displayMode定義:

    • 如果值為singleText(且只設定了一個元素),則元素會呈現為文字,內含內容、版面支援等。 這是僅呈現單一元素之片段的預設值。
    • 否則,會使用更簡單的方法(可稱為「表單檢視」),其中不支援中間內容,且片段內容會以「原樣」呈現。
  • 如果為displayMode == singleText(隱式或顯式)呈現片段,則會播放以下附加屬性:

    • paragraphScope 定義是否應呈現所有段落或僅呈現一系列段落(值: allrange)

    • 如果paragraphScope == range,則屬性paragraphRange定義要呈現的段落範圍

與其他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提供在語言變數之間導覽的方式,但是它們會以兩個不同的片段處理。

    注意

    AEM轉譯工作流程可搭配/content使用:

    • 由於內容片段模型位於/conf中,因此這些轉換中不包括這些模型。 您可以國際化UI字串

    • 範本會複製以建立片段,因此會隱含。

  • 中繼資料結構

    • 內容片段(re)使用中繼資料結構,可以與標準資產一起定義。

    • CFM提供其專屬的特定架構:

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

      如有需要,可加以擴充。

    • 各個模式表單與片段編輯器整合。

內容片段管理API —— 伺服器端

您可以使用伺服器端API來存取您的內容片段;請參閱:

com.adobe.cq.dam.cfm

注意

強烈建議您使用伺服器端API,而非直接存取內容結構。

關鍵介面

以下三個介面可用作入口點:

  • 片段範本 (FragmentTemplate)

    使用FragmentTemplate.createFragment()建立新片段。

    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)

    此介面可讓您以抽象方式處理內容片段。

    注意

    強烈建議通過此介面訪問片段。 應避免直接更改內容結構。

    此介面提供您以下方式:

    • 管理基本資料(例如:取得名稱;get/set title/description)

    • 存取中繼資料

    • 存取元素:

      • 清單元素

      • 依名稱取得元素

      • 建立新元素(請參閱Panuons

      • 存取元素資料(請參閱ContentElement

    • 為片段定義的清單變化

    • 全域建立新變化

    • 管理相關內容:

      • 清單系列
      • 新增系列
      • 移除系列
    • 存取片段的模型或範本

    代表片段主要元素的介面包括:

    • 內容元素 (ContentElement)

      • 取得基本資料(名稱、標題、說明)

      • 取得/設定內容

      • 存取元素的變化:

        • 清單變化
        • 依名稱取得變化
        • 建立新變化(請參閱Panuons
        • 移除變數(請參閱注意事項
        • 存取變數資料(請參閱ContentVariation
      • 解決變數的捷徑(如果指定的變數不適用於元素,則套用某些額外的實施特定備援邏輯)

    • 內容變化 (ContentVariation)

      • 取得基本資料(名稱、標題、說明)
      • 取得/設定內容
      • 簡單同步,基於上次修改的資訊

    這3個介面(ContentFragmentContentElementContentVariation)都擴充了Versionable介面,其中新增了內容片段所需的版本控制功能:

    • 建立元素的新版本
    • 元素的清單版本
    • 取得版本化元素的特定版本內容

適應——使用adaptTo()

可調整下列項目:

  • ContentFragment 可適用於:

    • Resource -基礎Sling資源;請注意,直接更新基 Resource 礎對象需要重建 ContentFragment 對象。

    • Asset -代表內 Asset 容片段的DAM抽象化;請注意,直接更 Asset 新需要重建對 ContentFragment 像。

  • ContentElement 可適用於:

    • ElementTemplate -用於訪問元素的結構資訊。
  • FragmentTemplate 可適用於:

    • Resource -確 Resource 定所複製的參考模型或原始模板;

      • 透過Resource所做的變更不會自動反映在FragmentTemplate中。
  • Resource 可適用於:

    • ContentFragment
    • FragmentTemplate

警告

應當指出:

  • 實作API以提供UI支援的功能。

  • 整個API的設計目的是自動​not​保留變更(除非API JavaDoc另有說明)。 因此,您必須始終提交各個請求(或實際使用的解析程式)的資源解析程式。

  • 可能需要額外努力的任務:

    • 建立/移除新元素不會更新簡單片段的資料結構(以片段範本為基礎)。

    • ContentElement建立新變數不會更新資料結構(但從ContentFragment全域建立變數)。

    • 移除現有變數不會更新資料結構。

內容片段管理API —— 用戶端

注意

對於AEM 6.5,用戶端API是內部的。

其他資訊

請參閱下列內容:

  • filter.xml

    內容片段管理的filter.xml已設定為不會與Assets核心內容套件重疊。

編輯會話

當用戶在其中一個編輯器頁面中開啟內容片段時,開始編輯會話。 當用戶離開編輯器時,通過選擇​保存​或​取消​完成編輯會話。

要求

控制編輯會話的要求包括:

  • 編輯可跨多個檢視(= HTML頁面)的內容片段應是原子。
  • 編輯也應為​transactional;在編輯作業結束時,變更必須提交(儲存)或回退(取消)。
  • 邊緣案件應妥善處理;這些情況包括使用者手動輸入URL或使用全域導覽離開頁面的情形。
  • 應提供定期自動儲存(每x分鐘),以防止資料遺失。
  • 如果內容片段由兩個使用者同時編輯,則不應覆寫彼此的變更。

程序

所涉及的流程包括:

  • 啟動會話

    • 內容片段的新版本隨即建立。
    • 自動儲存即會開始。
    • Cookie已設定;這些定義了當前編輯的片段,並且有一個編輯會話開啟。
  • 完成作業

    • 自動儲存已停止。

    • 提交時:

      • 上次修改的資訊將更新。
      • Cookie已移除。
    • 回滾時:

      • 還原啟動編輯作業時建立的內容片段版本。
      • Cookie已移除。
  • 編輯

    • 所有變更(自動儲存)都會在作用中的內容片段上完成——而不是在個別的受保護區域中。
    • 因此,這些變更會立即反映在參考個別內容片段的AEM頁面上

動作

可能的動作包括:

  • 輸入頁面

    • 檢查是否已存在編輯會話;透過檢查個別Cookie。

      • 如果存在,請確認正在編輯的內容片段的編輯會話已啟動

        • 如果當前片段,請重新建立會話。
        • 如果沒有,請嘗試取消對先前編輯的內容片段的編輯,並移除Cookie(之後未出現編輯工作階段)。
      • 如果不存在編輯會話,請等待用戶進行的第一次更改(請參見下面)。

    • 檢查頁面上是否已參考內容片段,若已參考則顯示適當資訊。

  • 內容變更

    • 每當使用者變更內容而沒有編輯工作階段時,就會建立新的編輯工作階段(請參閱啟動工作階段)。
  • 離開頁面

    • 如果編輯工作階段存在且變更尚未持續,則會顯示模式確認對話方塊,通知使用者可能遺失的內容,並允許使用者留在頁面上。

範例

範例:訪問現有內容片段

若要達成此目的,您可以將代表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
}

範例:建立新內容片段

若要以程式設計方式建立新的內容片段,您必須使用:

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.");

範例:指定自動保存間隔

可使用配置管理器(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秒)

內容片段範本

如需完整資訊,請參閱內容片段範本

頁面編寫元件

如需詳細資訊,請參閱

本頁內容

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
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