JavaScriptで書かれたフォームバリデーションライブラリParsley.jsの使い方を解説します。JacaScriptがわからなくてもHTMLの記述だけで利用できますし、JavaScriptの達人ならばさらに高度な使い方ができるとても使い勝手の良いライブラリです。
Parsley.jsのインストール
ダウンロード
公式サイトのダウンロードページからソースをダウンロードすることができます。CDNも使えますね。
Node.jsを導入済みならば npm
でインストールする方法もあります。
npm install parsleyjs
HTMLへの読み込み
HTMLでParsley.jsを読み込みます。
- Parsley.jsはjQueryに依存しているので、まずjQueryを読み込みます。
- 次に
dist
ディレクトリ下にあるParsley.jsの本体parsley.min.js
を読み込みます。 dist/i18n
下にある日本語化ファイルja.js
を読み込みます。src
ディレクトリ下にあるCSSファイルparsley.css
を読み込みます。
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://parsleyjs.org/dist/parsley.min.js"></script>
<script src="https://parsleyjs.org/dist/i18n/ja.js"></script>
<link rel="stylesheet" href="https://parsleyjs.org/src/parsley.css" />
- 上記のファイルのパスはCDNでインストールした場合です。他の方法でインストールした場合はパス名を読み替えてください。
- 自分で検証メッセージのスタイルをカスタマイズする場合は、
parsley.css
の読み込みは不要になります。が、手っ取り早く利用するためにとりあえず読み込んでおきましょう。(まぁ後でカスタマイズしたくなるよね)
フォームへの適用
任意のフォームでParsley.jsを利用するためのおまじないです。2つの方法があります。
1つめは、HTMLで記述する方法です。<form>
タグに data-parsley-validate
属性を追加します。
<form data-parsley-validate>
...
</form>
2つめは、JavaScriptで記述する方法です。<form>
タグに id
を付けてjQueryのセレクタで指定します。
<form id="私のフォーム">
...
</form>
<script>
$('#私のフォーム').parsley();
</script>
JavaScriptでは、複数のフォームをまとめて記述することもできます。フォームをたくさん使う場合はこちらが便利ですね。
<script>
$('#私のフォーム1, #私のフォーム2, #私のフォーム3', ...).parsley(
...設定...
);
</script>
Parsley.jsの使い方
今すぐ使ってみる
せっかくインストールが完了したので、面倒な説明は後回しにして動作させてみましょう。
下記のデモは、各入力項目に required
属性を指定したものです。「名前」の入力欄には minlength="3"
も追加しました。適当に文字を入力して[送信]ボタンを押してみてください。こんな感じでバリデーションが働きます。
組込バリデータ
では、ひとつひとつのバリデータの説明をしていきます。
基本的なHTMLの属性を指定するもの(例えば require
)とParsley.js独自の属性(例えば data-parsley-required
)を指定するものがあります。両方使えるものはどっちを使ってもOKです。
名前 | 属性名 | 説明 |
---|---|---|
必須項目 | required data-parsley-required data-parsley-required="true" data-parsley-required="false" | 値が入力または選択されていることを検証します。空白の値は無効です。data-parsley-required="false" は入力が必須ではないという意味なので、何も指定しないのと同じです。何のためにあるんでしょうね。 |
メールアドレス | type="email" data-parsley-type="email" | 値が有効なメールアドレスであることを検証します。 |
数値 | data-parsley-type="number" | 値が有効な数値であることを検証します。小数もOK。 |
整数 | type="number" data-parsley-type="integer" | 値が有効な整数であることを検証します。ただし、type="number" で step が小数の場合は小数もOK。 |
数字 | data-parsley-type="digits" | 値が数字のみであることを検証します。 |
英数字 | data-parsley-type="alphanum" | 値が英数字のみであることを検証します。 |
URL | type="url" data-parsley-type="url" | 値が有効なURLであることを検証します。 |
最小の長さ | minlength="6" data-parsley-minlength="6" | 文字列の長さが指定された値以上であることを検証します。 |
最大の長さ | maxlength="10" data-parsley-maxlength="10" | 文字列の長さが指定された値以下であることを検証します。 |
文字列の長さ | data-parsley-length="[6, 10]" | 文字列の長さが指定された値の範囲内であることを検証します。 |
最小値 | min="6" data-parsley-min="6" | 数値または日付が指定された値以上であることを検証します。 |
最大値 | max="10" data-parsley-max="10" | 数値または日付が指定された値以下であることを検証します。 |
数値の範囲 | type="range" data-parsley-range="[6, 10]" | 数値または日付が指定された値の範囲内であることを検証します。 |
パターン | pattern="\d+" data-parsley-pattern="\d+" | 値が正規表現にマッチすることを検証します。 |
チェックの最小値 | data-parsley-mincheck="3" | チェックボックスの選択数が指定された値以上であることを検証します。 |
チェックの最大値 | data-parsley-maxcheck="3" | チェックボックスの選択数が指定された値以下であることを検証します。 |
チェック数の範囲 | data-parsley-check="[1, 3]" | チェックボックスの選択数が指定された値の範囲内であることを検証します。 |
〇〇に等しい | data-parsley-equalto="#xxx" | 値が別のフィールドの値と同じであることを検証します。 |
例えば、テキストフィールドの入力を必須にして、文字数は3〜12文字に制限する場合は、次のように記述します。
<input type="text" name="名前" required data-parsley-length="[3, 12]">
カスタムバリデータ
Parsley.jsでは独自のバリデータを作って利用することもできます。ちょっとJavaScriptの知識が必要になりますが、がんばってみましょう。公式サイトのサンプルをわかりやすく書き換えたコードで説明します(やさしい)。
<input type="text" data-parsley-multiple="3" />
<script>
window.Parsley.addValidator("multiple", {
requirementType: "integer",
validateNumber: function (value, requirement) {
return 0 === value % requirement;
},
messages: {
en: "This value should be a multiple of %s",
ja: "この値は %s の倍数でなければなりません。",
},
});
</script>
これは入力された数値が3の倍数かどうかを検証するバリデータです。
バリデータの名前
バリデータに名前を付けます。この例では multiple
(倍数)という名前を付けました。
HTMLフォームにバリデータを適用する時は data-parsley-バリデータ名
という属性を追加します。上記1行目の data-parsley-multiple
がそれですね。
そして、JavaScriptでは、5行目で multiple
という名前を定義しています。
バリデータの名前が複数の単語で構成される場合、ちょっとややこしくなります。
例えば、バリデータ名が multiple of
の場合、HTMLでは data-parsley-multiple-of
という名前になります。このような単語間をハイフンでつなぐ命名規則をケバブケースといいます。
JacaScriptでは multipleOf
という名前になります。これはキャメルケースです。単語の先頭が大文字になります。
要件パラメータ
6行目の requirementType:
は、data-parsley-multiple
の値(この例では3)に期待される型を指定します。指定できる型は次のとおりです。
型 | 説明 |
---|---|
'string' | 文字列。型のチェックは行われません。 |
'integer' | 整数かどうかをチェックします。 |
'number' | 数値かどうかをチェックします。 |
'date' | 日付かどうかをチェックします。 |
'regexp' | 正規表現文字列または単純な式かどうかをチェックします。 |
'boolean' | ブーリアン型(true, false)かどうかをチェックします。 |
フォームの入力値
7行目の validateNumber
は、フォームに入力される値の検証方法を指定しています。指定できる値は次のとおりです。
名前 | 説明 |
---|---|
validateString | 入力値は文字列として渡されます。 |
validateNumber | 入力値は数値として渡されます。 |
validateDate | 入力値は日付として渡されます。 |
validateMultiple | チェックボックスの値の配列が渡されます。 |
関数
7〜9行目で、バリデーションするための関数が定義されています。この関数の引数 value
はフォームの入力値、 requirement
は属性値(この例では3)をあらわしています。
この関数の戻り値が true
ならば検証成功、false
ならば検証失敗となります。この例では value % requirement
の計算結果が 0
と等しければ true
、等しくなければ false
が戻り値です。
メッセージ
10〜13行目で、検証に失敗したときのメッセージを設定しています。複数の言語のメッセージを設定できます。
リモートバリデータ
Ajaxで外部のプログラムと通信をしてバリデーションをすることができます。
リモートバリデータを使用するには data-parsley-remote
属性を使用して外部プログラムを指定します。
<input type="text" name="合言葉" data-parsley-remote="./yunyun.php">
<?php
if($_GET['合言葉'] == 'ゆんゆん'){
$code = 200;
}
else{
$code = 404;
}
http_response_code($code);
合言葉が「ゆんゆん」と一致するかどうかをチェックするバリデータです(なにそれ)。
バリデーションプログラム yunyun.php
は $_GET
でフォームの入力値を受け取ります。検証に成功した場合はHTTPステータスコード 200
を、失敗した場合は 404
を返すようにします。これだけです。簡単ですね。楽しいですね。
これでデータベースを参照してバリデーションなんてこともできちゃいます。便利ですね。楽しいですね。
Parsley.jsの設定
エラーメッセージのカスタマイズ
エラーメッセージの文言を変更する場合は data-parsley-error-message
属性を使います。
<input
type="text"
name="名前"
required
data-parsley-error-message="名を名乗れ"
/>
複数のバリデータを使用している場合はバリデータごとにメッセージを変えることができます。data-parsley-バリデータ名-message
を使います。
<input
type="text"
name="名前"
required
minlength="3"
data-parsley-required-message="名を名乗れ"
data-parsley-minlength-message="3文字以上で名を名乗れ"
/>
エラーメッセージを表示したくない場合は data-parsley-errors-messages-disabled
を使います。
<input
type="text"
name="名前"
required
data-parsley-errors-messages-disabled
/>
エラーメッセージの表示位置を変更するには data-parsley-errors-container
属性でエラーメッセージを表示するコンテナの id
を指定します。
<div class="form-check">
<input
class="form-check-input"
type="checkbox"
name="好きな動物"
id="インパラ"
value="インパラ"
required
data-parsley-mincheck="3"
data-parsley-errors-container="#エラーメッセージ"
/><label class="form-check-label" for="インパラ">インパラ</label>
</div>
<div class="form-check">
<input
class="form-check-input"
type="checkbox"
name="好きな動物"
id="チベットスナギツネ"
value="チベットスナギツネ"
/><label class="form-check-label" for="チベットスナギツネ"
>チベットスナギツネ</label
>
</div>
<div class="form-check">
<input
class="form-check-input"
type="checkbox"
name="好きな動物"
id="マンドリル"
value="マンドリル"
/><label class="form-check-label" for="マンドリル"
>マンドリル</label
>
</div>
<div id="エラーメッセージ"></div>
バリデーションのタイミングのカスタマイズ
デフォルトではエラーメッセージは送信ボタンを押したときに表示されます。これは data-parsley-trigger
属性で変更できます。設定できる値はjQueryでサポートされているイベントです。スペースで区切って複数指定することもできます。
よく使うイベントを紹介します。
focusin | 要素にフォーカスが当たったとき |
focusout | 要素からフォーカスが外れたとき |
keyup | キーボードのキーが押され上がったとき |
change | 要素の値が変更されたとき |
input | 要素の値が変更されたとき |
click | 要素がクリックされたとき |
要素からフォーカスが外れた時にエラーメッセージを表示する例です。
<form action="" method="post" data-parsley-trigger="focusout">
...
</form>
入力が止まった後、指定したミリ秒だけ検証を遅延させるには data-parsley-debounce
属性を使います。キー入力のたびに検証を実行したくないとき、例えばリモートバリデータを使うときに便利そうです。
<input
type="text"
name="合言葉"
data-parsley-remote="./yunyun.php"
data-parsley-debounce="500"
/>
入力欄の文字数が指定した数になるまで検証を行わないようにするには data-parsley-validation-threshold
属性を使います。初期値は3です。
<input
type="password"
name="パスワード"
required
pattern="[a-zA-Z0-9]{8,32}"
data-parsley-validation-threshold="7"
/>
入力欄にフォーカスしただけで、まだ何も入力していないのにエラーメッセージが表示されたら、私はとてもイヤです。入力中にエラーが出たら「私がまだ書いてる途中でしょうが!」と北の国からの五郎さんばりに怒鳴ってしまいそうです。
なので、エラーメッセージを表示するタイミングは送信ボタンを押したとき、またはフォーカスが外れたときくらいにしておくのがいいと個人的には思います。キーアップのたびに検証するならば、上記の検証を遅らせる技をあわせて使いましょう。
検証結果の装飾のカスタマイズ
デフォルトでは検証結果が成功ならば parsley-success
失敗ならば parsley-error
が、バリデーションを設定した要素の class
の値として付加されます。この class
を利用してフォーム部品に色を付けるなどの装飾をしています。
data-parsley-class-handler
属性で id
を指定して、class
の付加先を変更できます。下記の例では <div id="名前のコンテナ">
にclass="parsley-success|parsley-error"
が付加されるようになります。
<div id="名前のコンテナ">
<label for="名前">名前</label>
<input
type="text"
name="名前"
required
data-parsley-class-handler="#名前のコンテナ"
/>
</div>
UI(エラーメッセージや入力欄の装飾)を無効化するには data-parsley-ui-enabled
属性に false
を設定します。
<input
type="text"
name="名前"
required
data-parsley-ui-enabled="false"
/>
Parsley.jsのUIの装飾はparsley.css
で行っていますが、これを使用しないで自分でCSSを書くこともできます。parsley.css
の中を見れば、どのように記述すればよいかわかりますね。
/* 検証が成功したとき */
input.parsley-success,
select.parsley-success,
textarea.parsley-success {
color: #468847;
background-color: #dff0d8;
border: 1px solid #d6e9c6;
}
/* 検証が失敗したとき */
input.parsley-error,
select.parsley-error,
textarea.parsley-error {
color: #b94a48;
background-color: #f2dede;
border: 1px solid #eed3d7;
}
/* エラーメッセージのリスト<ul>に設定されるclass */
.parsley-errors-list {
margin: 2px 0 3px;
padding: 0;
list-style-type: none;
font-size: 0.9em;
line-height: 0.9em;
opacity: 0;
color: #b94a48;
transition: all 0.3s ease-in;
-o-transition: all 0.3s ease-in;
-moz-transition: all 0.3s ease-in;
-webkit-transition: all 0.3s ease-in;
}
.parsley-errors-list.filled {
opacity: 1;
}
その他のカスタマイズ
1つの入力項目で複数の検証をするとき、初期値では最初の検証結果のエラーメッセージだけが表示されます。すべてのエラーメッセージを表示するようにするには data-parsley-priority-enabled="false"
を使用します。
検証時に入力データの空白文字を取り除くには次の属性を使用します。
data-parsley-whitespace="trim" | 先頭と末尾の空白文字を取り除く |
data-parsley-whitespace="squish" | 連続した空白文字を1つにまとめ、先頭と末尾の空白文字を取り除く |
設定をJavaScriptで記述する
これまでの説明では、HTMLに data-parsley-
で始まる属性を追加してParsley.jsの設定をしてきました。これらの設定はJavaScriptで記述することもできます。
<form id="私のフォーム">
...
</form>
<script>
$("#私のフォーム").parsley({
trigger: "focusout",
priorityEnabled: false,
});
</script>
HTMLの属性名から data-parsley-
を取り除いてケバブケースをキャメルケースに変換したものがJavaScriptにおける設定名となります。
HTMLの属性名 | JavaScriptの設定名 |
---|---|
data-parsley-trigger | trigger |
data-parsley-priority-enabled | priorityEnabled |
Bootstrapで使う場合の設定
BootstrapのフォームでParsley.jsを使う場合は、次のように設定します。
- 検証結果の有効・無効をあらわすclass名
parsley-success
とparsley-error
をBootstrap対応のis-valid
とis-invalid
に変更する。 - エラーメッセージを囲むHTMLを設定する。
- チェックボックス、ラジオボタン用の設定をする。
<script>
$("#私のフォーム").parsley({
//Bootstrapに対応したクラス名に変更
errorClass: "is-invalid",
successClass: "is-valid",
//エラーメッセージを囲むHTML
errorsWrapper: '<ul class="list-unstyled invalid-feedback mb-0"></ul>',
errorTemplate: "<li></li>",
});
//チェックボックス、ラジオボタンの設定
//同じグループの<input>要素に同じclassを設定しておく
//例: <input type="checkbox" class="foo">
$(".foo").parsley({ classHandler: ".foo" });
</script>
BootstrapとParsley.jsを使ったフォームのデモ
でわでわ
コメント