為AEM Screens開發自訂元件 developing-a-custom-component-for-aem-screens

AEM 6.5加上最新的Screens Feature Pack。

AEM Screens播放器

本機開發環境

在CRX Package Manager中，確認已安裝下列兩個套件：

1. screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip
2. screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip

Screens We.Retail執行透過CRX封裝管理員安裝的Ui.Apps和Ui.Content封裝。

screens-weretail-run.ui.apps ​套件會在/apps/weretail-run下方安裝程式碼。

此套件包含負責呈現專案自訂元件的程式碼。 此套件包含元件程式碼及任何所需的JavaScript或CSS。 此套件也內嵌​ screens-weretail-run.core-0.0.1-SNAPSHOT.jar，其中包含專案所需的任何Java™程式碼。

呈現ui.apps程式碼

以CRXDE Lite表示ui.apps程式碼

Hello World ​元件只是預留位置。 在教學課程中新增功能，讓作者可更新元件顯示的訊息。

screens-weretail-run.ui.content ​套件會在下方安裝程式碼：

• /conf/we-retail-run
• /content/dam/we-retail-run
• /content/screens/we-retail-run

此套件包含專案所需的起始內容和設定結構。 /conf/we-retail-run ​包含We.Retail執行專案的所有設定。 /content/dam/we-retail-run ​包括專案的開始數位資產。 /content/screens/we-retail-run ​包含Screens內容結構。 所有這些路徑的內容主要是在AEM中更新。 為了提高環境（本機、開發、舞台、生產）之間的一致性，通常會將基本內容結構儲存在原始檔控制中。

瀏覽至AEM Screens > We.Retail執行專案：

從AEM「開始」功能表，按一下Screens圖示。 驗證是否看到We.Retail執行專案。

在​ CRXDE-Lite ​中，http://localhost:4502/crx/de/index.jsp （或選擇的IDE）導覽至/apps/weretail-run/components/content/helloworld.

將下列屬性新增至helloworld元件：

    jcr:title="Hello World"
    sling:resourceSuperType="foundation/components/parbase"
    componentGroup="We.Retail Run - Content"

/apps/weretail-run/components/content/helloworld 的屬性

/apps/weretail-run/components/content/helloworld的屬性

Hello World ​元件會延伸​ foundation，元件，parbase ​元件，使其可正確用於序列通道中。

在/apps/weretail-run/components/content/helloworld下建立名為helloworld.html.的檔案

將下列專案填入檔案中：

<!--/*

 /apps/weretail-run/components/content/helloworld/helloworld.html

*/-->

<!--/* production: preview authoring mode + unspecified mode (i.e. on publish) */-->
<sly data-sly-test.production="${wcmmode.preview || wcmmode.disabled}" data-sly-include="production.html" />

<!--/* edit: any other authoring mode, i.e. edit, design, scaffolding, etc. */-->
<sly data-sly-test="${!production}" data-sly-include="edit.html" />

根據目前使用的編寫模式，Screens元件需要兩種不同的轉譯：

1. 生產：預覽或Publish模式(wcmmode=disabled)
2. 編輯：用於所有其他編寫模式，例如，編輯、設計、支架、開發人員……

helloworld.html充當切換器，檢查哪一個編寫模式作用中，並重新導向到另一個HTL指令碼。 Screens元件使用的常見慣例是，擁有用於編輯模式的edit.html指令碼和用於生產模式的production.html指令碼。

在/apps/weretail-run/components/content/helloworld下建立名為production.html.的檔案

將下列專案填入檔案中：

<!--/*
 /apps/weretail-run/components/content/helloworld/production.html

*/-->

<div data-duration="${properties.duration}" class="cmp-hello-world">
 <h1 class="cmp-hello-world__message">${properties.message}</h1>
</div>

以上是Hello World元件的生產標籤。 由於元件用於序列頻道，因此包含data-duration屬性。 序列頻道使用data-duration屬性來瞭解序列專案要顯示多久。

元件會呈現包含文字的div和h1標籤。 ${properties.message}是HTL指令碼的一部分，它輸出名為message的JCR屬性內容。 稍後會建立對話方塊，讓使用者輸入message屬性文字的值。

另請注意，元件會使用BEM （區塊元素修飾元）記號。 BEM是CSS編碼慣例，可讓您更輕鬆地建立可重複使用的元件。 BEM是AEM核心元件所使用的記號。

在/apps/weretail-run/components/content/helloworld下建立名為edit.html.的檔案

將下列專案填入檔案中：

<!--/*

 /apps/weretail-run/components/content/helloworld/edit.html

*/-->

<!--/* if message populated */-->
<div
 data-sly-test.message="${properties.message}"
 class="aem-Screens-editWrapper cmp-hello-world">
 <p class="cmp-hello-world__message">${message}</p>
</div>

<!--/* empty place holder */-->
<div data-sly-test="${!message}"
     class="aem-Screens-editWrapper cq-placeholder cmp-hello-world"
     data-emptytext="${'Hello World' @ i18n, locale=request.locale}">
</div>

以上是Hello World元件的已編輯標籤。 如果已填入對話方塊訊息，第一個區塊會顯示元件的已編輯版本。

如果未輸入任何對話方塊訊息，則會轉譯第二個區塊。 cq-placeholder和data-emptytext將標籤​ Hello World ​呈現為該案例中的預留位置。 可使用i18n將標籤的字串國際化，以支援在多個語言環境中撰寫。

複製Screens影像對話方塊以用於Hello World元件。

最簡單的做法是從現有的對話方塊開始，然後進行修改。

1. 複製對話方塊來源： /libs/screens/core/components/content/image/cq:dialog
2. 在/apps/weretail-run/components/content/helloworld下方貼上對話方塊

更新Hello World對話方塊以包含訊息的標籤。

更新對話方塊，使其符合下列內容。 最後對話方塊的JCR節點結構以XML形式顯示如下：

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" 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"
    jcr:primaryType="nt:unstructured"
    jcr:title="Hello World"
    sling:resourceType="cq/gui/components/authoring/dialog">
    <content
        jcr:primaryType="nt:unstructured"
        sling:resourceType="granite/ui/components/coral/foundation/tabs"
        size="L">
        <items jcr:primaryType="nt:unstructured">
            <message
                jcr:primaryType="nt:unstructured"
                jcr:title="Message"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <items jcr:primaryType="nt:unstructured">
                    <column
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="granite/ui/components/coral/foundation/container">
                        <items jcr:primaryType="nt:unstructured">
                            <message
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                                fieldDescription="Message for component to display"
                                fieldLabel="Message"
                                name="./message"/>
                        </items>
                    </column>
                </items>
            </message>
            <sequence
                jcr:primaryType="nt:unstructured"
                jcr:title="Sequence"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <items jcr:primaryType="nt:unstructured">
                    <column
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="granite/ui/components/coral/foundation/container">
                        <items jcr:primaryType="nt:unstructured">
                            <duration
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/form/numberfield"
                                defaultValue=""
                                fieldDescription="Amount of time the image is shown in the sequence, in milliseconds"
                                fieldLabel="Duration (milliseconds)"
                                min="0"
                                name="./duration"/>
                        </items>
                    </column>
                </items>
            </sequence>
        </items>
    </content>
</jcr:root>

訊息的文字欄位已儲存至名為message的屬性，而Duration的數字欄位已儲存至名為duration的屬性。 這兩個屬性都由HTL在/apps/weretail-run/components/content/helloworld/production.html中參照為${properties.message}和${properties.duration}。

Hello World — 完成的對話方塊

為Hello World元件的使用者端資料庫建立資料夾。

在/apps/weretail-run/components/content/helloworld下方，建立名為clientlibs的資料夾。

在clientlibs資料夾下，建立名稱為shared且型別為cq:ClientLibraryFolder的節點。

將下列屬性新增至共用使用者端程式庫：

• allowProxy | 布林值 | true

• categories| 字串[] | cq.screens.components

/apps/weretail-run/components/content/helloworld/clientlibs/shared 的屬性

/apps/weretail-run/components/content/helloworld/clientlibs/shared的屬性

categories屬性是識別使用者端程式庫的字串。 cq.screens.componentscategory會用於編輯和預覽生產模式。 因此，在sharedclientlib中定義的任何CSS或JS都會以所有模式載入。

最佳實務是，絕不應該公開生產環境中任何直接指向/apps的路徑。 allowProxy屬性可確保透過/etc.clientlibs的前置詞參考使用者端程式庫CSS和JS。

在共用資料夾下建立名為css.txt的檔案。

將下列專案填入檔案中：

#base=css

styles.less

在shared資料夾下建立名為css的資料夾。 在css資料夾下新增名為style.less的檔案。 使用者端程式庫的結構現在看起來應該像這樣：

本教學課程不直接撰寫CSS，而是使用LESS。 LESS是一種常用的CSS預先編譯器，支援CSS變數、mixin和函式。 AEM使用者端程式庫原生支援LESS編譯。 可以使用Sass或其他預先編譯程式，但必須在AEM外部編譯。

以下列專案填入/apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less：

/**
    Shared Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less

**/

.cmp-hello-world {
    background-color: #fff;

 &__message {
  color: #000;
  font-family: Helvetica;
  text-align:center;
 }
}

複製並貼上shared使用者端資料庫資料夾，以建立名為production的使用者端資料庫。

複製共用使用者端程式庫以建立生產使用者端程式庫。

將生產使用者端程式庫的categories屬性更新為cq.screens.components.production.

這麼做可確保只在「預覽 — 生產」模式中載入樣式。

/apps/weretail-run/components/content/helloworld/clientlibs/production的屬性。

以下列專案填入/apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less：

/**
    Production Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less

**/
.cmp-hello-world {

    height: 100%;
    width: 100%;
    position: fixed;

 &__message {

  position: relative;
  font-size: 5rem;
  top:25%;
 }
}

上述樣式會在畫面中央顯示訊息，但僅會顯示在「生產」模式中。

在​ CRXDE Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs中，瀏覽至/apps/settings/wcm/designs。

在設計資料夾底下建立名為we-retail-run且型別為cq:Page的節點。

在we-retail-run頁面下方，新增另一個名稱為jcr:content且型別為nt:unstructured的節點。 將下列屬性新增至jcr:content節點：

設計頁面於/apps/settings/wcm/designs/we-retail-run。

從AEM開始功能表，瀏覽至​ Screens > We.Retail執行 >並按一下​ 管道。

按一下​ 建立 ​按鈕

1. 選擇​ 建立實體

在建立精靈中：

範本步驟 — 選擇​ 順序頻道

1. 屬性步驟

• 基本索引標籤>標題= 閒置頻道
• 頻道標籤>檢查​ 讓頻道上線

開啟「閒置頻道」的頁面屬性。

更新Design欄位，使其指向/apps/settings/wcm/designs/we-retail-run （在前一節中建立的設計頁面）。

指向/apps/settings/wcm/designs/we-retail-run的設計設定

編輯新建立的「閒置頻道」，以將其開啟。

將頁面模式切換為​ 設計 ​模式。

1. 按一下Parsys中的​ 扳手 ​圖示，即可設定允許的元件。

2. 按一下​ Screens ​群組和​ We.Retail執行 — 內容 ​群組。

將頁面模式切換為​ 編輯。 Hello World元件現在可以新增到頁面，並與其他「序列」頻道元件結合。

在​ CRXDE Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs/we-retail-run/jcr%3Acontent/sequencechannel/par中，瀏覽至/apps/settings/wcm/designs/we-retail-run/jcr:content/sequencechannel/par。 請注意，components屬性現在包含group:Screens、group:We.Retail Run - Content。

下的設計組態

在/apps/settings/wcm/designs/we-retail-run下的設計設定