AEM CIF コアコンポーネントのカスタマイズ customize-cif-components

CIF Venia プロジェクトは、CIF コアコンポーネントを使用するための参照用コードベースです。このチュートリアルでは、製品ティーザーコンポーネントをさらに拡張して、Adobe Commerce のカスタム属性を表示します。また、AEM と Adobe Commerce 間の GraphQL 統合、および CIF コアコンポーネントによって提供される拡張フックについても学習します。

TIP
独自のコマース実装を開始する際に AEM プロジェクトアーキタイプを使用します。

作成する内容

Venia ブランドは最近、持続可能な資材を使用して一部の製品を製造し始めました。同社は、エコフレンドリー ​バッジを製品ティーザーの一部として表示したいと考えています。製品が​ エコフレンドリー ​な素材を使用しているかどうかを示す新しいカスタム属性が Adobe Commerce に作成されます。このカスタム属性が GraphQL クエリの一部として追加され、特定の製品の製品ティーザーに表示されます。

エコフレンドリーバッジの最終実装

前提条件 prerequisites

このチュートリアルを完了するには、ローカルの開発環境が必要です。この環境には、Adobe Commerce インスタンスに設定および接続された AEM の実行インスタンスが含まれます。AEM as a Cloud Service SDK を使用してローカル開発をセットアップするための要件と手順を確認します。このチュートリアルを完全に実行するには、属性を Adobe Commerce 内の製品に追加する権限が必要になります。

また、コード例やチュートリアルを実行するには、GraphiQL またはブラウザー拡張機能などの GraphQL IDE が必要です。ブラウザー拡張機能をインストールする場合は、その拡張機能にリクエストヘッダーを設定できることを確認してください。Google Chrome の Altair GraphQL Client は、ジョブを実行できる拡張機能の 1 つです。

Venia プロジェクトのクローン clone-venia-project

Venia プロジェクトのクローンを作成して、デフォルトのスタイルを上書きします。

NOTE
(CIF を含む AEM プロジェクトアーキタイプに基づく)既存のプロジェクトを使用 ​する場合、この節をスキップできます。
  1. 次の Git コマンドを実行すると、プロジェクトのクローンを作成できます。

    code language-shell
    $ git clone git@github.com:adobe/aem-cif-guides-venia.git
    
  2. プロジェクトをビルドしてローカル AEM インスタンスにデプロイします。

    code language-shell
    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  3. AEM インスタンスを Adobe Commerce インスタンスに接続するために必要な OSGi 設定を追加するか、作成されたプロジェクトに設定を追加します。

  4. この時点で、Adobe Commerce インスタンスに接続されたストアフロントの作業用のバージョンが必要です。USHome ページ(http://localhost:4502/editor.html/content/venia/us/en.html)にアクセスします。

    ストアフロントは現在 Venia テーマを使用しています。ストアフロントのメインメニューを展開すると、様々なカテゴリが表示され、Adobe Commerce への接続が機能していることが示されます。

    Venia テーマで構成されたストアフロント

製品ティーザーの作成 author-product-teaser

製品ティーザーコンポーネントの拡張は、このチュートリアル全体で行われます。最初の手順として、製品ティーザーのインスタンスをホームページに追加し、ベースライン機能を理解します。

  1. サイトの​ ホームページhttp://localhost:4502/editor.html/content/acme/us/en.html)に移動します。

  2. ページのメインレイアウトコンテナに新しい​ 製品ティーザー ​コンポーネントを挿入します。

    製品ティーザーの挿入

  3. サイドパネルを展開し(まだ切り替えていない場合)、アセットファインダードロップダウンリストを​ 製品 ​に切り替えます。接続された Adobe Commerce インスタンスから使用可能な製品のリストが表示されます。製品を選択し、ページ上の​ 製品ティーザー ​コンポーネントに​ ドラッグ&ドロップ ​します。

    製品ティーザーのドラッグ&ドロップ

    note note
    NOTE
    ダイアログ(レンチ ​アイコンをクリック)を使用してコンポーネントを設定することで、表示された製品を設定することもできます。
  4. これで、製品ティーザーによって製品が表示されます。製品名と製品の価格は、表示されるデフォルトの属性です。

    製品ティーザー - デフォルトスタイル

Adobe Commerce でのカスタム属性の追加 add-custom-attribute

AEM に表示された製品と製品データは Adobe Commerce に格納されます。次に、Adobe Commerce UI を使用して設定する製品属性の一部として、エコフレンドリー ​属性を追加します。

TIP
製品属性セットの一部として、既にカスタムの​ はい/いいえ ​属性がある場合は、それを使用して、この節をスキップしてください。
  1. Adobe Commerce インスタンスにログオンします。

  2. カタログ製品 ​に移動します。

  3. 検索フィルターを更新して、前の演習でティーザーコンポーネントに追加した場合に使用する​ コンフィグ商品 ​を見つけます。製品を編集モードで開きます。

    Valeria 製品の検索

  4. 製品の表示で、属性を追加新しい属性を作成 ​をクリックします。

  5. 次の値を使用して​ 新規属性 ​フォームに入力します(他の値はデフォルト設定のままにします)。

    table 0-row-3 1-row-3 2-row-3 3-row-3
    フィールドセット フィールドラベル
    属性プロパティ 属性ラベル エコフレンドリー
    属性プロパティ カタログ入力タイプ はい/いいえ
    高度な属性プロパティ 属性コード eco_friendly

    新規属性フォーム

    終了したら「属性を保存」をクリックします。

  6. 製品の下部までスクロールし、「属性」見出しを展開します。新しい「エコフレンドリー」フィールドが表示されます。切り替えボタンを「はい」に切り替えます。

    「はい」に切り替える

    変更内容を製品に​ 保存 ​します。

    note tip
    TIP
    製品属性の管理の詳細については、Adobe Commerce ユーザーガイドを参照してください。
  7. システムツールキャッシュ管理 ​に移動します。データスキーマが更新されたので、Adobe Commerce で一部のキャッシュタイプを無効にする必要があります。

  8. 設定」の横のチェックボックスをオンにして、更新 ​用にキャッシュタイプを送信します。

    構成キャッシュタイプの更新

    note tip
    TIP
    キャッシュ管理の詳細については、Adobe Commerce ユーザーガイドを参照してください。

GraphQL IDE を使用した属性の検証 use-graphql-ide

AEM コードに立ち入る前に、GraphQL IDE を使用して GraphQL の概要を調べてみると役に立ちます。AEM との Adobe Commerce 統合は、主に一連の GraphQL クエリを介して実行されます。GraphQL クエリを理解し変更することは、CIF コアコンポーネントを拡張するのに重要なことの 1 つです。

次に、GraphQL IDE を使用して、eco_friendly 属性が製品属性セットに追加されたことを確認します。このチュートリアルのスクリーンショットには、Altair GraphQL クライアント ​の Google Chrome 拡張機能を使用しています。

  1. GraphQL IDE を開き、IDE または拡張機能の URL バーに URL http://<commerce-server>/graphql を入力します。

  2. 次の製品クエリを追加します。ここで、YOUR_SKU は、前の演習で使用した製品の SKU です。

    code language-json
      {
        products(
        filter: { sku: { eq: "YOUR_SKU" } }
        ) {
            items {
            name
            sku
            eco_friendly
            }
        }
    }
    
  3. クエリを実行すると、次のような応答が返されます。

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

    GraphQL の応答例

    はい」の値は整数 1 です。この値は、GraphQL クエリを Java™ で記述する場合に役立ちます。

    note tip
    TIP
    詳しくは、Adobe Commerce GraphQL を参照してください。

製品ティーザーの Sling モデルのアップデート updating-sling-model-product-teaser

次に、Sling モデルを実装して、製品ティーザーのビジネスロジックを拡張します。Sling モデルは、コンポーネントで必要なビジネスロジックを実装する注釈駆動型の「POJO」(Plain Old Java™ Objects)です。Sling モデルは、コンポーネントの一部として HTL スクリプトと組み合わせて使用されます。既存の製品ティーザーモデルの一部を拡張できるように、Sling モデルの委任パターンに従います。

Sling モデルは Java として実装され、生成されたプロジェクトの​ コア ​モジュールにあります。

任意の IDE を使用して、Venia プロジェクトをインポートします。使用したクリーンショットは、Visual Studio Code IDE からのものです。

  1. IDE で、コア ​モジュールの下に移動して、次の操作を行います。core/src/main/java/com/venia/core/models/commerce/MyProductTeaser.java

    コアのロケーション IDE

    MyProductTeaser.java は、CIF 製品ティーザーインターフェイスを拡張する Java™ インターフェイスです。

    製品が「新規」と見なされた場合にバッジを表示するための新しい isShowBadge() メソッドが既に追加されています。

  2. isEcoFriendly() をアプリに追加します。

    code language-java
    @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 属性が「はい」と「いいえ」のどちらに設定されているかを示すロジックをカプセル化する新しいメソッドです。

  3. 次に、core/src/main/java/com/venia/core/models/commerce/MyProductTeaserImpl.javaMyProductTeaserImpl.java を検査します。

    Sling モデルの委任パターンを使用すると、MyProductTeaserImplsling:resourceSuperType プロパティを介して ProductTeaser モデルを参照できます。

    code language-java
    @Self
    @Via(type = ResourceSuperType.class)
    private ProductTeaser productTeaser;
    

    上書きまたは変更したくないメソッドについては、ProductTeaser が返す値を返すことができます。例:

    code language-java
    @Override
    public String getImage() {
        return productTeaser.getImage();
    }
    

    この方法を使用すると、実装で記述する必要のある Java™ コードの量を最小限に抑えることができます。

  4. AEM CIF コアコンポーネントが提供する拡張ポイントの 1 つに、特定の製品属性へのアクセスを提供する AbstractProductRetriever があります。initModel() メソッドを検査します。

    code language-java
    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 initialize the productRetriever */
        @PostConstruct
        public void initModel() {
            productRetriever = productTeaser.getProductRetriever();
    
            if (productRetriever != null) {
                productRetriever.extendProductQueryWith(p -> p.createdAt());
            }
    
        }
    ...
    

    @PostConstruct 注釈により、Sling モデルが初期化されるとこのメソッドが呼び出されます。

    製品の GraphQL クエリは、追加の created_at 属性を取得するように、extendProductQueryWith メソッドを使用して既に拡張されています。この属性は、後で isShowBadge() メソッドの一部として使用されます。

  5. GraphQL クエリをアップデートし、eco_friendly 属性を部分クエリに含めます。

    code language-java
    //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 メソッドに追加すると、他の製品属性を確実にモデルの残りの部分で使用できるようになります。また、実行されるクエリの数も最小限に抑えられます。

    上記のコードでは、eco_friendly 属性を取得するために addCustomSimpleField が使用されています。この属性では、Adobe Commerce スキーマの一部であるカスタム属性をクエリする方法を説明します。

    note note
    NOTE
    createdAt() メソッドは、製品インターフェイスの一部として実装されています。一般的なスキーマ属性のほとんどは実装されているので、真のカスタム属性に対してのみ addCustomSimpleField を使用します。
  6. ロガーを追加して、Java™ コードをデバッグできるようにします。

    code language-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() メソッドを実装します。

    code language-java
    @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 属性が「はい」に設定された場合の期待値は、実際には整数 1 であることがわかります。

    Sling モデルが更新されたので、Sling モデルに基づいて​ エコフレンドリー ​という指標を実際に表示するには、コンポーネントマークアップを更新する必要があります。

製品ティーザーのマークアップのカスタマイズ customize-markup-product-teaser

AEM コンポーネントの一般的な拡張機能は、コンポーネントによって生成されたマークアップを変更することです。この編集を行うには、コンポーネントがマークアップのレンダリングに使用する HTL スクリプトを上書きします。HTML テンプレート言語(HTL)は、軽量なテンプレート言語です。AEM コンポーネントを使用して、作成されたコンテンツに基づいてマークアップを動的にレンダリングするので、コンポーネントの再利用が可能になります。例えば、製品ティーザーを何度も再利用して、様々な製品を表示できます。

この例では、ティーザーの上部にバナーをレンダリングして、カスタム属性に基づいて製品が「エコフレンドリー」であることを示します。コンポーネントのマークアップをカスタマイズするデザインパターンは、AEM CIF コアコンポーネントだけでなく、すべての AEM コンポーネントの標準です。

NOTE
この製品ティーザーや 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 ファイルを検査します。

    製品ティーザー ui.apps

    code language-xml
    <?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 コアコンポーネントから製品ティーザー HTL スクリプトをコピー&ペーストする代わりに、sling:resourceSuperType を使用してすべての機能を継承できます。

  2. productteaser.html ファイルを開きます。このファイルは、CIF 製品ティーザーからの productteaser.html ファイルのコピーです。

    code language-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. 前の演習で実装した isEcoFriendly メソッドを呼び出せるように productteaser.html を変更します。

    code language-html
    ...
    <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>
    

    Sling モデルメソッドを HTL で呼び出すと、メソッドの get および is 部分が削除され、最初の文字が小文字に変換されます。isShowBadge().showBadge となり、isEcoFriendly.ecoFriendly となります。.isEcoFriendly() から返されるブール値に基づいて、<span>Eco Friendly</span> が表示されるかどうかを決定します。

    data-sly-test およびその他の HTL ブロックステートメントについて詳しくは、HTL の仕様を参照してください。

  4. 変更を保存し、コマンドラインターミナルから Maven スキルを使用して、AEM にアップデートをデプロイします。

    code language-shell
    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  5. 新しいブラウザーウィンドウを開いて AEM に移動し、OSGi コンソールステータスSling モデルhttp://localhost:4502/system/console/status-slingmodels に移動します。

  6. MyProductTeaserImpl を検索すると、次のような行が表示されます。

    code language-plain
    com.venia.core.models.commerce.MyProductTeaserImpl - venia/components/commerce/productteaser
    

    この行は、Sling モデルが正しくデプロイされ、正しいコンポーネントにマッピングされていることを示します。

  7. Venia ホームページhttp://localhost:4502/editor.html/content/venia/us/en.html)を更新します。製品ティーザーが追加されています。

    エコフレンドリーメッセージの表示

    製品の eco_friendly 属性が「はい」に設定されている場合、ページに「エコフレンドリー」というテキストが表示されます。異なる製品に切り替えて、動作の変更を確認してください。

  8. 次に AEM error.log を開き、追加したログ文を確認します。error.log は、<AEM SDK Install Location>/crx-quickstart/logs/error.log にあります。

    AEM ログを検索して、Sling モデルに追加されたログ文を確認します。

    code language-plain
    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**
    ...
    
    note caution
    CAUTION
    また、ティーザーで使用される製品が属性セットの一部としての eco_friendly 属性を持たない場合にも、スタックトレースが表示されることがあります。

エコフレンドリーバッジにスタイルを追加 add-styles

この時点で、エコフレンドリー ​バッジを表示するタイミングのロジックは機能していますが、プレーンテキストなのでスタイルを設定できます。次に、ui.frontend モジュールにアイコンとスタイルを追加し、実装を完了します。

  1. eco_friendly.svg ファイルをダウンロードします。このファイルは、エコフレンドリー ​バッジとして使用されます。

  2. IDE に戻り、ui.frontend フォルダーに移動します。

  3. eco_friendly.svg ファイルを ui.frontend/src/main/resources/images フォルダーに格納します。

    エコフレンドリー SVG の追加

  4. productteaser.scssui.frontend/src/main/styles/commerce/_productteaser.scss)ファイルを開きます。

  5. 次の Sass ルールを .productteaser クラス内に追加します。

    code language-scss
    .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');
            }
        }
    ...
    }
    
    note note
    NOTE
    フロントエンドワークフローに関する詳細については、「CIF コアコンポーネントのスタイル設定」を参照してください。
  6. 変更を保存し、コマンドラインターミナルから Maven スキルを使用して、AEM にアップデートをデプロイします。

    code language-shell
    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  7. Venia ホームページhttp://localhost:4502/editor.html/content/venia/us/en.html)を更新します。製品ティーザーが追加されています。

    エコフレンドリーバッジの最終実装

これで完了です congratulations

最初の AEM CIF コンポーネントをカスタマイズしました。ソリューションファイルは、こちらからダウンロードできます。

ボーナスチャレンジ bonus-challenge

製品ティーザーに既に実装されている​ 新規 ​バッジの機能を確認します。作成者が​ エコフレンドリー ​バッジをいつ表示するかを制御するためのチェックボックスを追加してみます。次の場所にあるコンポーネントダイアログボックスを更新します。ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser/_cq_dialog/.content.xml

新しいバッジの実装の課題

その他のリソース additional-resources

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