自訂AEM CIF核心元件

CIF Venia Project是使用CIF核心元件的參考代碼基。 在本教學課程中,您將進一步擴充Product Teaser元件,以顯示來自Magento的自訂屬性。 您也將進一步了解AEM與Magento之間的GraphQL整合,以及CIF核心元件提供的擴充功能鈎點。

秘訣

開始您自己的商務實作時,請使用AEM專案原型

您要建置的

Venia品牌最近開始使用可持續材料生產某些產品,而企業想要在產品預告中顯示​Eco Friendly​徽章。 將在Magento中建立新的自定義屬性,以指明產品是否使用​Eco friendly​材料。 然後,此自訂屬性將會新增為GraphQL查詢的一部分,並顯示在指定產品的產品預告上。

Eco友好徽章最終實施

必備條件

完成本教學課程需要本機開發環境。 這包括已設定並連線至AEM執行個體的執行中執行個體。 檢閱使用AEM作為Cloud ServiceSDK設定本機開發的需求和步驟。 若要完整遵循本教學課程,您需要權限,才能將屬性新增至Magento中的Product

您還需要GraphQL IDE(如GraphiQL)或瀏覽器擴展,才能運行代碼示例和教程。 如果您安裝瀏覽器擴充功能,請確定它能設定要求標題。 在Google Chrome上,Altair GraphQL用戶端是可執行此作業的擴充功能。

複製Venia專案

我們將複製Venia Project,然後覆寫預設樣式。

注意

歡迎使用現有專案 (根據包含CIF的AEM專案原型),並略過本節。

  1. 執行下列git命令以複製專案:

    $ git clone git@github.com:adobe/aem-cif-guides-venia.git
    
  2. 建立專案並部署至AEM的本機執行個體:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  3. 新增必要的OSGi設定,將您的AEM例項連線至Magento例項,或將設定新增至新建立的專案。

  4. 此時,您應該有連接至Magento例項的店面工作版本。 導覽至US > Home頁面,網址為:http://localhost:4502/editor.html/content/venia/us/en.html

    您應該會看到店面目前使用Venia主題。 展開店面的「主菜單」時,您應該會看到各種類別,表明連接Magento正在工作。

    Venia主題配置的店面

製作Product Teaser

本教學課程將擴充產品預告元件。 首先,將產品預告的新例項新增至首頁,以了解基線功能。

  1. 導覽至網站的​首頁:http://localhost:4502/editor.html/content/acme/us/en.html

  2. 將新的​產品預告​元件插入頁面的主版面容器中。

    插入Product Teaser

  3. 展開「側面板」(如果尚未切換),然後將資產尋找器下拉式清單切換為​Products。 這應會顯示連線Magento例項的可用產品清單。 選取產品,並將​拖放​它拖放至頁面上的​Product Teaser​元件。

    拖放產品預告

    注意

    請注意,您也可以使用對話方塊設定元件,以設定顯示的產品(按一下​_扳手_​圖示)。

  4. 您現在應該會看到產品預告顯示。 產品名稱和產品價格是顯示的預設屬性。

    Product Teaser — 預設樣式

在Magento中新增自訂屬性

AEM中顯示的產品和產品資料會儲存在Magento中。 接下來,使用MagentoUI,在產品屬性集中為​Eco Friendly​添加新屬性。

秘訣

已有自訂​Yes/No​屬性作為產品屬性集的一部分? 歡迎使用,並略過本節。

  1. 登入您的Magento例項。

  2. 導覽至​Catalog > Products

  3. 更新搜尋篩選器,以尋找在上一個練習中新增至Teaser元件時所使用的​可設定產品。 在編輯模式中開啟產品。

    搜尋有效產品

  4. 在產品檢視中,按一下「新增屬性​>​建立新屬性​」。

  5. 使用下列值填寫​新屬性​表單(保留其他值的預設設定)

    欄位集 欄位標籤
    屬性屬性 屬性標籤 生態友好
    屬性屬性 目錄輸入類型 是/否
    進階屬性 屬性代碼 eco_friendly

    新屬性表單

    完成後,按一下​儲存屬性

  6. 捲動至產品底部,然後展開​Attributes​標題。 您應該會看到新的​Eco Friendly​欄位。 將切換為​Yes

    切換為「是」

    ​儲存對產品的變更。

  7. 導航至​System > Tools > Cache Management。 由於資料架構已更新,因此我們需要使Magento中的某些快取類型失效。

  8. 勾選​Configuration​旁的方塊,並提交​Refresh​的快取類型

    刷新配置快取類型

使用GraphQL IDE驗證屬性

跳入AEM程式碼之前,請先使用GraphQL IDE探索MagentoGraphQL。 與AEM的Magento整合主要是透過一系列GraphQL查詢完成。 了解和修改GraphQL查詢是擴充CIF核心元件的關鍵方式之一。

接下來,使用GraphQL IDE驗證eco_friendly屬性已添加到產品屬性集中。 本教程中的螢幕截圖是使用Altair GraphQL客戶端

  1. 開啟GraphQL IDE,然後在IDE或擴展的URL欄中輸入URL http://<magento-server>/graphql

  2. 新增下列產品查詢,其中YOUR_SKU是上次練習中所用產品的​SKU:

      {
        products(
        filter: { sku: { eq: "YOUR_SKU" } }
        ) {
            items {
            name
            sku
            eco_friendly
            }
        }
    }
    
  3. 執行查詢,您應得到如下的回應:

    {
      "data": {
        "products": {
          "items": [
            {
              "name": "Valeria Two-Layer Tank",
              "sku": "VT11",
              "eco_friendly": 1
            }
          ]
        }
      }
    }
    

    範例GraphQL回應

    請注意,值​Yes​是整數​1。 以Java編寫GraphQL查詢時,此功能會相當實用。

更新Product Teaser的Sling模型

接下來,我們將實作Sling模型,以擴充Product Teaser的商業邏輯。 Sling模型是註解導向的「POJO」(純舊Java物件),可實作元件所需的任何商業邏輯。Sling模型與HTL指令碼搭配使用,是元件的一部分。 我們將遵循Sling模型🔗的委派模式,以便只擴充部分現有產品預告模型。

Sling模型以Java方式實作,可在產生專案的​core​模組中找到。

使用您選擇的IDE🔗導入Venia項目。 使用的螢幕截圖來自Visual Studio代碼IDE

  1. 在IDE中,導覽至​core​模組下方:core/src/main/java/com/venia/core/models/commerce/MyProductTeaser.java

    核心位置IDE

    MyProductTeaser.java 是可擴充CIF ProductTeaser介面的 🔗 Java介面。

    已新增名為isShowBadge()的新方法,如果產品被視為「新」,則會顯示徽章。

  2. 將新方法isEcoFriendly()添加到介面:

    @ProviderType
    public interface MyProductTeaser extends ProductTeaser {
        // Extend the existing interface with the additional properties which you
        // want to expose to the HTL template.
        public Boolean isShowBadge();
    
        public Boolean isEcoFriendly();
    }
    

    這是我們將引入的新方法,用於封裝邏輯,以指示產品的eco_friendly屬性是否設定為​Yes​或​No

  3. 接下來,在core/src/main/java/com/venia/core/models/commerce/MyProductTeaserImpl.java檢查MyProductTeaserImpl.java

    Sling模型🔗的委派模式允許MyProductTeaserImpl透過sling:resourceSuperType屬性參考ProductTeaser模型:

    @Self
    @Via(type = ResourceSuperType.class)
    private ProductTeaser productTeaser;
    

    對於我們不想覆寫或變更的所有方法,我們只需傳回ProductTeaser傳回的值即可。 例如:

    @Override
    public String getImage() {
        return productTeaser.getImage();
    }
    

    這可將實施需要寫入的Java程式碼量降至最低。

  4. AEM CIF核心元件提供的額外擴充點之一,是可存取特定產品屬性的AbstractProductRetriever。 Inspect initModel()方法:

    import javax.annotation.PostConstruct;
    ...
    @Model(adaptables = SlingHttpServletRequest.class, adapters = MyProductTeaser.class, resourceType = MyProductTeaserImpl.RESOURCE_TYPE)
    public class MyProductTeaserImpl implements MyProductTeaser {
        ...
        private AbstractProductRetriever productRetriever;
    
        /* add this method to intialize the proudctRetriever */
        @PostConstruct
        public void initModel() {
            productRetriever = productTeaser.getProductRetriever();
    
            if (productRetriever != null) {
                productRetriever.extendProductQueryWith(p -> p.createdAt());
            }
    
        }
    ...
    

    @PostConstruct附註可確保Sling模型初始化後立即呼叫此方法。

    請注意,已使用extendProductQueryWith方法擴展產品GraphQL查詢,以檢索其他created_at屬性。 此屬性後來作為isShowBadge()方法的一部分使用。

  5. 更新GraphQL查詢,將eco_friendly屬性包含在部分查詢中:

    //MyProductTeaserImpl.java
    
    private static final String ECO_FRIENDLY_ATTRIBUTE = "eco_friendly";
    
    @PostConstruct
    public void initModel() {
        productRetriever = productTeaser.getProductRetriever();
    
        if (productRetriever != null) {
            productRetriever.extendProductQueryWith(p -> p
                .createdAt()
                .addCustomSimpleField(ECO_FRIENDLY_ATTRIBUTE)
            );
        }
    }
    

    extendProductQueryWith方法添加是一種功能強大的方法,可確保模型的其餘部分可以使用其他產品屬性。 它也會將執行的查詢數量降至最低。

    在上述程式碼中,addCustomSimpleField用於擷取eco_friendly屬性。 這說明如何查詢屬於Magento結構的任何自訂屬性。

    注意

    createdAt()方法實際上已作為產品介面的一部分實施。 最常找到的結構屬性大多已實作,因此,請僅使用addCustomSimpleField作為真正的自訂屬性。

  6. 新增記錄器以協助偵錯Java程式碼:

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    ...
    @Model(adaptables = SlingHttpServletRequest.class, adapters = MyProductTeaser.class, resourceType = MyProductTeaserImpl.RESOURCE_TYPE)
    public class MyProductTeaserImpl implements MyProductTeaser {
    
    private static final Logger LOGGER = LoggerFactory.getLogger(MyProductTeaserImpl.class);
    
  7. 接下來,實作isEcoFriendly()方法:

    @Override
    public Boolean isEcoFriendly() {
    
        Integer ecoFriendlyValue;
        try {
            ecoFriendlyValue = productRetriever.fetchProduct().getAsInteger(ECO_FRIENDLY_ATTRIBUTE);
            if(ecoFriendlyValue != null && ecoFriendlyValue.equals(Integer.valueOf(1))) {
                LOGGER.info("*** Product is Eco Friendly**");
                return true;
            }
        } catch (SchemaViolationError e) {
            LOGGER.error("Error retrieving eco friendly attribute");
        }
        LOGGER.info("*** Product is not Eco Friendly**");
        return false;
    }
    

    在上述方法中,使用productRetriever來擷取產品,使用getAsInteger()方法來取得eco_friendly屬性的值。 根據我們先前執行的GraphQL查詢,我們知道當eco_friendly屬性設為"Yes"時,預期值實際上為​1​的整數。

    現在Sling模型已更新,需要更新元件標籤,才能根據Sling模型實際顯示​Eco Friendly​的指標。

自訂Product Teaser的標籤

AEM元件的常見擴充功能是修改元件產生的標籤。 若要這麼做,請覆寫元件用來呈現其標籤的 HTL指令碼。 HTML範本語言(HTL)是一種精簡的範本語言,AEM元件可用來根據製作的內容動態轉譯標籤,以允許重複使用元件。 例如,產品預告可反複重複使用,以顯示不同的產品。

在此情況下,我們想在預告頂端呈現橫幅,以根據自訂屬性指出產品為「生態友好」。 自訂元件標籤的設計模式實際上是所有AEM元件的標準,而不只是AEM CIF核心元件。

注意

如果您使用CIF產品和類別選擇器(例如此產品預告)或CIF頁面元件來自訂元件,請務必在元件對話方塊中加入所需的cif.shell.picker clientlib。 如需詳細資訊,請參閱CIF產品與類別選擇器使用

  1. 在IDE中,導航並展開ui.apps模組,然後展開資料夾層次結構以:ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser並檢查.content.xml檔案。

    Product Teaser ui.apps

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
        jcr:description="Product Teaser Component"
        jcr:primaryType="cq:Component"
        jcr:title="Product Teaser"
        sling:resourceSuperType="core/cif/components/commerce/productteaser/v1/productteaser"
        componentGroup="Venia - Commerce"/>
    

    以上是專案中產品預告元件的元件定義。 請注意屬性sling:resourceSuperType="core/cif/components/commerce/productteaser/v1/productteaser"。 這是建立代理元件的示例。 我們不必從AEM CIF核心元件複製並貼上所有Product Teaser HTL指令碼,而是可使用sling:resourceSuperType繼承所有功能。

  2. 開啟檔案productteaser.html。 這是CIF產品預告productteaser.html檔案的副本

    <!--/* productteaser.html */-->
    <sly
      data-sly-use.product="com.venia.core.models.commerce.MyProductTeaser"
      data-sly-use.templates="core/wcm/components/commons/v1/templates.html"
      data-sly-use.actionsTpl="actions.html"
      data-sly-test.isConfigured="${properties.selection}"
      data-sly-test.hasProduct="${product.url}"
    ></sly>
    

    請注意,MyProductTeaser的Sling模型已使用,並指派給product變數。

  3. 修改productteaser.html以呼叫前一個練習中實作的isEcoFriendly方法:

    ...
    <div
      data-sly-test="${isConfigured && hasProduct}"
      class="item__root"
      data-cmp-is="productteaser"
      data-virtual="${product.virtualProduct}"
    >
      <div data-sly-test="${product.showBadge}" class="item__badge">
        <span>${properties.text || 'New'}</span>
      </div>
      <!--/* Insert call to Eco Friendly here */-->
      <div data-sly-test="${product.ecoFriendly}" class="item__eco">
        <span>Eco Friendly</span>
      </div>
      ...
    </div>
    

    在HTL中呼叫Sling Model方法時,方法的getis部分會遭到捨棄,而第一個字母會變成小寫。 因此,isShowBadge()變成.showBadge,而isEcoFriendly變成.ecoFriendly。 根據從.isEcoFriendly()返回的布林值確定是否顯示<span>Eco Friendly</span>

    如需data-sly-test和其他 HTL區塊陳述式的詳細資訊,請參閱此處

  4. 使用Maven技能,從命令列終端儲存變更並將更新部署至AEM:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  5. 開啟新的瀏覽器視窗,並導覽至AEM和​OSGi主控台 > Status > Sling模型:http://localhost:4502/system/console/status-slingmodels

  6. 搜尋MyProductTeaserImpl,您應該會看到如下所示的一行:

    com.venia.core.models.commerce.MyProductTeaserImpl - venia/components/commerce/productteaser
    

    這表示Sling模型已正確部署並對應至正確的元件。

  7. http://localhost:4502/editor.html/content/venia/us/en.html重新整理至已新增產品預告的​Venia首頁

    顯示「生態友好」消息

    如果產品的eco_friendly屬性設定為​Yes,您應該會在頁面上看到「Eco Friendly」文字。 嘗試切換至不同的產品,以查看行為變更。

  8. 接下來開啟AEM error.log ,查看我們新增的記錄陳述式。 error.log位於<AEM SDK Install Location>/crx-quickstart/logs/error.log

    搜尋AEM記錄檔,以查看Sling模型中新增的記錄陳述式:

    2020-08-28 12:57:03.114 INFO [com.venia.core.models.commerce.MyProductTeaserImpl] *** Product is Eco Friendly**
    ...
    2020-08-28 13:01:00.271 INFO [com.venia.core.models.commerce.MyProductTeaserImpl] *** Product is not Eco Friendly**
    ...
    
    注意

    如果預告中使用的產品在其屬性集中沒有eco_friendly屬性,您也可能會看到一些堆棧跟蹤。

為Eco友好徽章添加樣式

此時,Eco Friendly​徽章顯示時機的邏輯正在運作,但純文字可能會使用某些樣式。 接下來,在ui.frontend模組中新增圖示和樣式以完成實作。

  1. 下載eco_friendly.svg檔案。 這將用作​Eco Friendly​徽章。

  2. 返回IDE並導航到ui.frontend資料夾。

  3. eco_friendly.svg檔案添加到ui.frontend/src/main/resources/images資料夾:

    已添加Eco Friendly SVG

  4. ui.frontend/src/main/styles/commerce/_productteaser.scss開啟檔案productteaser.scss

  5. .productteaser類別內新增下列Sass規則:

    .productteaser {
        ...
        .item__eco {
            width: 60px;
            height: 60px;
            left: 0px;
            overflow: hidden;
            position: absolute;
            padding: 5px;
    
        span {
            display: block;
            position: absolute;
            width: 45px;
            height: 45px;
            text-indent: -9999px;
            background: no-repeat center center url('../resources/images/eco_friendly.svg');
            }
        }
    ...
    }
    
    注意

    如需前端工作流程的詳細資訊,請參閱樣式CIF核心元件

  6. 使用Maven技能,從命令列終端儲存變更並將更新部署至AEM:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  7. http://localhost:4502/editor.html/content/venia/us/en.html重新整理至已新增產品預告的​Venia首頁

    Eco友好徽章最終實施

恭喜

您剛自訂了第一個AEM CIF元件! 在此處🔗下載已完成的解決方案檔案。

獎金挑戰

檢閱已在產品預告中實作的​New​徽章的功能。 請嘗試新增其他核取方塊,讓作者控制何時應顯示​Eco Friendly​徽章。 您需要在ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser/_cq_dialog/.content.xml更新元件對話方塊。

新徽章實作挑戰

其他資源

本頁內容