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

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

ヒント

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

作成する内容

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

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

前提条件

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

また、コード例やチュートリアルを実行するには、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 -PautoInstallSinglePackage,cloud

  3. AEM インスタンスを Adobe Commerce インスタンスに接続するために必要な OSGi 構成を追加するか、新しく作成されたプロジェクトに構成を追加します。

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

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

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

製品ティーザーの作成

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

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

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

    製品ティーザーの挿入

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

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

    メモ

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

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

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

Adobe Commerce でのカスタム属性の追加

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

ヒント

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

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

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

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

    Valeria 製品の検索

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

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

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

    新規属性フォーム

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

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

    「はい」に切り替える

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

    ヒント

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

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

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

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

    ヒント

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

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

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

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

  1. GraphQL IDE を開き、IDE または拡張機能の URL バーに URL http://<commerce-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 で記述する場合に役立ちます。

    ヒント

    Adobe Commerce 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.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 コアコンポーネントが提供する拡張ポイントの 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 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 属性を部分クエリに含めます。

    //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 スキーマの一部であるカスタム属性をクエリする方法を説明します。

    メモ

    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 -PautoInstallSinglePackage,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.scss（ui.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 -PautoInstallSinglePackage,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 でコンポーネントダイアログをアップデートする必要があります。

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

その他のリソース

このページ