元件參考指南

元件是在AEM中建立體驗的核心。 核心元件AEM專案原型可讓您輕鬆開始使用一組現成的強大元件。 The WKND Tutorial takes the developer through how to use these tools and how to build custom components in order to create a new AEM site.

秘訣

參考本檔案之前,請確定您已完成WKND教學課程,因此熟悉核心元件AEM專案原型。

由於WKND教學課程涵蓋大部分使用案例,本檔案旨在補充這些資源。 它提供有關如何在AEM中架構和設定元件的深入技術細節,而非快速入門手冊。

概覽

本節介紹開發您自己的元件時所需的詳細資訊,並說明重要概念和問題。

規劃

開始實際設定或編寫元件程式碼之前,您應先詢問:

  • 您到底需要新元件做什麼?
  • 您是否需要從頭建立元件,還是可以從現有元件繼承基本知識?
  • 元件是否需要邏輯才能選取/操控內容?
    • 邏輯應與使用者介面層分開。 HTL的設計目的,是為了協助確保此情況發生。
  • 元件是否需要CSS格式?
    • CSS格式應與元件定義分開。 定義命名HTML元素的慣例,以便透過外部CSS檔案修改它們。
  • 您的新元件可能會帶來哪些安全性影響?

重複使用現有元件

在您花時間建立全新元件之前,請考慮自訂或擴充現有元件。 核心元 件提供一套靈活、強大且經過良好測試的生產就緒元件。

擴充核心元件

核心元件也提供清除自訂模式,供您用來調整它們以符合自己專案的需求。

覆蓋元件

元件也可以根據搜尋路徑邏輯以覆蓋重新定義。 但在此情況下,將不會觸發Sling Resource Merger,且/apps必須定義整個覆蓋。

擴展元件對話框

您也可以使用Sling Resource Merger並定義屬性sling:resourceSuperType來覆寫元件對話方塊。

這表示您只需重新定義所需的差異,而不需要重新定義整個對話框。

內容邏輯和呈現標籤

您的元件將以HTML呈現。 您的元件需要定義取得必要內容所需的HTML,然後在製作和發佈環境中視需要呈現。

建議您將負責標籤和轉譯的程式碼與控制用來選取元件內容之邏輯的程式碼分開。

HTL支援此理念,該模板語言故意限制以確保使用真正的寫程式語言定義基礎業務邏輯。 此機制會反白標示為指定檢視所呼叫的程式碼,並視需要為相同元件的不同檢視允許特定邏輯。

此(選用)邏輯可以不同方式實作,並可透過特定命令從HTL叫用:

  • 使用Java - HTL Java Use-API可讓HTL檔案存取自訂Java類別中的Helper方法。 這可讓您使用Java程式碼來實作邏輯,以選取和設定元件內容。
  • 使用JavaScript - HTL JavaScript Use-API可讓HTL檔案存取以JavaScript撰寫的協助程式碼。 這可讓您使用JavaScript程式碼來實作邏輯,以選取和設定元件內容。
  • 使用用戶端資料庫 — 現代化網站嚴重依賴於由複雜JavaScript和CSS程式碼驅動的用戶端處理。 如需詳細資訊,請參閱AEMas a Cloud Service的檔案使用用戶端程式庫

元件結構

AEM元件的結構既強大又靈活。 主要部分為:

資源類型

結構的一個關鍵元素是資源類型。

  • 內容結構聲明意圖。
  • 資源類型會實作它們。

這是抽象,有助於確保即使外觀和感覺隨時間而改變,意圖仍會維持。

元件定義

元件的定義可依下列方式劃分:

  • AEM元件以Sling.為基礎
  • AEM元件位於/libs/core/wcm/components下。
  • 項目/站點特定元件位於/apps/<myApp>/components下。
  • AEM標準元件定義為cq:Component,且有關鍵元素:
    • jcr屬性 — jcr屬性的清單。 這些是變數,有些可能是選用的,但元件節點、其屬性和子節點的基本結構是由cq:Component定義定義的。
    • 資源 — 這些定義元件使用的靜態元素。
    • 指令碼 — 這些指令碼用於實作元件之產生例項的行為。

Vital Properties

  • 根節點:
    • <mycomponent> (cq:Component) - Hierarchy node of the component.
  • 重要屬性:
    • jcr:title — 元件標題;例如,元件在元件瀏覽器和元件控制台中列出時, 作為 標籤使用
    • jcr:description — 元件的說明;在元件瀏覽器和元件主控台中,作為滑鼠移過提示使用
    • See the section Component Icon for details
  • Vital Child Nodes:
    • cq:editConfig (cq:EditConfig) — 定義元件的編輯屬性,並使元件顯示在「元件瀏覽器」中
      • 如果元件有對話方塊,則會自動顯示在「元件」瀏覽器或Sidekick中,即使cq:editConfig不存在亦然。
    • cq:childEditConfig (cq:EditConfig) — 控制未定義子元件的製作UI方面。 cq:editConfig
    • cq:dialog (nt:unstructured) — 此元件的對話框。定義介面,讓使用者設定元件和/或編輯內容。
    • cq:design_dialog (nt:unstructured) — 編輯此元件的設計

元件圖示

當開發人員建立元件時,元件的圖示或縮寫會透過元件的JCR屬性定義。 這些屬性的計算順序如下,並使用找到的第一個有效屬性。

  1. cq:icon — 指向Coral UI資料庫中標準圖示的字 串屬 性,以在元件瀏覽器中顯示
    • 使用Coral圖示的HTML屬性值。
  2. abbreviation — 字串屬性,可自訂元件瀏覽器中元件名稱的縮寫
    • 縮寫應限制為兩個字元。
    • 提供空字串將從jcr:title屬性的前兩個字元建立縮寫。
      • 例如,「Im」代表「Image」
      • 本地化的標題將用於建立縮寫。
    • 僅當元件具有abbreviation_commentI18n屬性,然後將該屬性用作翻譯提示時,才翻譯縮寫。
  3. cq:icon.pngcq: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中選取的元件,例如其他元件繼承的基礎元件。
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 此值指向元件🔗的表徵圖,並顯示在元件瀏覽器中。

If we look at the Text component, we can see a number of these elements:

Text Component structure

Properties of particular interest include:

  • jcr:title — 這是元件瀏覽器中用於識別元件的元件標題。
  • jcr:description — 此為元件的說明。
  • sling:resourceSuperType - This indicates the path of inheritance when extending a component (by overriding a definition).

Child nodes of particular interest include:

  • cq:editConfig — 這會在編輯時控制元件的視覺效果。
  • cq:dialog — 這會定義編輯此元件內容的對話方塊。
  • cq:design_dialog — 它指定此元件的設計編輯選項。

對話方塊

對話方塊是元件的關鍵元素,因為對話方塊提供介面,供作者在內容頁面上設定元件,並為該元件提供輸入。 如需內容作者如何與元件互動的詳細資訊,請參閱製作檔案

視元件的複雜性而定,您的對話方塊可能需要一或多個索引標籤。

AEM元件的對話方塊:

  • nt:unstructured類型的cq:dialog節點。
  • 位於其cq:Component節點下,且位於其元件定義旁。
  • 定義用於編輯此元件內容的對話框。
  • 是使用Granite UI元件來定義。
  • 會根據其內容結構和sling:resourceType屬性,在伺服器端轉譯(作為Sling元件)。
  • 包含描述對話框內欄位的節點結構
    • 這些節點為nt:unstructured,具有所需的sling:resourceType屬性。

標題元件的對話框定義

在對話方塊中,會定義個別欄位:

標題元件對話框定義的欄位

設計對話方塊

設計對話方塊與用來編輯和設定內容的對話方塊類似,但提供範本作者的介面,以在頁面範本上預先設定並提供該元件的設計詳細資料。 內容作者接著會使用頁面範本來建立內容頁面。 如需如何建立範本的詳細資訊,請參閱範本檔案

編輯頁面範本時會使用設計對話方塊,但並非所有元件都需要這些對話方塊。例如,Title​和​影像元件​都有設計對話方塊,而​社交媒體共用元件​則沒有。

Coral UI和Granite UI

Coral UI和Granite UI會定義AEM的外觀和風格。

  • Coral UI 提供跨所有雲端解決方案的一致UI。
  • Granite UI 提供包裝在Sling元件中的Coral UI標籤,以建立UI主控台和對話方塊。

Granite UI提供在製作環境中建立對話方塊所需的大量基本Widget。 如有必要,您可以擴充此選取範圍並建立您自己的介面工具集。

如需其他詳細資訊,請參閱下列資源:

自訂對話方塊欄位

若要建立新介面工具集以用於元件對話方塊,您必須建立新的Granite UI欄位元件。

如果您將對話方塊視為表單元素的簡單容器,則您也可以將對話方塊內容的主要內容視為表單欄位。 建立新表單欄位需要建立資源類型;這等同於建立新元件。 為協助您完成該工作,Granite UI提供要繼承的通用欄位元件(使用sling:resourceSuperType):

/libs/granite/ui/components/coral/foundation/form/field

更具體來說,Granite UI提供一系列欄位元件,這些元件適合用於對話方塊,或更一般地以forms.

建立資源類型後,可以在對話方塊中新增新節點,並使用引用您剛引入的資源類型的屬性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模式為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:dropTargets

cq:dropTargets節點(節點類型nt:unstructured)定義可接受從內容尋找器拖曳的資產中刪除的放置目標。 它是cq:DropTargetConfig類型的節點。

類型cq:DropTargetConfig的子節點定義元件中的放置目標。

就地編輯 — cq:inplaceEditing

就地編輯器可讓使用者直接編輯內容流程中的內容,而不需開啟對話方塊。 例如,標準​Text​和​Title​元件都具有內嵌編輯器。

就地編輯器對於每個元件類型並非必要/有意義的。

cq:inplaceEditing節點(節點類型cq:InplaceEditingConfig)定義元件的就地編輯配置。 它可以有下列屬性:

屬性名稱 屬性類型 屬性值
active Boolean true 啟用元件就地編輯。
configPath String 編輯器配置的路徑,可由配置節點指定
editorType String 可用類型包括:plaintext對於非HTML內容,title在開始編輯之前將圖形標題轉換為純文字,而text使用RTF編輯器

以下配置啟用元件的嵌入編輯,並將plaintext定義為編輯器類型:

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

處理欄位事件 — cq:listeners

在自訂用戶端程式庫中,對對話欄位上的事件進行處理的方法是透過監聽器完成。

若要將邏輯插入欄位,您應:

  • 將欄位標示為指定的CSS類別(連結)。
  • 在用戶端程式庫中定義掛接該CSS類別名稱的JS接聽程式(這可確保您的自訂邏輯限定在您的欄位內,而不會影響相同類型的其他欄位)。

若要達成此目標,您必須了解您要與之互動的基礎Widget程式庫。 請參閱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的值。

檔案元件

身為開發人員,您需要輕鬆存取元件檔案,以便快速了解元件的:

  • 說明
  • 預期用途
  • 內容結構和屬性
  • 公開的API和擴充功能點

因此,很容易就能在元件本身內使用任何現有的檔案標籤。

您只需將README.md檔案置於元件結構中即可。

元件結構中的README.md

此Markdown會顯示在元件控制台中。

元件控制台中顯示的README.md

支援的Markdown與內容片段的相同。

本頁內容