モジュール構成フィールドの追加

[アーティクル]
03/08/2023

この記事では、Microsoft Dynamics 365 Commerce でモジュール構成フィールドを追加する方法について説明します。

構成フィールドは、モジュールに追加してページ作成者に公開し、さまざまなモジュール機能を制御することができます。これらの機能の例には、さまざまなビュー、配置プロパティ、機能をオンまたはオフにするブール値の切り替え、モジュールのタイトルまたはヘッダー、リッチテキストの説明、コールからアクションへのリンク、画像 URL、そしてコマース製品データがあります。

次の図は、選択したモジュールの構成フィールドが Commerce サイトビルダーにどのように表示されるかを示しています。

作成ツールのモジュール構成フィールド。

新しいモジュール構成フィールドの追加

構成フィールドを追加するには、モジュール定義ファイル MODULE_NAME.definition.json の config セクションにエントリを追加します。

例

次のモジュール定義ファイルの例では、imageAlignment 構成フィールドが追加され、ページの作成者がモジュール内の画像の配置を構成できるようになりました。 2 つの列挙型 (列挙) オプションがあります: 「左」 (既定のオプション) および「右」。

{
    "$type": "contentModule",
    "friendlyName": "Product Feature",
    "name": "product-feature",
    "description": "Feature module used to highlight a product.",
    "categories": [
        "storytelling"
    ],
    "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"
        }
    }
}

モジュール構成スキーマ

モジュール定義ファイルの config セクションには、作成ツールで使用されるすべてのモジュールの公開構成フィールドの一覧が含まれています。

コンフィギュレーション名 – React ソースコードからコンフィギュレーション値にアクセスするために使用されるローカル名。この名前は、大文字と小文字が区別されません。
"friendlyName" – 作成ツールでコンフィギュレーション名として表示されるフレンドリ名。
"description" – 作成ツールでコンフィギュレーションの説明として表示される説明。
"type" – コンフィギュレーションのタイプ。使用可能な値は、"string"、"bool"、"number"、"integer"、"richText"、"image"、"imageSettings"、"css"、"video"、および "array" です。
"enum" – 列挙型の場合、値を "string" にする必要があります。
"default" – 作成ツールで値が設定されていない場合の既定値。
"scope" – このモジュールは、構成を特定のモジュールインスタンスまたはサイト上のすべてのモジュールのいずれかに適用するために使用されます。有効値は、"module" および "siteOnly" です。値が "siteOnly" に設定されている場合、モジュールコンフィギュレーションはページに表示されず、そこで構成することはできません。これは、サイトビルダーのサイトレベルでのみ、サイト設定 > 拡張機能で表示および構成できます。このようにして、値はサイト全体に対して一度に設定できます。このフィールドを設定しない場合、既定値は "module" になります。
"group" – グループは、作成ツールで構成を組織化されたグループに編成するために使用されます。
"required" – モジュールにプロパティを設定する必要があるかどうかを指定するブール値フラグ。値が true に設定されている場合、作成ツールは必要なプロパティが設定されていない時、またはモジュールがレンダリングされる時にエラーを表示します。
"resources" – このフィールドは、ローカライズリソースに使用されます。
"definitions" - このフィールドには、構成セクションで拡張タイプとして参照できる複雑な構成タイプの定義を含めることができます。

次の例は、サポートされるさまざまなデータ型の使用方法を示しています。

{
    "$type": "contentModule",
    "friendlyName": "Sample Configurations",
    "name": "sample-config",
    "description": "Provides various configuration property samples",
    "categories": [""],
    "tags": [""],
    "dataActions": {},
    "config": {
        "title": {
            "type": "string",
            "friendlyName": "Title",
            "description": "Example config value",
            "default": "",
            "scope": "module"
        },
        "subTitle": {
            "type": "richText",
            "friendlyName": "SubTitle",
            "description": "Sub title rich text field"
        },
        "bgImage": {
            "type": "image",
            "friendlyName": "Background image",
            "description": "Background image"
        },
        "images": {
            "type": "array",
            "friendlyName": "Images",
            "description": "Image array",
            "items": {
                "type": "image"
            }
        },
        "backgroundImageSettings": {
            "type": "imageSettings",
            "friendlyName": "Background image settings",
            "description": "Image settings for background image settings"
        },
        "ambientVideo": {
            "type": "video",
            "friendlyName": "Ambient video",
            "description": "Ambient video",
        },
        "headingArray":{
            "type": "array",
            "friendlyName": "Headings",
            "description": "Heading array",
            "items": {
                "$ref": "#/definitions/heading"
            }
        },
        "heading":{
            "$ref": "#/definitions/heading"
        },
        "heading2":{
            "type": "object",
            "friendlyName": "Heading2",
            "description": "Heading2 property with its own enum",
            "properties": {
                "style": {
                    "type": "string",
                    "enum": {
                        "bold": "Bold",
                        "underline": "Underline",
                        "italics": "Italics",
                        "strong": "Strong",
                        "emphasized": "Emphasized",
                        "none": "None"
                    },
                    "friendlyName": "Style",
                    "description": "Heading style"
                }
            }
        },
        "textPlacement":{
            "friendlyName": "Text placement",
                "description": "Placement of the text",
            "type": "object",
            "enum":{
                "left": "Left",
            "right": "Right",
            "center": "Center"
            },
            "default": "left"
        }
    },
    "definitions": {
        "heading": {
            "type": "object",
            "friendlyName": "Heading",
            "description": "Heading property",
            "properties": {
                "text": {
                    "type": "string",
                    "friendlyName": "Text",
                    "description": "Heading Text"
                },
                "style": {
                    "type": "string",
                    "enum": {
                        "bold": "Bold",
                        "underline": "Underline",
                        "none": "None"
                    },
                    "friendlyName": "Style",
                    "description": "Heading style"
                },
                "showImage":{
                    "type":"boolean",
                    "friendlyName": "Show image?",
                    "description": "Should Show Image"
                },
                "bgImage": {
                    "type": "image",
                    "friendlyName": "Background image",
                    "description": "Background image"
                },
                "imageArray":{
                    "type": "array",
                    "friendlyName": "Images",
                    "description": "Image Array",
                    "items": {
                        "type": "image"
                    }
                }
            }
        }
    }
}

css コンフィギュレーションのタイプ

モジュール構成プロパティのコンフィギュレーションタイプは、"type": "css" として宣言することもできます。 css タイプとして宣言されたモジュール構成プロパティは、モジュールに適用できるクラスの文字列列挙のセットを指定する必要があります。特定のモジュール構成プロパティに対して選択できる列挙オプションは 1 つのみです。列挙オプションが選択されると、選択されたクラスが、this.props.config.className プロパティを介して propertyName__propertyValue の形式でモジュールに渡されるクラスのリストに追加されます。 css コンフィギュレーションタイプは、this.props.config.className プロパティにマージされているため、this.props.config プロパティから直接アクセスできないことに注意してください。

className プロパティ

すべてのコンテンツモジュールには、className という名前の構成フィールドが組み込まれています。この構成フィールドには、this.props.config.className プロパティを介してモジュールのビュー内でアクセスできます。この構成フィールドは、サイト作成ツールに表示されます。したがって、ページ作成者は、モジュールルートクラスに追加する必要がある空白で区切られたカスケードスタイルシート (CSS) クラス名の文字列を追加できます。

cssClassName property

__cssClassName__ は、モジュール定義ファイル内で宣言される別の特別なプロパティです。モジュールの作成者には、モジュールに常に適用される、カスタム不可、編集不可、読み取り専用の className プロパティを指定する方法が提供されます。したがって、その編集可能なプロパティを false に設定し、既定値を指定する必要があります。

次の例では、モジュール作成者がこのフィールドに既定値ヒーローを与えています。したがって、このモジュールのすべてのインスタンスは、常に　this.props.config.className プロパティの一部としてヒーロー クラスを持ちます。

...
    "__cssClassName__": {
        "default": "hero",
        "editable": false,
        "friendlyName": "Readonly CSS Class Name(s)",
        "description": "Provides a way to set constant, unchangeable default css class(es) to apply to your module.",
        "type": "string"
    },
...

ローカルテスト用の構成フィールドで、モックデータを使用する

次の例は、mocks/MODULE_NAME.json ファイルの新しい構成フィールドにモック値を設定する方法を示しています。モックデータは、ローカルの開発環境でモジュールを表示する場合に便利です。

{
    "id": "R1Module1",
    "config": {
        "imageAlignment": "left",
        "productTitle": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses",
        "productDetails": "High-quality and pioneered with the perfect blend of timeless classic and modern technology with hint of old school glamor.",
        "productImage": {
            "src": "https://bit.ly/33cMGxr",
            "altText": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses"
        },
        "buttonText": "Buy Now",
        "productIds": "68719498121"
    },
    "data": {
        "actionResponse": {
            "text": "Sample Action Response"
        }
    },
    "typeName": "product-feature"
}

モジュール React コンポーネントの構成フィールドへのアクセス

React コンポーネントの構成フィールドにアクセスするには、props.config アプリケーションプログラミングインターフェイス (API) を使用します。

次の例では、適切な HTML を表示するためにモジュールビューファイルに送信される構成値を持つ props プロパティを作成します。

import * as React from 'react';

import { IProductFeatureData } from './product-feature.data';
import { imageAlignment, IProductFeatureProps } from './product-feature.props.autogenerated';

export interface IProductFeatureViewProps extends IProductFeatureProps<IProductFeatureData> {
    productName: string;
    productInfo: string;
    productImageUrl: string;
    productPrice: string;
    buttonInfo: string;
    alignment: imageAlignment;
}

/**
 *
 * ProductFeature component
 * @extends {React.PureComponent<IProductFeatureProps<IProductFeatureData>>}
 */
class ProductFeature extends React.PureComponent<IProductFeatureProps<IProductFeatureData>> {
    public render(): JSX.Element | null {
        const { config } = this.props;

        // set default product info values
        const ProductName = config.productTitle ? config.productTitle : 'No product name defined';
        const ProductInfo = config.productDetails ? config.productDetails.toString() : 'No product details defined';
        const ProductImageUrl = config.productImage ? config.productImage.src : '';
        const ButtonInfo = config.buttonText ? config.buttonText : 'No button text defined';
        const ProductPrice = '129';

        const ProductFeatureViewProps = {
            ...this.props,
            productName: ProductName,
            productInfo: ProductInfo,
            productImageUrl: ProductImageUrl,
            productPrice: ProductPrice,
            buttonInfo: ButtonInfo,
            alignment: config.imageAlignment
        };

        return this.props.renderView(ProductFeatureViewProps);
    }
}

export default ProductFeature;

次の例では、前述の React コンポーネントから渡されたコンフィギュレーション値を使用して HTML レイアウトを処理する、対応するモジュールビューファイルを示します。

import * as React from 'react';
import { IProductFeatureViewProps } from './product-feature';
import { imageAlignment } from './product-feature.props.autogenerated';

const _renderImage=(productImageUrl: string, productName: string): JSX.Element => {
    return <img src={productImageUrl} alt={productName} className='img-fluid p-3' />;
};

const _renderInfo=(productName: string, productInfo: string, productPrice: string, buttonInfo: string): JSX.Element => {
    return (
        <div className='container'>
            <h2>{productName}</h2>
            <p>{productInfo}</p>
            <p>{productPrice}</p>
            <button type='button' className='btn btn-primary'>{buttonInfo}</button>
        </div>
    );
};

export default (props: IProductFeatureViewProps) => {
    const { productName, productInfo, productImageUrl, productPrice, buttonInfo, alignment } = props;

    let left;
    let right;

    if (alignment === imageAlignment.left) {
        left = _renderImage(productImageUrl, productName);
        right = _renderInfo(productName, productInfo, productPrice, buttonInfo);
    } else {
        right = _renderImage(productImageUrl, productName);
        left = _renderInfo(productName, productInfo, productPrice, buttonInfo);
    }

    return (
        <div className='row align-items-center'>
            <div className='col-sm-6'>
                {left}
            </div>
            <div className='col-sm-6'>
                {right}
            </div>
        </div>
    );
};