自訂和擴充內容片段 customizing-and-extending-content-fragments

在Adobe Experience Manager as a Cloud Service中,內容片段會擴充標準資產;請參閱:

架構 architecture

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

  • 內容片段 ​本身
  • 它包含一或多個​ 內容元素
  • 它可以有一或多個​ 內容變數

個別內容片段是以內容片段模式為基礎:

  • 內容片段模型會在建立內容片段時定義其結構。

  • 片段會參考模型;因此,模型的變更可能會影響或確實影響任何相依片段。

  • 模型是由資料型別建立而成。

  • 新增新變數的函式等,必須據此更新片段。

    note note
    NOTE
    若要您顯示/轉譯內容片段,您的帳戶必須擁有模型的read許可權。
    note caution
    CAUTION
    對現有內容片段模型所做的任何變更都可能影響相依片段;這可能會導致這些片段中的孤立屬性。

網站與Assets的整合 integration-of-sites-with-assets

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

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

將內容片段視為AEM Sites功能,例如:

  • 可在編寫頁面時使用。

將內容片段對應至Assets mapping-content-fragments-to-assets

內容片段到資產

根據內容片段模型的內容片段會對應至單一資產:

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

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

      jcr:content/data/master

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

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

  • 中繼資料和關聯內容儲存在jcr:content/metadata下方
    除了標題和說明(不被視為傳統中繼資料,且儲存在jcr:content中)

資產位置 asset-location

與標準資產一樣,內容片段位於下:

/content/dam

資產許可權 asset-permissions

請參閱內容片段 — 刪除考量事項

功能整合 feature-integration

若要與Assets核心整合:

  • 內容片段管理(CFM)功能以Assets核心為基礎。

  • CFM針對卡片/欄/清單檢視中的專案提供自己的實作;這些增效模組會插入現有的Assets內容呈現實作。

  • 已擴充數個Assets元件,以符合內容片段。

在頁面中使用內容片段 using-content-fragments-in-pages

CAUTION
內容片段元件是核心元件的一部分。 如需詳細資訊,請參閱開發核心元件

內容片段可以從AEM頁面引用,就像任何其他資產型別一樣。 AEM提供​ 內容片段核心元件 - 元件,可讓您在頁面上包含內容片段。 您也可以擴充此​ 內容片段 ​核心元件。

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

  • 元件可讓您選取要顯示的變數。

  • 此外,也可以選取段落範圍來限制輸出;例如,這可用於多欄輸出。

  • 元件允許中間內容:

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

    • 對於中間內容:

      • 請注意不穩定參考的可能性。 中間內容(在製作頁面時新增)與旁邊段落沒有固定的關係。 在中間內容的位置之前插入新段落(在內容片段編輯器中)可能會失去相對位置。

      • 請考慮使用其他引數(例如變數和段落篩選器)來設定要在頁面上呈現的內容。

NOTE
內容片段模型:
在頁面上使用內容片段時,會參考其所根據的內容片段模式。
這表示,如果您在發佈頁面時尚未發佈模型,系統會標籤此模型,並將模型新增至要與頁面一起發佈的資源。

與其他架構整合 integration-with-other-frameworks

內容片段可以整合至:

  • 翻譯

    內容片段已與AEM翻譯工作流程完全整合。 在架構層級,這表示:

    • 內容片段的個別翻譯是單獨的片段;例如:

      • 它們位於不同的語言根下,但共用相關語言根下的相對路徑:

        /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
Adobe建議使用伺服器端API,而非直接存取內容結構。

重要介面 key-interfaces

下列三個介面可作為進入點:

  • 內容片段 (ContentFragment)

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

    介面提供您執行下列作業的方法:

    • 管理基本資料(例如,取得名稱、取得/設定標題/說明)

    • 存取中繼資料

    • 存取元素:

      • 清單元素

      • 依名稱取得元素

      • 建立元素(請參閱警告

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

    • 為片段定義的清單變數

    • 全域建立變數

    • 管理關聯內容:

      • 清單集合
      • 新增集合
      • 移除集合
    • 存取片段的模型

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

    • Content元素 (ContentElement)

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

      • 取得/設定內容

      • 存取元素的變數:

        • 清單變數
        • 依名稱取得變數
        • 建立變數(請參閱警告
        • 移除變數(請參閱警告
        • 存取變化資料(請參閱ContentVariation
      • 解決變數的捷徑(如果指定的變數不適用於元素,則套用一些額外的實作專用遞補邏輯)

    • 內容變數 (ContentVariation)

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

    所有三個介面( ContentFragmentContentElementContentVariation)都會延伸Versionable介面,新增內容片段所需的版本設定功能:

    • 建立元素的版本
    • 列出元素的版本
    • 取得已建立版本之元素的特定版本內容

調整 — 使用adaptTo() adapting-using-adaptto

可調整以下內容:

  • ContentFragment可以調整為:

    • Resource — 基礎Sling資源;直接更新基礎Resource需要重建ContentFragment物件。

    • Asset — 代表內容片段的DAM Asset抽象化;直接更新Asset需要重建ContentFragment物件。

  • ContentElement可以調整為:

  • FragmentTemplate

  • Resource可以調整為:

    • ContentFragment

警告 caveats

請注意:

  • 整個API的設計目的是​ ​自動保留變更(除非在API JavaDoc中另有註明)。 因此,請一律認可個別請求的資源解析器(或您實際使用的解析器)。

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

    • Adobe建議您從ContentFragment建立變數。 這可確保所有元素都共用此變數,並視需要更新適當的全域資料結構,以反映內容結構中的新變數。

    • 使用ContentElement.removeVariation()透過元素移除現有的變數並不會更新指派給變數的全域資料結構。 若要確保這些資料結構保持同步,請改用ContentFragment.removeVariation(),這會移除全域變數。

內容片段管理API — 使用者端 the-content-fragment-management-api-client-side

CAUTION
使用者端API為內部API。

其他資訊 additional-information

請參閱下列內容:

  • filter.xml

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

編輯工作階段 edit-sessions

CAUTION
請考量此背景資訊。 您不應該在此變更任何專案(因為儲存庫中已標示為​ 私人區域),但有時這可能有助於瞭解事情的幕後運作方式。

編輯內容片段是原子性的,它可以跨越多個檢視(=HTML頁面)。 因此,原子式多檢視編輯功能不是典型的AEM概念,內容片段會使用所謂的​ 編輯工作階段

當使用者在編輯器中開啟內容片段時,會啟動編輯工作階段。 當使用者透過選取​ 儲存 ​或​ 取消 ​而離開編輯器時,編輯工作階段即已完成。

技術上,所有編輯都是在​ 即時 ​內容上完成的,就像所有其他AEM編輯一樣。 開始編輯工作階段時,會建立目前未編輯狀態的版本。 如果使用者取消編輯,則會還原該版本。 如果使用者按一下​ 儲存,則不會執行任何特定動作,因為編輯是在​ 即時 ​內容上執行,因此所有變更都會持續存在。 此外,按一下「儲存」會觸發一些背景處理,例如建立全文檢索搜尋資訊或處理混合媒體資產,或同時觸發兩者。

對於邊緣案例有一些安全措施;例如,如果使用者嘗試離開編輯器而未儲存或取消編輯工作階段。 此外,定期自動儲存也可防止資料遺失。
兩個使用者可以同時編輯相同的內容片段,因此會覆寫彼此的變更。 若要防止此情況,內容片段必須透過在片段上套用DAM管理的 簽出 ​動作來鎖定。

範例 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

若要以程式設計方式建立內容片段,請使用從模型資源改寫的FragmentTemplate

例如:

Resource modelRsc = resourceResolver.getResource("...");
FragmentTemplate tpl = modelRsc.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秒)

用於頁面編寫的元件 components-for-page-authoring

如需詳細資訊,請參閱

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab