Commerce Webform Order
Drupal WebformとDrupal Commerceを統合し、専用のWebformハンドラーを通じてWebform送信からCommerceの注文を作成できるようにします。
commerce_webform_order
インストール
composer require 'drupal/commerce_webform_order:^3.0'
概要
Commerce Webform Orderは、DrupalのWebformモジュールとCommerceモジュールの間に強力な統合レイヤーを提供します。サイトビルダーは、Webformを通じて顧客データを収集し、送信データから自動的にCommerce注文を生成することで、複雑な注文ワークフローを作成できます。
このモジュールは、寄付フォーム、会員申請、サービス予約、およびDrupal Commerceの堅牢なEコマースシステムを通じて支払いを処理しながらユーザーから詳細な情報を収集する必要があるあらゆるシナリオに特に有用です。
Webform送信を直接販売する類似モジュールとは異なり、Commerce Webform OrderはCommerceの上位レイヤーとして機能し、PurchasableEntityInterfaceを実装する任意のEntityを販売できます。これにより、複雑なEコマースシナリオに対してより高い柔軟性を提供します。
Features
- Webform送信からCommerce注文を作成するWebformハンドラー（豊富な設定オプション付き）
- Payment Gatewayの選択フォームをWebformに直接埋め込むPayment Method Webformエレメント
- Webform送信内で現在の注文状態を同期・表示するOrder State Webformエレメント
- 支払いステータス情報を追跡・表示するPayment Status Webformエレメント
- Webformから開始された支払いを処理するためのカスタムCheckoutペイン（Payment Process）
- 注文状態/支払いステータスとWebform送信データの自動同期
- 動的な注文作成のためのハンドラー設定でのToken値のサポート
- カートを空にする、新しいカート、カートを結合するオプションを含むカート動作制御
- Webform送信後にユーザーをCheckoutにリダイレクトするオプション
- 注文の所有者、請求先プロファイル、Payment Gateway、支払い方法の設定サポート
- Webformデータからカスタム注文アイテムフィールドを入力するための注文アイテムフィールドマッピング
- 関連する注文がドラフト状態でなくなった場合のWebform送信更新の防止
- 開発およびトラブルシューティング用のデバッグモード
- 保存前に注文、注文アイテム、Webform送信をカスタマイズするためのAlter hook
Use Cases
カスタム金額の寄付フォーム
ユーザーがカスタムの寄付金額を入力できる寄付Webformを作成します。数値フィールドを注文アイテムの金額にマッピングし、寄付者が貢献額を指定できるようにします。ハンドラーはカスタム価格で注文を作成し、ユーザーは支払い処理のためにCheckoutにリダイレクトされます。
支払い付きイベント登録
参加者情報を収集し、登録料のCommerce注文を作成するイベント登録フォームを構築します。Order Stateエレメントを使用して確認ページに支払いステータスを表示し、注文完了に基づいてメール通知をトリガーします。
会員申請
会員詳細を収集し、会費を処理する会員申請フォームを作成します。請求先プロファイル設定を使用して、フォームで収集した情報でCheckoutを事前入力し、支払いプロセスを効率化します。
商品カスタマイズフォーム
顧客がWebformを通じて商品をカスタマイズ（例：刻印テキスト、色の選択）し、これらの値を注文アイテムのカスタムフィールドにマッピングできるようにします。注文アイテムは標準のCommerceデータと共にカスタマイズの詳細を保存します。
マルチステップCheckoutの置き換え
Commerceの標準Checkoutフローをwebformベースのcheckoutに置き換えます。Payment Methodエレメントを埋め込んでフォーム内で直接支払い情報を収集し、カスタムのPayment Process Checkoutペインを使用してトランザクションを処理します。
継続寄付の設定
継続寄付用の支払い方法情報を収集する寄付フォームを作成します。Payment Methodエレメントは保存済み支払い方法をサポートしており、Commerce継続支払いモジュールと統合することで将来の自動課金を可能にします。
Tips
- 送信データに基づいた動的な注文作成のために、ハンドラー設定でToken値（例：[webform_submission:values:amount]）を使用します。
- 置換値がないTokenを削除するために、Tokenに:clearサフィックス（例：[current-user:name:clear]）を追加します。
- Payment Methodエレメントを使用する場合、標準の「Payment process」Checkoutペインを「Payment process (Commerce Webform Order)」に置き換え、「Payment information」ペインを無効にします。
- 詳細な注文作成情報を確認するために開発中はデバッグを有効にしますが、本番環境では必ず無効にしてください。
- Order StateおよびPayment Statusエレメントを使用して、Commerceイベントに基づいて他のWebformハンドラーで条件付きアクションをトリガーします。
- 匿名の寄付の場合、権限の問題を回避するためにStoreアクセスの「アクセスチェックをバイパス」を有効にすることを検討してください。
- ハンドラーは無制限のカーディナリティをサポートします。複数のハンドラーを追加して、1つの送信から複数の注文アイテムを作成できます。
- 他のモジュールやカスタムコードで使用できる任意のデータを注文に追加するために、「カスタム注文データ」フィールドでYAML形式を使用します。
Technical Details
Admin Pages 1
/admin/structure/webform/manage/{webform}/handlers/add/commerce_webform_order
WebformにCommerce Webform Order Handlerを追加するための設定フォーム。注文作成ルールと動作を設定できます。
Hooks 1
hook_commerce_webform_order_handler_postsave_alter
Webformハンドラーで保存前に注文、注文アイテム、Webform送信を変更します。Webform送信から作成されたCommerceエンティティへのカスタム変更を可能にします。
Security Notes 4
- 「アクセスチェックをバイパス」オプションは通常のDrupalアクセス制御を上書きするため、慎重に使用してください。
- デバッグモードはすべてのユーザーに注文情報を表示します。開発環境でのみ使用してください。
- 支払い方法情報はCommerce PaymentのセキュアなAPIを通じて処理されます。機密データはWebform送信に保存されません。
- prevent_update機能は、完了した注文にリンクされた送信への変更をブロックすることでデータの整合性を維持するのに役立ちます。