Clientside Validation
データ属性とjQuery Validation Pluginを使用して、Drupalフォームにクライアントサイドのフォームバリデーションを追加します。
clientside_validation
インストール
composer require 'drupal/clientside_validation:^4.1'
概要
Clientside Validationは、サーバー送信前にDrupalフォームの即時クライアントサイドバリデーションを提供するモジュールです。このモジュールはフォーム要素にHTML5データ属性を追加し、JavaScriptバリデーションライブラリによって処理されます。
モジュールはコアベースモジュールとjQueryサブモジュールで構成されています。コアモジュールはバリデーション要件に基づいてフォーム要素にdata-rule-*およびdata-msg-*属性を追加するPHP側を処理します。clientside_validation_jqueryサブモジュールは、実際のクライアントサイドバリデーションを実行するためにjQuery Validation Pluginを統合します。
モジュールは必須フィールド、メールバリデーション、URLバリデーション、数値範囲バリデーション(min、max、step)、パターンマッチング、フィールド一致チェックなど、様々なバリデーションタイプをサポートしています。また、条件付きバリデーションのためのDrupalのStates API、WYSIWYGフィールドのためのCKEditor、一貫したエラー表示のためのInline Form Errorsモジュールともシームレスに統合されます。
Features
- 追加設定なしですべてのDrupalフォームに自動クライアントサイドバリデーションを適用
- CvValidatorプラグインシステムによるカスタムバリデーターを可能にするプラグインベースのアーキテクチャ
- required、email、URL、min、max、step、maxlength、patternバリデーション用の組み込みバリデーター
- DrupalのStates API(#states)を使用した条件付き必須フィールドのサポート
- #required_error、#email_error、#url_error、#min_error、#max_error、#step_error、#maxlength_error、#pattern_errorフォーム要素プロパティによるカスタムエラーメッセージ
- パスワード確認や類似のフィールドマッチングシナリオのためのequal-toバリデーション
- 設定可能な動作によるAJAXフォームバリデーションサポート
- WYSIWYGエディタコンテンツのバリデーションのためのCKEditor統合
- 一貫したエラースタイリングのためのInline Form Errorsモジュール統合
- CDNまたはローカルインストールによる柔軟なライブラリ読み込み
- jQuery Validationライブラリ管理のためのDrushコマンド
- バリデーション動作の制御と機能拡張のためのHookシステム
Use Cases
基本的な必須フィールドバリデーション
任意のフォーム要素に#requiredプロパティを追加すると、自動的にクライアントサイドの必須バリデーションが適用されます。ユーザーがフィールドを入力せずに送信しようとすると、「Field name field is required.」のようなエラーメッセージが表示されます。#required_errorプロパティを使用してメッセージをカスタマイズできます。
パスワード確認バリデーション
#equal_toプロパティを使用して、確認フィールドが別のフィールドと一致することをバリデーションします。例えば、パスワード確認フィールドに'#equal_to' => 'pass1'を追加すると、「pass1」という名前の元のパスワードフィールドと一致することを確認します。#equal_to_errorでエラーメッセージをカスタマイズできます。
パターンベースのバリデーション
#patternプロパティと正規表現を使用して、電話番号、郵便番号、カスタム識別子などのフィールド形式をバリデーションします。例:インドの電話番号には'#pattern' => '[789][0-9]{9}'。#pattern_errorでエラーメッセージをカスタマイズできます。
数値範囲バリデーション
数値フィールドで#min、#max、#stepプロパティを使用して数値制約をバリデーションします。例えば、年齢フィールドには'#min' => 18、'#max' => 120を使用でき、数量フィールドには'#step' => 5を使用して5の倍数のみを許可できます。
AJAXフォームバリデーション
設定で「AJAX送信前にすべてのフォームをバリデート」を有効にするか、特定のフォームにCSSクラス「cv-validate-before-ajax」を追加して、AJAXフォーム送信前にフィールドをバリデーションし、不要なサーバーリクエストを防ぎます。
States APIによる条件付き必須フィールド
Drupalの#states APIとクライアントサイドバリデーションを組み合わせて条件付き必須フィールドを実現します。例:'#states' => ['required' => [':input[name="option"]' => ['value' => 'other']]]は、別のフィールドが特定の値を持つ場合のみフィールドを必須にします。
カスタムバリデーターの作成
カスタムモジュールにCvValidatorプラグインを作成してモジュールを拡張します。サポートされるタイプ/属性を指定する@CvValidatorアノテーションを持つプラグインクラスをsrc/Plugin/CvValidator/に配置します。getRules()を実装してバリデーションルールとメッセージを返します。
Tips
- デモモジュール(clientside_validation_demo)を使用して、すべてのバリデーション機能をテストし、フォーム要素設定の動作例を確認してください。
- より良いユーザー体験のために、設定で「Blur/focusoutでバリデート」を有効にして、ユーザーがフォームフィールドをタブ移動する際に即座にフィードバックを提供してください。
- カスタムバリデーターを作成する際は、hook_clientside_validation_validator_info_alter()を実装して、バリデーターが必要とする追加のJavaScriptライブラリをアタッチしてください。
- モジュールはURLバリデーションでDrupalのストリームラッパー(public://、private://)を自動的にサポートし、有効なファイル参照を許可します。
- hook_clientside_validation_should_validate()を使用して、特別な処理が必要な特定のフォームや要素のバリデーションを選択的に無効にしてください。
- カスタムJavaScriptはdocumentの'cv-jquery-validate-options-update'イベントをリッスンして、jQuery Validationオプションをグローバルに変更できます。
- 送信ボタンにformnovalidate属性があるフォームの場合、クライアントサイドバリデーションはスキップされます。「キャンセル」や「下書き保存」ボタンに便利です。
Technical Details
Admin Pages 2
/admin/config/user-interface/clientside-validation-jquery-settings
jQuery Validation Pluginの読み込み方法とフォームでのバリデーション動作を設定します。このページでは、管理者がCDNとローカルライブラリの読み込みの選択、AJAXフォームバリデーション動作の設定、追加バリデーション機能の有効化を行うことができます。
/admin/config/user-interface/clientside-validation-demo
Clientside Validationモジュールのすべてのバリデーション機能を紹介するデモフォームです。このフォームには、必須フィールド、カスタムエラーメッセージ、条件付き必須フィールド、メールバリデーション、URLバリデーション、min/max/step付き数値バリデーション、パターンマッチング、フィールド一致バリデーションの例が含まれています。
Hooks 2
hook_clientside_validation_validator_info_alter
モジュールがCvValidatorプラグイン定義を変更できるようにします。カスタムJavaScriptライブラリの追加、サポートされる要素タイプの変更、プラグイン動作の変更に使用できます。
hook_clientside_validation_should_validate
モジュールが特定のフォーム要素がクライアントサイドバリデーションを受けるべきかどうかを制御できるようにします。要素のバリデーションをスキップするにはFALSEを返します。
Drush Commands 3
drush clientside_validation_jquery:library-status
jQuery Validationライブラリが/librariesディレクトリにローカルインストールされているかどうかを表示します。
drush clientside_validation_jquery:library-download
jQuery Validationライブラリを/libraries/jquery-validationにダウンロードしてインストールします。ダウンロードしたアーカイブを自動的に展開してリネームします。
drush clientside_validation_jquery:library-remove
/libraries/jquery-validationからローカルインストールされたjQuery Validationライブラリを削除します。
Troubleshooting 6
ページソースでjquery.validate.min.jsを検査してライブラリが読み込まれているか確認してください。ローカルライブラリを使用している場合は、'drush cvjls'を実行してインストール状態を確認してください。インストールされていない場合は、設定でCDNを有効にするか、'drush cvjld'を実行してダウンロードしてください。
CDN URLがサーバーからアクセス可能であることを確認してください。モジュールは指定されたパスでjquery.validate.min.jsがアクセス可能かどうかを確認してURLをバリデーションします。形式を使用してください:https://cdn.jsdelivr.net/npm/jquery-validation@1.21.0/dist/
設定で「AJAX送信前にすべてのフォームをバリデート」を「はい」に設定するか、AJAX送信前にバリデーションすべきフォームにCSSクラス「cv-validate-before-ajax」を追加してください。
ckeditorモジュールが有効になっていることを確認してください。統合ライブラリはCKEditorが存在する場合に自動的に読み込まれます。それでも動作しない場合は、ブラウザコンソールでJavaScriptエラーを確認してください。
クライアントサイドとサーバーサイドのバリデーションエラーメッセージの間で一貫したスタイリングを得るために、Inline Form Errorsモジュールを有効にしてください。
カスタムエラー用の正しいプロパティ名を使用していることを確認してください。各バリデーターには独自のエラープロパティがあります:#required_error、#email_error、#url_error、#min_error、#max_error、#step_error、#maxlength_error、#pattern_error、#equal_to_error、#url_internal_external_error。