Clientside Validation

データ属性とjQuery Validation Pluginを使用して、Drupalフォームにクライアントサイドのフォームバリデーションを追加します。

clientside_validation
22,488 sites
88
drupal.org

インストール

Drupal 11, 10, 9 v4.1.2
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
Clientside Validation jQuery設定 /admin/config/user-interface/clientside-validation-jquery-settings

jQuery Validation Pluginの読み込み方法とフォームでのバリデーション動作を設定します。このページでは、管理者がCDNとローカルライブラリの読み込みの選択、AJAXフォームバリデーション動作の設定、追加バリデーション機能の有効化を行うことができます。

Clientside Validationデモ /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 Validationライブラリが読み込まれていない

ページソースでjquery.validate.min.jsを検査してライブラリが読み込まれているか確認してください。ローカルライブラリを使用している場合は、'drush cvjls'を実行してインストール状態を確認してください。インストールされていない場合は、設定でCDNを有効にするか、'drush cvjld'を実行してダウンロードしてください。

設定保存時にCDN URLバリデーションエラー

CDN URLがサーバーからアクセス可能であることを確認してください。モジュールは指定されたパスでjquery.validate.min.jsがアクセス可能かどうかを確認してURLをバリデーションします。形式を使用してください:https://cdn.jsdelivr.net/npm/jquery-validation@1.21.0/dist/

AJAXフォームがバリデーションなしで送信される

設定で「AJAX送信前にすべてのフォームをバリデート」を「はい」に設定するか、AJAX送信前にバリデーションすべきフォームにCSSクラス「cv-validate-before-ajax」を追加してください。

CKEditorフィールドがバリデーションされない

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。