アクションフォーム

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

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

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

　ここでは、「アクションフォームクラス」について説明しますが、基本は「フォームクラス」なので、そちらも参考にしてください。

1. アクションフォーム例

　アクションフォームクラスは、フォームクラスの上に成り立ち、アクションフォームを継承したサブクラスの設定でフォームを構築します。設定を予め定義することにより、メインロジックの見通しが良くなったり、再利用しやすくなります。

アクションフォームを作成する手順は、
(1) アクションフォームを継承したサブクラスを作成する
(2) アクション内で、(1)で作成したクラスをインスタンス化し（必要に応じて処理を行い）、テンプレートにセット
(3) テンプレート内で、アクションから渡されたオブジェクトから要素を取得し表示処理を行う

(1) アクションフォームを継承したサブクラスの例

(SYL_APP_DIR) /lib/Forms/MailForm.php

class FormsMailform extends SyL_ActionForm
{
    var $elements_config = array(
        'name' => array(
            'type'         => 'text',
            'name' => '名前',
            'options'      => array(),
            'attributes'   => array('size' => '30'),
            'validate'     => array(
                'require' => array(
                    'message'    => '{name}は必須となります',
                    'parameters' => array()
                ),
                'length' => array(
                    'message'    => '{name}は{max}バイトまで入力できます',
                    'parameters' => array('max' => 50)
                )
            )
        ),
        'mail_address' => array(
...

(2) アクションのコード例

...
// アクションフォームオブジェクト取得
$form =& $this->getActionForm($data, 'Forms.Mailform', $context->isPost());
// アクションフォームオブジェクトをセット
$data->setRef('form', $form->getResultArray());
...

(3) テンプレートのコード例

...
{if $form.error}
<h4>下記エラーが発生しました。<br>修正してから再度送信お願いします</h4>
<p>
{foreach from=$form.error_message item=error_message}
・{$error_message}<br>
{/foreach}
</p>
{/if}

<table>
  <form {$form.attributes}>
  <tr>
    <th>{$form.elements.name.label}{if !$form.read_only}
 <font color="#CC0000">*</font>{/if}</td>
    <td>{$form.elements.name.html}</td>
  </tr>
  <tr>
    <th>{$form.elements.mail_address.label}</td>
    <td>{$form.elements.mail_address.html}</td>
  </tr>
...

2. アクションフォームクラス

　アクションフォームクラスは、アクションクラス内でインスタンス化するSyL_ActionFormクラスを継承したフォームクラスで、フォームの表示内容やバリデーション内容を設定するクラスとなります。

　このクラスは、lib ディレクトリ（SYL_APP_DIR または、SYL_PROJECT_LIB_DIR）内に保存し、lib 以下のディレクトリ名とファイル名の先頭大文字にして結合した命名規則（例えば、lib/Forms/Sample.php ならクラス名は FormsSample）で作成します。

　フォームの設定は、このクラスの $elements_config プロパティに設定します。

フォームの設定（$elements_config）の定義

$elements_config は、連想配列で定義します。連想配列のキー値は、フォーム内の各要素名になり、要素名に対する値が、要素を構成する連想配列になります。

＜要素ごとに設定値＞

キー名	型	内容
name	string	要素の表示名
type	string	要素のタイプ
options	array	要素のサブ項目。radio, select, checkbox の各項目になり、キーが項目値、値が表示値の配列で設定する
attributes	array	要素の追加属性。例えば、text に size 属性を設定する場合、キーが size、値がサイズ値の配列となる。
default	string	要素のデフォルト値
validate	array	要素のバリデーション設定配列。詳細は後述。

バリデーションの設定

　バリデーションは、validate 要素の値（配列）として設定します。キーに使用するバリデーションの種類を指定し、その値としてエラーメッセージを格納する message キーと、バリデーションパラメータを持った parameters キーの配列からなります。

※バリデーションの種類やバリデーションパラメータについては、7.3 バリデーションの種類参照

　複数バリデーションの種類が設定された場合、上から順に実行され、エラーになったバリデーションのエラーメッセージが返されます。（エラーになったバリデーションより後は実行されません）

　エラーメッセージは、message キーで指定した値が返されます。エラーメッセージの中に{name}文字列があるとフォーム要素名に変換されます。また、{}の中にバリデーションパラメータ名があると、その値で変換されます。

＜設定例＞

...
    var $elements_config = array(
        'name' => array(
            'type'         => 'text',
            'name' => '名前',
            'options'      => array(),
            'attributes'   => array('size' => '30'),
            'validate'     => array(
                'require' => array(
                    'message'    => '{name}は必須となります',
                    'parameters' => array()
                ),
                'length' => array(
                    'message'    => '{name}は{max}バイトまで入力できます',
                    'parameters' => array('max' => 50)
                )
            )
        ),
        'mail_address' => array(
...

3. アクションの記述

　作成したアクションフォームクラスをアクションで使用するには、アクションフォームクラスをインスタンス化する必要があります。アクションで、インスタンスを取得するには、アクションの親クラスに実装されている getActionForm メソッドを使用します。

...
function execute(&$data, &$context)
{
...
// アクションフォームオブジェクト取得
$form =& $this->getActionForm($data, 'Forms.Mailform', $context->isPost());
// アクションフォームオブジェクトをセット
$data->setRef('form', $form->getResultArray());
...

getActionForm メソッドの引数は、3つあります。
(1) データ管理オブジェクト
(2) アクションフォームクラスパス
(3) 初期化フラグ（オプション: デフォルト false）

アクションフォームクラスパスは、SyL_Loaderクラスで読み込める形式で指定します。
初期化フラグは、アクションフォームクラスで定義されたデフォルト値をセットするフラグになります。（true だとセットされる）

　インスタンス化した後は、適宜処理を行いテンプレートに渡すためのフォームデータを getResultArray メソッドで配列に変換しセットします。

※以降の流れはフォームクラスと同様なので、フォームクラスを参照してください。