AEM Components - The Basics

當您開始開發新元件時，您需要瞭解其結構和組態的基本知識。

此程式包括閱讀理論並檢視標準AEM例項中廣泛的元件實作。 雖然AEM已改用新的標準、現代化、可觸控的UI，但仍持續支援傳統的UI，這讓後一種方式略顯複雜。

概覽

本節將介紹開發您自己的元件時所需的詳細資訊。

規劃

開始實際設定或編碼元件之前，您應詢問：

• 您到底需要新元件做什麼？

  • 清晰的規格有助於在開發、測試和移交的所有階段。

    詳細資訊可能會隨時間而改變，但規範可以更新（儘管更改也應記錄在案）。

• 您需要從頭開始建立元件，還是可以從現有元件繼承基本功能？

  • 我們不需要重新發明車輪。
  • AEM提供數種機制，可讓您繼承和延伸其他元件定義的詳細資料，包括覆寫、覆蓋和Sling Resource Merger。

• 您的元件是否需要邏輯來選取／控制內容？

  • 邏輯應與使用者介面層分開。 HTL的設計目的是協助確保這一點。

• 您的元件是否需要CSS格式？

  • CSS格式應與元件定義分開。 定義HTML元素命名的慣例，以便您透過外部CSS檔案修改這些元素。

• 我應該考慮哪些安全方面？

  • 如需詳細資訊，請參閱安全性檢查清單——開發最佳實務。

Touch-Enabled與Classic UI

在開始進行任何有關開發元件的嚴肅討論之前，您必須知道作者將使用哪個UI:

• 觸控式UI
  在AEM 5.6.0 中引進的標準使用者介面是6.x中的預覽與擴充功能。它以Adobe Marketing Cloud的統一使用者體驗為基礎，使用 Coral UI和 Granite UI的基礎技術。

• 基於
  ExtJS技術的UIUser介面是在CQ 5.1中引入的。

如需詳細資訊，請參閱客戶適用的UI介面建議。

可實作元件以支援觸控式UI、傳統UI或兩者。 在檢視標準例項時，您也會看到原本專為傳統UI、觸控式UI或兩者設計的現成可用元件。

因此，本頁將說明兩者的基本概念，以及如何辨識它們。

內容邏輯與轉換標籤

建議將負責標籤和轉換的代碼與控制用於選擇元件內容的邏輯的代碼分開。

HTL支援此理念，該模板語言被特意限制以確保使用真正的寫程式語言來定義底層業務邏輯。 這個（選用）邏輯是從HTL以特定命令叫用。 此機制會反白標示為特定檢視所呼叫的程式碼，並視需要允許相同元件不同檢視的特定邏輯。

HTL與JSP

HTL是AEM 6.0中引進的HTML範本語言。

在開發您自己的元件時，有關使用HTL或JSP(Java Server Pages)的討論應該是直接的，因為HTL現在是AEM的建議指令碼語言。

HTL和JSP都可用來開發傳統和觸控式使用者介面的元件。 雖然有人傾向於假設HTL僅適用於傳統UI的觸控式UI和JSP，但這是誤解，而且更多是因為時間的緣故。 觸控式UI和HTL大約在相同時段內併入AEM。 由於HTL現在是建議的語言，所以會用於新元件，而新元件通常用於觸控式UI。

開發您自己的元件

若要針對適當的UI建立您自己的元件，請參閱（閱讀本頁後）:

• AEM元件（適用於觸控式UI）
• Classic UI的AEM元件

快速入門的方法是複製現有元件，然後進行所需的變更。 要瞭解如何建立自己的元件並將其添加到段落系統中，請參閱：

• 開發元件 （主要針對觸控式UI）

將元件移至發佈例項

轉換內容的元件必須部署在與內容相同的AEM例項上。 因此，在作者實例上用於編寫和呈現頁面的所有元件都必須部署在發佈實例上。 部署後，這些元件可用來呈現已啟動的頁面。

使用下列工具將元件移至發佈例項：

• 使用Package Manager將元件新增至套件，並將它們移至其他AEM例項。
• 使用「激活樹」複製工 具來複製元件。

從「開始」中要感知的元件

• 頁面:

  • AEM具有​page​元件(cq:Page)。
  • 這是一種對內容管理非常重要的特定資源類型。
    • 頁面對應於保存網站內容的網頁。

• 段落制度：

  • 段落系統是網站管理段落清單時的關鍵部分。 它用於保存和構建保存實際內容的各個元件。
  • 您可以在段落系統中建立、移動、複製和刪除段落。
  • 您也可以選取可在特定段落系統中使用的元件。
  • 標準實例中有各種可用的段落系統（例如parsys、 [responsivegrid](/docs/experience-manager-64/sites-authoring/responsive-layout.md)）。

結構

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 -如果此元件列在段落系統中，則顯示的影像。

  • Touch UI

    • 如需詳細資訊，請參閱Touch UI](/docs/experience-manager-64/sites-developing/components-basics.html?lang=zh-Hant#component-icon-in-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)-此元件的設計編輯。

Touch UI中的元件圖示

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

1. cq:icon -指向 Coral UI程式庫中標準圖示的字串屬 性，以顯示在元件瀏覽器中

   • 使用Coral圖示的HTML屬性值。

2. abbreviation -字串屬性，用於自定義元件瀏覽器中元件名稱的縮寫

   • 縮寫應限制為兩個字元。

   • 提供空字串將從jcr:title屬性的前兩個字元生成縮寫。

     • 例如，「Im」代表「Image」
     • 本地化的標題將用來建立縮寫。

   • 僅當元件具有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:icon、abbreviation、cq:icon.png或cq: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	觸控式使用者介面的設計對話方塊定義。
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	如果找到此節點，當從「元件瀏覽器」或「側腳」新增元件時，此節點將用作內容範本。
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中的Title旁。
thumbnail.png	nt:file	從Sidekick拖曳元件至適當位置時顯示的可選縮圖。

如果我們查看​Text​元件（任一版本），我們可看到下列元素：

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

  

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

  

特定權益物業包括：

• 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

  • cq:dialog ( nt:unstructured節點):

    • 定義用於編輯此元件內容的對話框

    • 觸控式UI的特定功能

    • 是使用Granite UI元件定義的

    • have a property sling:resourceType, as standard Sling content structure

    • 可以具有helpPath屬性來定義幫助資源（絕對或相對路徑），該資源在幫助表徵圖(? 表徵圖)。

      • 對於現成可用的元件，這通常會參照檔案中的頁面。
      • 如果未指定helpPath，則會顯示預設URL（檔案概述頁面）。

  

  在對話方塊中，會定義個別欄位：

  

• 傳統 UI

  • dialog (節 cq:Dialog點)

    • 定義用於編輯此元件內容的對話框

    • 特定於傳統UI

    • 是使用ExtJS Widget定義

    • 具有xtype屬性，該屬性引用ExtJS

    • 可以具有helpPath屬性來定義在選擇​幫助​按鈕時訪問的上下文相關幫助資源（絕對或相對路徑）。

      • 對於現成可用的元件，這通常會參照檔案中的頁面。
      • 如果未指定helpPath，則會顯示預設URL（檔案概述頁面）。

  

  在對話方塊中，會定義個別欄位：

  

  在傳統對話方塊中：

  • 您可以將對話框建立為cq:Dialog，該對話框將提供單個頁籤——如文本元件中的頁籤，或者如果需要多個頁籤，如文本元件中的頁籤，則該對話框可以定義為cq:TabPanel。
  • a cq:WidgetCollection(items)用於為輸入欄位(cq:Widget)或其他頁籤(cq:Widget)提供基礎。 此階層可加以擴充。

設計對話框

設計對話框與用於編輯和配置內容的對話框非常相似，但它們為作者提供了介面，以配置和提供該元件的設計詳細資訊。

設計對話框在「設計模式」中可用，但並非所有元件（例如「標題」和「影像」）都需要這些對話框， ​​ ​​但「文本」卻不 ​​需要。

段落系統（例如parsys）的設計對話框是一個特殊情況，因為它允許用戶選擇特定的其他元件（從元件瀏覽器或側腳）。

將元件添加到段落系統

在定義元件後，它必須可供使用。 要使元件可用於段落系統中，您可以執行以下任一操作：

1. 開啟頁面的設計模式並啟用必要的元件。

2. 將所需元件添加到模板定義的components屬性中：

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

   例如，請參閱：

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

   

元件及其建立的內容

如果我們在頁面上建立並配置​Title​元件的實例：<content-path>/Prototype.html

• 觸控式UI

  

• 傳統 UI

  

然後，我們可以看到在儲存庫中建立的內容的結構：

尤其是，如果您查看​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:editConfig和cq:childEditConfig中的配置設定（與編輯功能相關）。

• 包含階層

  在執行時期，會依包含的順序加入。

  設計人員會使用此階層，而設計人員則會依據此階層來呈現各種設計；包括版面資訊、css資訊、parsys中的可用元件等。

編輯行為

本節說明如何設定元件的編輯行為。 這包括一些屬性，如元件可用的操作、就地編輯器的特性以及與元件上的事件相關的偵聽器。

此設定是觸控式和傳統UI的常見設定，但有特定的差異。

元件的編輯行為是通過在元件節點（類型cq:Component）下添加cq:editConfig類型cq:EditConfig的節點，並添加特定屬性和子節點來配置的。 以下屬性和子節點可用：

• cq:editConfig 節點屬性:

  • cq:actions ( String array):定義可在元件上執行的操作。

  • cq:layout ( String)::定義在傳統UI中編輯元件的方式。

  • cq:dialogMode ( String):定義在傳統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型):定義在元件上執行動作之前或之後所發生的動作。

<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模式為edit或preview時），元件只要不呈現任何可見輸出，就應呈現預留位置。
預留位置的典型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中顯示。啟用觸控的使用者介面不會在內容相關功能表中顯示動作，因此不適用。
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"/>

以下配置將「從基本框架繼承的配置」文本添加到元件編輯欄：

<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（僅限Classic UI）

cq:layout屬性(String)定義了在傳統UI中如何編輯元件。 下列值可用：

屬性值	說明
rollover	預設值。 元件版本可透過點按和／或內容選單「滑鼠移過」存取。 若要進階使用，請注意對應的用戶端物件是： CQ.wcm.EditRollover.
editbar	元件版本可透過工具列存取。 若要進階使用，請注意對應的用戶端物件是： CQ.wcm.EditBar.
auto	用戶端程式碼會保留此選項。

以下配置將編輯按鈕添加到元件編輯欄中：

<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（僅限Classic UI）

元件可以連結至編輯對話方塊。 cq:dialogMode屬性(String)定義了在傳統UI中如何開啟元件對話框。 下列值可用：

屬性值	說明
floating	對話框是浮動的。
inline	(預設值). 對話框錨定在元件上。
auto	如果元件寬度小於客戶端CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH值，則對話框是浮動的，否則它是內嵌的。

以下配置定義帶有編輯按鈕的編輯欄和浮動對話框：

<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類型節點的集合。

類型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。

例如，類名在Download元件的JSP中定義如下
(/libs/foundation/components/download/download.jsp)，其中file是下載元件編輯配置中放置目標的節點名稱：

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

類型cq:DropTargetConfig的節點需要具有以下屬性：

屬性名稱	屬性值
accept	套用至資產MIME類型的Regex，以驗證是否允許刪除。
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（僅限Classic 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>

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內容。 標題：是增強的純文字編輯器，可在編輯開始前將圖形標題轉換為純文字。 由Geometrixx標題元件使用。 文字：要用於HTML內容（使用Rich Text Editor）。

以下配置啟用元件的就地編輯，並將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	在將元件插入其他元件（僅限容器）後，就會觸發處理常式。

事件處理常式可與自訂實作一起實作。 例如（其中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"/>