repo_zf1/documentation/manual/ja/module_specs/Zend_Form-QuickStart.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.form.quickstart">
    <title>Zend_Form クイックスタート</title>

    <para>
        このクイックスタートガイドでは、<classname>Zend_Form</classname>
        を用いたフォームの作成や検証、そしてレンダリングについての基本を扱います。
    </para>

    <sect2 id="zend.form.quickstart.create">
        <title>フォームオブジェクトの作成</title>

        <para>
            フォームオブジェクトを作成するのは非常に簡単で、
            単に <classname>Zend_Form</classname> のインスタンスを作成するだけです。
        </para>

        <programlisting language="php"><![CDATA[
$form = new Zend_Form;
]]></programlisting>

        <para>
            より高度に使いこなす際には <classname>Zend_Form</classname>
            のサブクラスを作成することになるかもしれません。
            しかし、単純なフォームの場合は <classname>Zend_Form</classname>
            オブジェクトをそのまま使えばプログラム上でフォームを作成できます。
        </para>

        <para>
            フォームのアクションやメソッドを指定したい場合は (普通はするでしょうね)、
            <methodname>setAction()</methodname> メソッドおよび
            <methodname>setMethod()</methodname> メソッドを使用します。
        </para>

        <programlisting language="php"><![CDATA[
$form->setAction('/resource/process')
     ->setMethod('post');
]]></programlisting>

        <para>
            このコードは、フォームのアクションをパーシャル <acronym>URL</acronym>
            "<filename>/resource/process</filename>" に設定し、メソッドに <acronym>HTTP</acronym> <acronym>POST</acronym>
            を指定します。これは、最終的なレンダリングの際に反映されます。
        </para>

        <para>
            さらに、<emphasis>&lt;form&gt;</emphasis>
            タグ用のその他の <acronym>HTML</acronym> 属性を設定することもできます。
            その場合は <methodname>setAttrib()</methodname> メソッドあるいは <methodname>setAttribs()</methodname> メソッド使用します。
            たとえば id を指定したい場合は、"<property>id</property>" 属性を使用します。
        </para>

        <programlisting language="php"><![CDATA[
$form->setAttrib('id', 'login');
]]></programlisting>
    </sect2>

    <sect2 id="zend.form.quickstart.elements">
        <title>フォームへの要素の追加</title>

        <para>
            要素がなければフォームには何の意味もありません。
            <classname>Zend_Form</classname> にデフォルトで組み込まれている要素を使用すると、
            <classname>Zend_View</classname> ヘルパーを用いて <acronym>XHTML</acronym> 形式でレンダリングできます。
            以下のような要素が組み込まれています。
        </para>

        <itemizedlist>
            <listitem><para>
                button
            </para></listitem>

            <listitem><para>
                checkbox (あるいは複数チェックボックスを一度にレンダリングする multiCheckbox)
            </para></listitem>

            <listitem><para>
                hidden
            </para></listitem>

            <listitem><para>
                image
            </para></listitem>

            <listitem><para>
                password
            </para></listitem>

            <listitem><para>
                radio
            </para></listitem>

            <listitem><para>
                reset
            </para></listitem>

            <listitem><para>
                select (通常のものと複数選択形式のものの両方)
            </para></listitem>

            <listitem><para>
                submit
            </para></listitem>

            <listitem><para>
                text
            </para></listitem>

            <listitem><para>
                textarea
            </para></listitem>
        </itemizedlist>

        <para>
            フォームに要素を追加するには、二通りの方法があります。
            フォーム要素のインスタンスを作成してそのオブジェクトを渡す方法と、
            単に要素の型だけを渡して <classname>Zend_Form</classname>
            にその型のオブジェクトを作成させる方法です。
        </para>

        <para>
            いくつか例を示します。
        </para>

        <programlisting language="php"><![CDATA[
// 要素のインスタンスを作成してフォームオブジェクトに渡します
$form->addElement(new Zend_Form_Element_Text('username'));

// フォーム要素の型をフォームオブジェクトに渡します
$form->addElement('text', 'username');
]]></programlisting>

        <para>
            デフォルトでは、バリデータやフィルタは一切含まれません。
            つまり、追加した要素に対して最低でもバリデータを指定し、
            おそらくフィルタも指定しなければならないということです。
            これは、(a) 要素をフォームに追加する前に行う、
            (b) <classname>Zend_Form</classname> で要素を作成する際のオプションで指定する、
            あるいは (c) 要素を追加した後でフォームオブジェクトから要素を取り出し、
            それを設定する
            のいずれかの方法で行います。
        </para>

        <para>
            まずは要素のインスタンスにバリデータを追加する例を見てみましょう。
            <classname>Zend_Validate_*</classname> オブジェクトそのものを渡すか、
            あるいは使用するバリデータの名前を渡すことになります。
        </para>

        <programlisting language="php"><![CDATA[
$username = new Zend_Form_Element_Text('username');

// Zend_Validate_* オブジェクトを渡します
$username->addValidator(new Zend_Validate_Alnum());

// バリデータ名を渡します
$username->addValidator('alnum');
]]></programlisting>

        <para>
            2 番目の方法を使用する場合、
            もしバリデータのコンストラクタに引数を指定するのならば
            それを配列形式で 3 番目のパラメータとして指定します。
        </para>

        <programlisting language="php"><![CDATA[
// 正規表現パターンを渡します
$username->addValidator('regex', false, array('/^[a-z]/i'));
]]></programlisting>

        <para>
            (2 番目のパラメータの意味は、
            このバリデータの検証に失敗した場合にそれ以降のバリデータの実行を防止するか否かを表します。
            デフォルトではこの設定は <constant>FALSE</constant> です)
        </para>

        <para>
            特定の要素を必須項目として指定したいこともあるでしょう。
            その場合は、アクセサメソッドで指定するか、
            要素を作成する際のオプションとして指定します。
            ここでは前者の方法の例を示します。
        </para>

        <programlisting language="php"><![CDATA[
// この要素は必須です
$username->setRequired(true);
]]></programlisting>

        <para>
            要素が必須な場合は、'NotEmpty' バリデータが
            バリデータチェインの先頭に追加されます。
            これで、必須要素には値が入力されていることが保証されます。
        </para>

        <para>
            フィルタの登録方法は、基本的にはバリデータと同じです。
            例として、最終的な値を小文字変換するフィルタを追加してみましょう。
        </para>

        <programlisting language="php"><![CDATA[
$username->addFilter('StringtoLower');
]]></programlisting>

        <para>
            これまでの内容をまとめると、要素の設定はこのようになります。
        </para>

        <programlisting language="php"><![CDATA[
$username->addValidator('alnum')
         ->addValidator('regex', false, array('/^[a-z]/'))
         ->setRequired(true)
         ->addFilter('StringToLower');

// あるいは、もうすこしコンパクトに書くなら
$username->addValidators(array('alnum',
        array('regex', false, '/^[a-z]/i')
    ))
    ->setRequired(true)
    ->addFilters(array('StringToLower'));
]]></programlisting>

        <para>
            シンプルといえばシンプルですが、
            フォームのすべての要素についてこれを行うというのも
            ちょっと面白くありません。上で説明した (b)
            の方法を試してみましょう。
            <methodname>Zend_Form::addElement()</methodname>
            をファクトリメソッドとして使用して新しい要素を作成する際に、
            設定オプションを渡すことができます。
            たとえば、使用するバリデータやフィルタをここで指定することが可能です。
            先ほどと同じ設定を行うには、次のように書きます。
        </para>

        <programlisting language="php"><![CDATA[
$form->addElement('text', 'username', array(
    'validators' => array(
        'alnum',
        array('regex', false, '/^[a-z]/i')
    ),
    'required' => true,
    'filters'  => array('StringToLower'),
));
]]></programlisting>

        <note><para>
            同じオプションを指定した要素をいろんな場所で使用するような場合は、
            <classname>Zend_Form_Element</classname> のサブクラスを作成してそれを使用するといいでしょう。
            長い目で見れば、そのほうがタイピング量を軽減できます。
        </para></note>
    </sect2>

    <sect2 id="zend.form.quickstart.render">
        <title>フォームのレンダリング</title>

        <para>
            フォームのレンダリングの方法は簡単です。
            ほとんどの要素は <classname>Zend_View</classname>
            ヘルパーを用いて自身のレンダリングを行うので、
            ビューオブジェクトが必要となります。
            それ以外の方法としては、フォームの render()
            メソッドを使う方法と単純に echo する方法があります。
        </para>

        <programlisting language="php"><![CDATA[
// 明示的に render() をコールし、オプションでビューオブジェクトを渡します
echo $form->render($view);

// 事前に setView() でビューオブジェクトが設定されているものとします
echo $form;
]]></programlisting>

        <para>
            デフォルトでは、<classname>Zend_Form</classname> と
            <classname>Zend_Form_Element</classname> は
            <classname>ViewRenderer</classname> が初期化したビューオブジェクトを使おうと試みます。
            つまり、Zend Framework の <acronym>MVC</acronym>
            を使用している場合は、自分でビューを設定する必要はないということです。
            フォームをビュースクリプト内でレンダリングするには、
            単に次のように書くだけです。
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->form ?>
]]></programlisting>

        <para>
            水面下では、<classname>Zend_Form</classname> は "デコレータ"
            を用いてレンダリングを行っています。
            このデコレータが、コンテンツの置換や
            先頭 (あるいは末尾) へのコンテンツの追加、
            その他コンテンツに対する操作を行うことになります。
            複数のデコレータを組み合わせることで、
            さまざまな効果を適用できます。
            デフォルトでは、<classname>Zend_Form_Element</classname>
            は 4 つのデコレータを組み合わせて出力を行います。
            その設定は、次のようになっています。
        </para>

        <programlisting language="php"><![CDATA[
$element->addDecorators(array(
    'ViewHelper',
    'Errors',
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));
]]></programlisting>

        <para>
            (&lt;HELPERNAME&gt; は使用しているビューヘルパーの名前で、
            これは要素によって異なります)
        </para>

        <para>
            上の設定で出力した結果は次のようになります。
        </para>

        <programlisting language="html"><![CDATA[
<dt><label for="username" class="required">Username</dt>
<dd>
    <input type="text" name="username" value="123-abc" />
    <ul class="errors">
        <li>'123-abc' has not only alphabetic and digit characters</li>
        <li>'123-abc' does not match against pattern '/^[a-z]/i'</li>
    </ul>
</dd>
]]></programlisting>

        <para>
            (フォーマットは異なるかもしれません)
        </para>

        <para>
            出力を変えたい場合は、その要素で使用するデコレータを変更することもできます。
            詳細な情報は、デコレータのセクションを参照ください。
        </para>

        <para>
            フォームオブジェクトが各要素を順に処理し、
            <acronym>HTML</acronym> <emphasis>&lt;form&gt;</emphasis> タグの中に出力していきます。
            フォームを設定した際に指定したアクションとメソッドが
            <emphasis>&lt;form&gt;</emphasis> タグに設定されます。
            また同時に、<methodname>setAttribs()</methodname>
            系のメソッドで設定した属性もここで設定されます。
        </para>

        <para>
            要素の処理は、登録した順に行われます。
            要素の中に order 属性が指定されている場合は、
            そこで指定した順に従います。
            order を指定するには次のようにします。
        </para>

        <programlisting language="php"><![CDATA[
$element->setOrder(10);
]]></programlisting>

        <para>
            あるいは、要素を作成する際にオプションとして指定します。
        </para>

        <programlisting language="php"><![CDATA[
$form->addElement('text', 'username', array('order' => 10));
]]></programlisting>
    </sect2>

    <sect2 id="zend.form.quickstart.validate">
        <title>フォームの妥当性の検証</title>

        <para>
            フォームが送信されたら、
            その内容をチェックしてバリデーションを通過したかどうかを確認しなければなりません。
            各要素に入力されたデータについてチェックを行います。
            要素名にマッチするキーが存在しない場合、
            もしその項目が必須指定されているのなら
            <constant>NULL</constant> 値が指定されたものとしてバリデーションを行います。
        </para>

        <para>
            データはどこから取得するのでしょう? たとえば <code>$_POST</code> や
            <code>$_GET</code>、あるいはその他のデータソース
            (ウェブサービスへのリクエストなど) からです。
        </para>

        <programlisting language="php"><![CDATA[
if ($form->isValid($_POST)) {
    // 成功!
} else {
    // 失敗!
}
]]></programlisting>

        <para>
            <acronym>AJAX</acronym> リクエストの場合は、特定の要素や要素群だけを検証することもあります。
            <methodname>isValidPartial()</methodname> はフォームの一部を検証します。
            しかし、<methodname>isValid()</methodname>
            とは異なり、キーが存在しない場合はその要素のバリデーションを行いません。
        </para>

        <programlisting language="php"><![CDATA[
if ($form->isValidPartial($_POST)) {
    // 存在する要素はすべてバリデーションに通過しました
} else {
    // いくつかの要素がバリデーションに失敗しました
}
]]></programlisting>

        <para>
            さらに、<methodname>processAjax()</methodname>
            メソッドでもフォームの一部の検証を行うことができます。
            <methodname>isValidPartial()</methodname> とは異なり、
            このメソッドでは失敗時のエラーメッセージを
            <acronym>JSON</acronym> 形式の文字列で返します。
        </para>

        <para>
            バリデーションを通過したとしましょう。
            これで、フィルタリング済みの値を取得できるようになりました。
        </para>

        <programlisting language="php"><![CDATA[
$values = $form->getValues();
]]></programlisting>

        <para>
            フィルタリング前の値を取得したい場合は次のようにします。
        </para>

        <programlisting language="php"><![CDATA[
$unfiltered = $form->getUnfilteredValues();
]]></programlisting>

        <para>
            一方、部分的に妥当なフォームのうち、妥当でフィルタ処理した全ての値を必要とする場合、
            以下を呼び出しできます。
        </para>

        <programlisting language="php"><![CDATA[
$values = $form->getValidValues($_POST);
]]></programlisting>
    </sect2>

    <sect2 id="zend.form.quickstart.errorstatus">
        <title>エラー情報の取得</title>

        <para>
            バリデーションに失敗したらどうしたらいいのでしょう?
            たいていの場合は、フォームを再度レンダリングすることになるでしょう。
            デフォルトのデコレータを使用している場合は、
            エラーメッセージも表示されるようになります。
        </para>

        <programlisting language="php"><![CDATA[
if (!$form->isValid($_POST)) {
    echo $form;

    // あるいは、ビューオブジェクトを代入してビューをレンダリングします...
    $this->view->form = $form;
    return $this->render('form');
}
]]></programlisting>

        <para>
            エラーの内容を調べるには二通りの方法があります。
            <methodname>getErrors()</methodname> は、要素名とコードを対応させた連想配列を返します
            (コードは、エラーコードの配列となります)。
            <methodname>getMessages()</methodname> は、要素名とメッセージを対応させた連想配列を返します
            (メッセージは、エラーコードとエラーメッセージを対応させた連想配列となります)。
            エラーが発生していない要素については、
            結果の配列には含められません。
        </para>
    </sect2>

    <sect2 id="zend.form.quickstart.puttingtogether">
        <title>まとめ</title>

        <para>
            では、シンプルなログイン画面を作ってみましょう。
            この画面では、以下の項目に対応する要素が必要となります。
        </para>

        <itemizedlist>
            <listitem><para>ユーザ名</para></listitem>
            <listitem><para>パスワード</para></listitem>
            <listitem><para>送信ボタン</para></listitem>
        </itemizedlist>

        <para>
            今回の例では、ユーザ名として使用できるのは英数字のみであるとします。
            また、最初は必ず英字であること、長さは 6 文字から
            20 文字までの間であることとし、
            入力された内容はすべて小文字に変換することにします。
            パスワードは 6 文字以上でなければならないようにします。
            <!-- TODO : to be translated -->
            We'll simply toss the submit value when done,
            so it can remain unvalidated.
        </para>

        <para>
            <classname>Zend_Form</classname> のオプションを駆使して、
            フォームを作成してみましょう。
        </para>

        <programlisting language="php"><![CDATA[
$form = new Zend_Form();
$form->setAction('/user/login')
     ->setMethod('post');

// username 要素を作成・設定します
$username = $form->createElement('text', 'username');
$username->addValidator('alnum')
         ->addValidator('regex', false, array('/^[a-z]+/'))
         ->addValidator('stringLength', false, array(6, 20))
         ->setRequired(true)
         ->addFilter('StringToLower');

// password 要素を作成・設定します
$password = $form->createElement('password', 'password');
$password->addValidator('StringLength', false, array(6))
         ->setRequired(true);

// 要素をフォームに追加します
$form->addElement($username)
     ->addElement($password)
     // addElement() をファクトリとして使用して 'Login' ボタンを作成します
     ->addElement('submit', 'login', array('label' => 'Login'));
]]></programlisting>

        <para>
            次に、これを処理するためのコントローラを作成します。
        </para>

        <programlisting language="php"><![CDATA[
class UserController extends Zend_Controller_Action
{
    public function getForm()
    {
        // 先ほどのようなフォームを作成します
        return $form;
    }

    public function indexAction()
    {
        // user/form.phtml をレンダリングします
        $this->view->form = $this->getForm();
        $this->render('form');
    }

    public function loginAction()
    {
        if (!$this->getRequest()->isPost()) {
            return $this->_forward('index');
        }
        $form = $this->getForm();
        if (!$form->isValid($_POST)) {
            // バリデーションに失敗したので、フォームを再描画します
            $this->view->form = $form;
            return $this->render('form');
        }

        $values = $form->getValues();
        // ここで認証処理を行います
    }
}
]]></programlisting>

        <para>
            フォームを表示するためのビュースクリプトは次のようになります。
        </para>

        <programlisting language="php"><![CDATA[
<h2>Please login:</h2>
<?php echo $this->form ?>
]]></programlisting>

        <para>
            コントローラのコードをご覧になってお気づきの通り、
            やるべき作業がまだ残っています。
            入力された内容が妥当な形式であったとしても、
            たとえば <classname>Zend_Auth</classname> などを用いた認証処理が必要です。
        </para>
    </sect2>

    <sect2 id="zend.form.quickstart.config">
        <title>Zend_Config オブジェクトの使用法</title>

        <para>
            <classname>Zend_Form</classname> のすべてのクラスは
            <classname>Zend_Config</classname> を用いて設定できます。
            コンストラクタに <classname>Zend_Config</classname>
            オブジェクトを渡すか、あるいは <methodname>setConfig()</methodname>
            を使用して渡すことになります。先ほどのようなフォームを
            <acronym>INI</acronym> ファイルを用いて作成できないかどうかを検討してみましょう。
            <!-- TODO : to be translated -->
            First, let's follow the
            recommendations, and place our configurations into sections
            reflecting the release location, and focus on the 'development'
            section.
            次に、指定したコントローラ ('user') 用のセクションとフォーム
            ('login') 用のキーを作成します。
        </para>

        <programlisting language="ini"><![CDATA[
[development]
; フォーム全般のメタ情報
user.login.action = "/user/login"
user.login.method = "post"

; username 要素
user.login.elements.username.type = "text"
user.login.elements.username.options.validators.alnum.validator = "alnum"
user.login.elements.username.options.validators.regex.validator = "regex"
user.login.elements.username.options.validators.regex.options.pattern = "/^[a-z]/i"
user.login.elements.username.options.validators.strlen.validator = "StringLength"
user.login.elements.username.options.validators.strlen.options.min = "6"
user.login.elements.username.options.validators.strlen.options.max = "20"
user.login.elements.username.options.required = true
user.login.elements.username.options.filters.lower.filter = "StringToLower"

; password 要素
user.login.elements.password.type = "password"
user.login.elements.password.options.validators.strlen.validator = "StringLength"
user.login.elements.password.options.validators.strlen.options.min = "6"
user.login.elements.password.options.required = true

; submit 要素
user.login.elements.submit.type = "submit"
]]></programlisting>

        <para>
            そしてこれをフォームのコンストラクタに渡します。
        </para>

        <programlisting language="php"><![CDATA[
$config = new Zend_Config_Ini($configFile, 'development');
$form   = new Zend_Form($config->user->login);
]]></programlisting>

        <para>
            これでフォームの定義が完了しました。
        </para>
    </sect2>

    <sect2 id="zend.form.quickstart.conclusion">
        <title>結論</title>

        <para>
            ここまで読み進めてこられたみなさんは、
            <classname>Zend_Form</classname> のさまざまな機能を駆使するだけの準備ができたことでしょう。
            さらに詳細な情報に進んでいきましょう!
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->