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

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

ヒント

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

作成する内容

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

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

前提条件

このチュートリアルを完了するには、ローカルの開発環境が必要です。これには、Magento インスタンスに設定および接続された AEM の実行インスタンスが含まれます。AEM🔗でローカル開発を設定する際の要件と手順を確認します。 このチュートリアルを完全に実行するには、属性を Magento 内の製品に追加する権限が必要になります。

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

Veniaプロジェクトのクローン

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

メモ

(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 -PautoInstallPackage,cloud
    
  3. AEM インスタンスを Magento インスタンスに接続するために必要な OSGi 構成を追加するか、新しく作成されたプロジェクトに構成を追加します。

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

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

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

製品ティーザーの作成

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

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

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

    製品ティーザーの挿入

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

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

    メモ

    ダイアログ(レンチ​アイコンをクリック)を使用してコンポーネントを設定することで、表示された製品を設定することもできます。

  4. これで、製品ティーザーによって製品が表示されます。製品名と製品の価格は、表示されるデフォルトの属性です。

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

Magentoにカスタム属性を追加する

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

ヒント

製品属性セットの一部として、既にカスタムの​はい/いいえ​属性がある場合は、それを使用して、この節をスキップしてください。

  1. Magento インスタンスにログインします。

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

  3. 検索フィルターをアップデートして、前の練習でティーザーコンポーネントに追加した場合に使用する​構成可能な製品​を見つけます。製品を編集モードで開きます。

    Valeria 製品の検索

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

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

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

    新規属性フォーム

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

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

    「はい」に切り替える

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

    ヒント

    製品属性の管理の詳細については、『Magento ユーザーガイド』を参照してください。

  7. システムツールキャッシュ管理​に移動します。データスキーマはアップデートされたので、Magento 内のキャッシュタイプの一部を無効にする必要があります。

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

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

    ヒント

    キャッシュ管理の詳細については、『Magento ユーザーガイド』を参照してください。

GraphQL IDEを使用した属性の検証

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

次に、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 の応答例

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

    ヒント

    Magento GraphQL に関する詳細なドキュメントは、こちらを参照してください。

製品ティーザーの Sling モデルのアップデート

次に、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() メソッドをインターフェイスに追加します。

    @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 モデルを参照できます。

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

    上書きや変更を望まないすべてのメソッドに対しては、単に ProductTeaser の戻り値を返すだけです。次に例を示します。

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

    これにより、実装で記述する必要のある Java コードの量を最小限に抑えることができます。

  4. AEM CIF コアコンポーネントが提供する拡張ポイントの 1 つに、特定の製品属性へのアクセスを提供する AbstractProductRetriever があります。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 モデルが初期化されるとすぐにこのメソッドが呼び出されます。

    製品のGraphQLクエリは、追加のcreated_at属性を取得するためにextendProductQueryWithメソッドを使用して既に拡張されています。 この属性は、後で 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 ->
                 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 属性が「はい」に設定された場合の期待値は、実際には整数 1 であることがわかっています。

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

製品ティーザーのマークアップのカスタマイズ

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

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

メモ

この製品ティーザーや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

    <?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 ファイルのコピーです。

    <!--/* 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>
    

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

    data-sly-test などの HTL ブロック文の詳細については、こちらを参照してください。

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

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

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

    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 モデルに追加されたログ文を確認します。

    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 属性を持たない場合は、スタックトレースが表示されることがあります。

エコフレンドリーバッジのスタイルの追加

この時点で、エコフレンドリー​バッジを表示するタイミングのロジックは機能していますが、プレーンテキストなのでスタイルを設定できます。次に、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 クラス内に追加します。

    .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 -PautoInstallPackage,cloud
    
  7. Venia ホームページhttp://localhost:4502/editor.html/content/venia/us/en.html)を更新します。製品ティーザーが追加されています。

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

これで完了です

最初の AEM CIF コンポーネントをカスタマイズしました。完成したソリューションファイルをこちらからダウンロードしてください。

ボーナスチャレンジ

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

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

その他のリソース

このページ