フォーム

　WEB上で入力フォームを作成する時、一般的な処理や定型的な処理が多く存在します。 そのような汎用的な処理をクラスにまとめ、簡単に入力フォームを作成できるのが、このライブラリになります。

　SyLフレームワークのフォームクラスは、3種類あります。
　・フォームクラス
　・アクションフォームクラス
　・ADMアクションフォームクラス

　「フォームクラス」は、3種類中で最も低レベルで汎用的なフォームクラスで、SyLフレームワークを使用しない外部システムでも使用できます。
　「アクションフォームクラス」は、予めフォーム定義を作成したクラスを使用し、フォーム内の修正、フォーム自体の再利用が容易です。
　「ADMアクションフォームクラス」は、ADM (汎用データ管理)のフォーム関連処理で使用されるクラスです。

　ここでは、「フォームクラス」について説明します。

　基本的な使用方法は、下記のようになります。

＜アクション内容＞

// フォームクラスインクルード
// ※SyL外で使用する際は、直接インクルードしてください
SyL_Loader::lib('Form');
SyL_Loader::lib('ValidationManager');

// バリデーション基本パターン作成
$v_require   =& SyL_Validator::create('require', '{name}は必須です');
$v_length20  =& SyL_Validator::create('length',  '{name}は最大{max}文字
（バイト）まで入力できます', array('max'=> 20));

// フォームオブジェクト作成
$form =& new SyL_Form();

// フォーム要素: 名前
$element =& $form->createElement('text', 'name', '名前', array(), 
array('size' => '30'));
// バリデーションセット
$vs =& SyL_Validators::create();
$vs->add($v_require);
$vs->add($v_length20);
$element->setValidators($vs);
$form->addElement($element);

// フォーム要素: 性別
$gender = array(
  '1' => '男',
  '2' => '女'
);
$element =& $form->createElement('radio', 'gender', '性別',
$gender, array());
// バリデーションセット
$vs =& SyL_Validators::create();
$vs->add($v_require);
$element->setValidators($vs);
$form->addElement($element);

// サブミットボタン
$element =& $form->createElement('submit', 'OK', '送信');
$form->addElement($element);

// POSTならバリデーション処理
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    if ($form->validate()) {
        // バリデーションOK
        // フォーム内容を確認表示に変更
        $form->setReadOnly(true);
    }
}

// 結果を連想配列で取得
$forms =& $form->getResultArray();

＜テンプレート内容＞

<?php if ($forms['error']) { ?>
<font color="#990000"><?= implode('<br>', $forms['error_message']) ?></font>
<br><br>
<?php } ?>

<table>
<form <?= $forms['attributes'] ?>>
<tr>
<td><?= $forms['elements']['name']['label'] ?>
</td><td><?= $forms['elements']['name']['html'] ?></td>
</tr>
<tr>
<td><?= $forms['elements']['gender']['label'] ?></td>
<td><?= $forms['elements']['gender']['html'] ?></td>
</tr>
<tr>
<td colspan="2"><?= $forms['elements']['ok']['html'] ?></td>
</tr>
</form>
</table>

アクションでは、まずフォームオブジェクトを作成し、下記のように要素を作成します。

$element =& $form->createElement('text', 'name', '名前', array(), 
array('size' => '30'));

要素を作成する createElement メソッドの仕様です。

作成した要素に対して、バリデーションを追加することができます。
バリデーションは、最初に基本パターンを作成し、

$v_require =& SyL_Validator::create('require', '{name}は必須です');

要素に追加する流れになります。

// バリデーショングループ作成
$vs =& SyL_Validators::create();
$vs->add($v_require);
// バリデーションを要素に追加
$element->setValidators($vs);

※バリデーションの使い方や種類は 7.3 バリデーション 参照

フォームの要素を作成し、大本のフォームオブジェクトにセットしたら、 場合よりバリデーションを行います。

if ($form->validate()) {
    $form->setReadOnly(true);
}

フォームオブジェクトの validate メソッドでバリデーションを実行し、 問題なければ（エラーがなければ）確認画面を表示するため、setReadOnly メソッドで全要素を読み取り専用にしています。

最後に表示処理用のデータを（配列として）取得します。

$forms =& $form->getResultArray();

テンプレート側では、表示処理用のデータを使用してフォームを構築します。

フォームオブジェクトの getResultArray メソッドで取得できる連想配列の仕様です。

[last_name] => Array
    (
        [label] => 名前（姓）
        [html] => <input size="30" 
name="last_name" type="text" value="" />
        [require] => 1
        [error] => 
        [error_message] => 
        [read_only] => 
    )

[first_name] => Array
    (
...

　使用できるフォームの要素を下記に記載します。

　フォーム要素を作成しているときに、要素をグループ化して扱えたら便利なことがあります。 例えば、電話番号の3つのテキストボックスを例に示すと、

電話番号：  -  - 

というものです。 要素のグループ化は、このように複数の要素をグループ化して、1つの要素として扱うことができます。

コード例は、下記のようになります。

＜アクション内容＞

$element =& $form->createElement('group', 'tel', '電話番号');
$element->addElement($form->createElement('text', 'tel1', '電話番号1', 
array(), array('size' => '10')));
$element->addElement($form->createElement('text', 'tel2', '電話番号2', 
array(), array('size' => '10')));
$element->addElement($form->createElement('text', 'tel3', '電話番号3', 
array(), array('size' => '10')));
$element->setFormat('%s - %s - %s', 'tel1', 'tel2', 'tel3');
$vs =& SyL_Validators::create();
$vs->add($v_require);
$vs->add($v_numeric);
$element->setValidators($vs);
$form->addElement($element);

＜テンプレート内容＞

<?= $forms['elements']['tel']['label'] ?>
<?= $forms['elements']['tel']['html'] ?>

　外部からの入力に対して欠かせない処理の1つにバリデーションがあります。 特にフォームのバリデーションは、適正なデータのみをフィルタリングするだけでなく、 正確なエラーメッセージを表示することにより、ユーザビリティの向上にも付与します。

　サーバー側のバリデーションであれば、「1. フォーム例」で示した例のように記述することにより、 自動で実行することができますが、使用できるバリデーションには、サーバー側の他に クライアント側（JavaScript）バリデーションもあります。

　クライアント側バリデーションは、サーバー側で定義したバリデーションを、 JavaScriptコードとして出力することにより、 サーバー側と同一のチェックをクライアント側でも行うことができます。

　クライアント側バリデーションを使用するには、下記のような流れになります。

(1) サーバー側で、Validation ライブラリを出力するPHPコードを記述
(2) クライアント側で、Validation ライブラリをインポート
(3) サーバー側で、JavaScriptバリデーションを有効化
(4) クライアント側で、バリデーションコードを出力

(1) サーバー側で、Validation ライブラリを出力するPHPコードを記述

　クライアント側バリデーションを行うには、まずJavaScriptバリデーションライブラリをインポートします。

　もし、JavaScript出力フレームワークを使用しているのであれば、外部パラメータから読み込めるので、ここは省略可能です。 WEBアプリケーションフレームワークのみで作成する場合は、下記のように直接アクションで 動的にJavaScript出力ビューに切り替え、 Validationライブラリを出力します。

    function execute(&$data, &$context)
    {
        $context->setViewType('js.default');
        $data->addImport('validation');
    }

(2) クライアント側で、Ajax ライブラリをインポート

　(1)で作成したサーバー側のファイルを HTML のスクリプトタグで読み込みます。

スクリプトタグの記述例）
<script type="text/javascript" 
src="/web_controller.php/validation.html"></script>

　JavaScript出力フレームワークを使用している場合は、(1)を行わなくてもアクションがマッピングされていないURLに対して下記のように記述することにより自動的にインポートできます。

スクリプトタグの記述例）
<script type="text/javascript" 
src="/js_controller.php/index.js?import=Validation"></script>

※ここでインポートする Ajax ライブラリは、SYL_INCLUDE_DIR /lib/JsClient/SyL_JsClientValidation.js となり、上記方法ではこれを直接インポートしています。

(3) JavaScriptバリデーションを有効化

　PHP側でフォームオブジェクト生成後に、クライアント側バリデーション実行関数名を引数に useJs メソッドを実行する。

...
$form->useJs('sylFormCheck');
...

(4) クライアント側で、バリデーションコードを出力

　$forms['js_code']を出力すると、「(3) JavaScriptバリデーションを有効化」で指定した関数名でバリデーションコードが出力されます。

...
<?php echo $forms['js_code']; ?>
...

[ 関数の仕様 ]
　入力項目にエラーが発生した場合、（デフォルトで）アラート表示してエラー要素をフォーカスします。
・引数
　(1) フォームオブジェクト
・戻り値
　true: エラー無し、false: エラーあり

後は、その関数を使用してJavaScriptバリデーションを実現します。

...
<form ... onsubmit="return sylFormCheck(this);">
...