モジュール定義ファイル

[アーティクル]
07/30/2024

この記事では、Microsoft Dynamics 365 Commerce のモジュール定義ファイルについて説明します。

モジュール定義ファイル MODULE_NAME.definition.json は、モジュールを登録し、Dynamics 365 Commerce サイトビルダーツールにメタデータを提供するために使用されます。このメタデータには、モジュール名、説明、カテゴリ、および構成が含まれます。

モジュール定義ファイルの例を次に示します。

{
    "$type": "contentModule",
    "friendlyName": "Product Feature",
    "name": "product-feature",
    "description": "Feature module used to highlight a product.",
    "categories": ["marketing"],
    "tags": [""],
    "dataActions": {
        "products":{
            "path": "@msdyn365-commerce-modules/retail-actions/dist/lib/get-simple-products",
            "runOn": "server"
        }
    },
    "config": {
        "imageAlignment": {
            "friendlyName": "Image Alignment",
            "description": "Sets the desired alignment of the image, either left or right on the text.",
            "type": "string",
            "enum": {
                "left": "Left",
                "right": "Right"
            },
            "default": "left",
            "scope": "module",
            "group": "Layout Properties"
        },
        "productTitle": {
            "type": "string",
            "friendlyName": "Product Title",
            "description": "Product placement title",
            "required" : true
        },
        "productDetails": {
            "type": "richText",
            "friendlyName": "Product Details",
            "description": "Rich text representing the featured product details"
        },
        "productImage": {
            "type": "image",
            "friendlyName": "Product Image",
            "description": "Image representing the featured product"
        },
    },
    "resources": {
        "buyNowButtonText": {
            "value": "Buy Now!",
            "comment": "Text for the buy now button"
        }
    }
}

モジュール定義ファイルでは構成フィールドも公開され、ページ作成者はモジュール設定とリソース定義を構成できます。前の例では、画像の配置設定の構成フィールドがあります (使用可能な値は左と右です)。他の例としては、モジュールのタイトルやヘッダー、リッチテキストの説明、「アクションの呼び出し」リンク、画像 URL、または Commerce 製品データなどがあります。

ページの作成者は、他のページのモジュールの設定に影響を与えることなく、特定のページのモジュールの設定を構成できます。モジュール構成は、モジュールインスタンスごとに実装するか、モジュールのすべてのインスタンスでグローバルに実装できます。

モジュール定義スキーマ

"$type" – モジュールのタイプモジュールは、コンテンツモジュール (contentModule)、コンテナーモジュール (containerModule)、ページモジュール (PageModule)、スクリプト挿入モジュール (scriptModule)、またはテーマモジュール (themeModule) のいずれかです。コンテナーモジュールとページモジュールには、レイアウト地域に使用される "スロット" も定義されます。スクリプト挿入モジュールは、スクリプトを挿入できる場所を指定するために使用される「属性」セクションも定義します。
"friendlyName" – モジュール.のフレンドリ名。この名前はページ作成者に表示されます。最小の長さは 3 文字です。
"名前" – モジュールの名前。この名前は、アプリケーション間で一意でなければなりません。モジュールの ID として使用され、サイトビルダーツールによって参照されます。変更しないでください。
"説明" – モジュールの説明。説明は、モジュールがページに追加されたときにサイトビルダーツールに表示されるわかりやすい文字列を提供します。
"カテゴリ" – モジュールがサブスクライブできるカテゴリ。コンテナーモジュールは、ここで指定された値を使用して、特定のスロットで一部のモジュールを許可または禁止します。
"タグ" – モジュールの検索に使用されるタグ。すべてのカテゴリがタグとして自動的に追加されます。
"dataActions" – dataActions ノードは、モジュールに対して実行するデータアクションを登録するために使用されます。既定では、データアクションはサーバー側で実行されます。ただし、クライアント側で実行するように構成することもできます。
"スロット" – スロットはコンテナーモジュールでのみ定義されます。これらは、サイトビルダツールで公開されます。スロットの許可リストと拒否リストを定義して、特定のモジュールがそのスロットで受け入れられるのを許可または禁止することができます。
"属性" – 属性は、スクリプトの挿入プロパティを制御するために使用されます。詳細については、スクリプトの挿入を参照してください。
"config" – 構成セクションはモジュールの構成プロパティを追加するために使用します。詳細については、モジュール構成フィールドの追加を参照してください。
"リソース" – このプロパティは、モジュールで使用されるリソースをローカライズするために使用されます。詳細については、この記事の後半にあるモジュールリソーススキーマセクションを参照してください。
"dependentSemaas" – dependentSchema セクションは、他の構成プロパティのコンテキスト値に基づいて、構成プロパティを表示または非表示にするために使用されます。詳細については、コンテキストに基づいて表示されるモジュールプロパティのコンフィギュレーションを参照してください。

モジュールへのデータアクションの登録

モジュールがデータアクションからのデータに依存する場合、データアクションはモジュール定義ファイルの dataActions セクションに登録する必要があります。

次の例では、データアクション登録を含むモジュール定義ファイルを示します。

// test-module.definition.json
{
    "$type": "contentModule",
    "friendlyName": "test-module",
    "name": "test-module",
    "description": "Module for testing observable data actions",
    "categories": ["test-module"],
    "tags": ["samples"],
    "dataActions": {
        "products":{
            "path": "@msdyn365-commerce-modules/retail-actions/dist/lib/get-simple-products",
            "runOn": "server"
        },
        "productWarranty":{
            "path": "../../actions/getProductWarrantyInfo",
            "runOn": "server"
        }
    }
    ...
}

各データアクションは、その名前および次のプロパティで宣言されます。

"パス" – データアクションのパス。パスは、ローカルパスまたは SDK に含まれるコアアクションのパスにすることができます (例: "@msdyn365-commerce-modules/retail-actions/dist/lib/get-selected-variant")。
"runOn" – データアクションの実行場所を制御する設定。有効な値は、サーバーまたはクライアントです。値が指定されていない場合、既定値はサーバーです。

前の例では、データアクションが登録された後、モジュールはそれをサーバー上で自動的に実行します。次に、モジュールは結果を testResult プロパティにバインドします。このプロパティは、モジュールの data.ts ファイルで定義する必要があります。

// test-module.data.ts
import { AsyncResult , SimpleProduct } from '@msdyn365-commerce/retail-proxy';
import { IGetProductWarrantyInfoData } from '../../actions/getProductWarrantyInfo';

export interface IAsyncTestModuleData {
    products: AsyncResult<SimpleProduct>[];
    productWarrantyInfo: AsyncResult<IGetProductWarrantyInfoData>;
}

その後、モジュール内のデータアクションの結果にアクセスできます。

モジュールリソーススキーマ

"リソース" – このプロパティは、リソースをローカライズするために使用されます。リソース文字列が定義されると、対応する JavaScript Object Notation (JSON) ファイルからローカライズされた文字列が取得されます。これらのファイルは、/src/resources/modules/ ディレクトリに格納されます。 global.json ファイルと、fr-fr.json などの、必要なローカライズされた JSON ファイルが含まれています。
"resourcekey" – リソースの名前。 this.props.resources.resourceKey プロパティを介してコードでリソースキーにアクセスできます。
"コメント" – ローカライズを支援するために、文字列の目的を識別する文字列。
"値" – モジュールで使用されるリソース文字列データ。