Drupal 7 の Form API #states の使い方
手短な説明にはなりますが、 Drupal の Form API の #states というパラメータの使い方についてかんたんにご紹介したいと思います。
Drupal でフォームをプログラムで作成する場合は #states というパラメータを使うことにより、通常 JavaScript 側で記述しなくてはならないフィールドの状態変更を PHP 側で記述することができます。
たとえば
- 特定のチェックボックスにチェックが入っているときだけフィールドを表示する
- 特定のチェックボックスにチェックが入っていなければ送信ボタンを無効化する
といった「他のフィールドの状態に応じてフィールドの状態を設定する」ちょっとした設定が PHP 側だけで完結した形で記述できます。
具体例を見てみます。
mymodule というカスタムモジュールがあるものとします。
mymodule モジュールに以下の hook_menu() を追加します。
/**
* Implements hook_menu().
*/
function mymodule_menu() {
// #states を使ったフォームのサンプル
$items['sample-form'] = array(
'title' => 'Sample form with state',
'page callback' => 'drupal_get_form',
'page arguments' => array('mymodule_state_form'),
'access callback' => TRUE,
);
return $items;
}mymodule_state_form というフォーム生成用の関数を定義する必要があるので以下のとおりに記述します。
/**
* Drupal の Form API の #states を使ったフォームを生成
*/
function mymodule_state_form($form, &$form_state) {
$form['comment'] = array(
'comment_check' => array(
'#type' => 'checkbox',
'#title' => 'Add comment',
),
$form['actions'] = array(
'submit' => array(
'#type' => 'submit',
'#value' => t('submit'),
'#button_type' => 'submit',
// comment_check フィールドにチェックが入っていない場合は
// submit ボタンを無効化する
'#states' => array(
'disabled' => array(
':input[name="comment_check"]' => array('checked' => FALSE),
),
),
),
);
return $form;
}ここで注目していただきたいのは submit フィールドに追加された #states プロパティです。
こちらは以下のフォーマットで要素の状態変更の設定を定義しています。
'#states' => array(
状態A => array(
jQuery セレクタ => array(状態のキー => 状態の値),
),
),意味合いは次のとおりとなります。
- 「 jQuery セレクタ」で指定した要素が
- 「状態のキー」と「状態の値」で示された状態になれば
- このフィールドを「状態A」の状態に変更してね
実際、パス /sample-form にアクセスしてこのフォームを表示すると、「 Add comment 」というラベルのついたフィールドにチェックが入っていないときには submit ボタンが押せないことが確認できるかと思います。
今回の例では disabled を例にとりましたが、 disabled の他にも要素に設定する状態としては次のものが利用できます。
enabledrequiredoptionalvisibleinvisiblecheckeduncheckedexpandedcollapsed
基本的な使い方だけのご紹介でしたが、これができることがわかっていればさまざまな場面で JS の記述を省略することができるかと思います。 よく考えられています。 便利ですねー。