repo_zf1/documentation/manual/ja/module_specs/Zend_View-Helpers.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 19425 -->
<sect1 id="zend.view.helpers" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>ビューヘルパー</title>

    <para>
        ビュースクリプトの中で、複雑な関数を繰り返し実行しなければならないこともあるでしょう
        (例えば日付のフォーマット、フォーム要素の作成、リンクの作成など)。
        このような作業を行うために、ヘルパークラスを使用できます。
    </para>

    <para>
        ヘルパーの正体は、単なるクラスです。たとえば 'fooBar' という名前のヘルパーを使用するとしましょう。
        デフォルトでは、クラス名の先頭には 'Zend_View_Helper_'
        がつきます (ヘルパーのパスを設定する際に、これは独自のものに変更できます)。
        そしてクラス名の最後の部分がヘルパーの名前となります。
        このとき、単語の先頭は大文字にしなければなりません。つまり、
        ヘルパーのクラス名は <classname>Zend_View_Helper_FooBar</classname>
        となります。このクラスには、最低限ヘルパー名と同じ名前 (camelCase 形式にしたもの)
        のメソッド <methodname>fooBar()</methodname> が含まれていなければなりません。
    </para>

    <note>
        <title>大文字小文字の扱い</title>
        <para>
            ヘルパー名は常に camelCase 形式となります。
            つまり、最初は常に小文字となります。
            クラス名は MixedCase 形式ですが、実際に実行されるメソッドは
            camelCase 形式となります。
        </para>
    </note>

    <note>
        <title>デフォルトのヘルパーのパス</title>

        <para>
            デフォルトのヘルパーのパスは常に Zend Framework
            のビューヘルパーのパス、すなわち 'Zend/View/Helper/' となります。
            <methodname>setHelperPath()</methodname> をコールして既存のパスを上書きしても、
            このパスだけは残ります。これにより、
            デフォルトのヘルパーは常に動作することが保証されます。
        </para>
    </note>

    <para>
        ビュースクリプト内でヘルパーを使用するには、
        <code>$this->helperName()</code> をコールします。これをコールすると、裏側では
        <classname>Zend_View</classname> が <classname>Zend_View_Helper_HelperName</classname> クラスを読み込み、
        そのクラスのインスタンスを作成して <methodname>helperName()</methodname> メソッドをコールします。
        オブジェクトのインスタンスは <classname>Zend_View</classname> インスタンスの中に残り続け、
        後で <code>$this->helperName()</code> がコールされたときには再利用されます。
    </para>

    <sect2 id="zend.view.helpers.initial">
        <title>付属のヘルパー</title>

        <para>
            <classname>Zend_View</classname> には、はじめからいくつかのヘルパークラスが付属しています。
            これらのほとんどはフォーム要素の生成に関するもので、
            適切なエスケープ処理を自動的に行います。
            さらに、ルートにもとづいた <acronym>URL</acronym> と HTML の一覧を作成したり、
            変数を宣言したりするものもあります。
            現在付属しているヘルパーは、次のとおりです。
        </para>

        <itemizedlist>

            <listitem><para>
                <code>declareVars():</code>
                <methodname>strictVars()</methodname> を使用する際に同時に使用します。
                このヘルパーを使用すると、テンプレート変数を宣言できます。
                この変数は、すでにビュースクリプトで設定されているものでもいないものでもかまいません。
                また、同時にデフォルト値も設定します。
                このメソッドへの引数として配列を渡すとデフォルト値を設定します。
                それ以外の場合は、もしその変数が存在しない場合は空文字列を設定します。
            </para></listitem>

            <listitem><para>
                <code>fieldset($name, $content, $attribs):</code>
                <acronym>XHTML</acronym> の fieldset を作成します。<varname>$attribs</varname> に
                'legend' というキーが含まれる場合、その値をフィールドセットの説明として使用します。
                フィールドセットで囲む内容は、このヘルパーに渡した
                <varname>$content</varname> です。
            </para></listitem>

            <listitem><para>
                <code>form($name, $attribs, $content):</code>
                <acronym>XHTML</acronym> の form を作成します。すべての <varname>$attribs</varname>
                はエスケープされ、form タグの <acronym>XHTML</acronym> 属性としてレンダリングされます。
                <varname>$content</varname> が存在してその値が false 以外の場合は、
                その内容がフォームの開始タグと終了タグの間にレンダリングされます。
                <varname>$content</varname> が false (デフォルト) の場合は、
                フォームの開始タグのみを作成します。
            </para></listitem>

            <listitem><para>
                <code>formButton($name, $value, $attribs):</code> &lt;button /&gt; 要素を作成します。
            </para></listitem>

            <listitem>
                <para>
                    <code>formCheckbox($name, $value, $attribs,
                        $options):</code>
                    &lt;input type="checkbox" /&gt; 要素を作成します。
                </para>

                <para>
                    デフォルトでは、$value を指定せず $options
                    が存在しなかった場合は、未チェックの値として '0'
                    そしてチェック状態の値として '1' を使用します。
                    $value が渡されたけれど $options が存在しなかった場合は、
                    渡された値をチェック状態の値とみなします。
                </para>

                <para>
                    $options は配列でなければなりません。
                    数値添字形式の配列の場合は、最初の要素がチェック状態の値となり、
                    その次の要素が未チェック状態の値となります。
                    3 番目以降の要素の内容は無視されます。
                    キー 'checked' および 'unChecked' を持つ連想配列を指定することもできます。
                </para>

                <para>
                    $options を渡した場合は、$value
                    が「チェック状態の値」と一致した場合にその要素がチェック状態だとみなされます。
                    チェック状態あるいは未チェック状態は、
                    属性 'checked' に boolean 値を渡して指定することもできます。
                </para>

                <para>
                    これらの内容を簡単にまとめた例を示します。
                </para>

                <programlisting language="php"><![CDATA[
// '1' および '0' でチェック状態と未チェック状態を表します。これはチェックされていません
echo $this->formCheckbox('foo');

// '1' および '0' でチェック状態と未チェック状態を表します。これはチェックされています
echo $this->formCheckbox('foo', null, array('checked' => true));

// 'bar' および '0' でチェック状態と未チェック状態を表します。これはチェックされていません
echo $this->formCheckbox('foo', 'bar');

// 'bar' および '0' でチェック状態と未チェック状態を表します。これはチェックされています
echo $this->formCheckbox('foo', 'bar', array('checked' => true));

// 'bar' および 'baz' でチェック状態と未チェック状態を表します。これはチェックされていません
echo $this->formCheckbox('foo', null, null, array('bar', 'baz'));

// 'bar' および 'baz' でチェック状態と未チェック状態を表します。これはチェックされていません
echo $this->formCheckbox('foo', null, null, array(
    'checked' => 'bar',
    'unChecked' => 'baz'
));

// 'bar' および 'baz' でチェック状態と未チェック状態を表します。これはチェックされています
echo $this->formCheckbox('foo', 'bar', null, array('bar', 'baz'));
echo $this->formCheckbox('foo',
                         null,
                         array('checked' => true),
                         array('bar', 'baz'));

// 'bar' および 'baz' でチェック状態と未チェック状態を表します。これはチェックされていません
echo $this->formCheckbox('foo', 'baz', null, array('bar', 'baz'));
echo $this->formCheckbox('foo',
                         null,
                         array('checked' => false),
                         array('bar', 'baz'));
]]></programlisting>

                <para>
                    どの場合についても、マークアップの先頭に hidden
                    要素を追加してそこに「未チェック状態」を表す値を保持します。
                    そうすることで、仮に未チェック状態であったとしても
                    フォームから何らかの値が返されるようになるのです。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>formErrors($errors, $options):</code>
                    エラーの表示用に、<acronym>XHTML</acronym> の順序なしリストを作成します。
                    <varname>$errors</varname> は、文字列あるいは文字列の配列となります。
                    <varname>$options</varname> は、リストの開始タグの属性として設定したい内容です。
                </para>

                <para>
                    エラー出力の開始時、終了時、そして各エラーの区切りとして使用する
                    コンテンツを指定することもできます。
                    そのためにはヘルパーのこれらのメソッドをコールします。
                </para>

                <itemizedlist>
                    <listitem><para>
                            <methodname>setElementStart($string)</methodname>;
                            デフォルトは '&lt;ul class="errors"%s"&gt;&lt;li&gt;'
                            で、%s の部分には <varname>$options</varname>
                            で指定した属性が入ります。
                    </para></listitem>

                    <listitem><para>
                            <methodname>setElementSeparator($string)</methodname>;
                            デフォルトは '&lt;/li&gt;&lt;li&gt;' です。
                    </para></listitem>

                    <listitem><para>
                            <methodname>setElementEnd($string)</methodname>;
                            デフォルトは '&lt;/li&gt;&lt;/ul&gt;' です。
                    </para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>
                <code>formFile($name, $attribs):</code>
                type="file" /&gt; 要素を作成します。
            </para></listitem>

            <listitem><para>
                <code>formHidden($name, $value, $attribs):</code> &lt;input
                type="hidden" /&gt; 要素を作成します。
            </para></listitem>

            <listitem><para>
                <code>formLabel($name, $value, $attribs):</code>
                &lt;label&gt; 要素を作成します。<code>for</code> 属性の値は
                <varname>$name</varname> に、そしてラベルのテキストは
                <varname>$value</varname> になります。
                <varname>attribs</varname> に <code>disable</code>
                を渡すと、結果を何も返しません。
            </para></listitem>

            <listitem><para>
                <code>formMultiCheckbox($name, $value, $attribs, $options,
                    $listsep):</code> チェックボックスのリストを作成します。
                <varname>$options</varname> は連想配列で、任意の深さにできます。
                <varname>$value</varname> は単一の値か複数の値の配列で、これが
                <varname>$options</varname> 配列のキーにマッチします。
                <varname>$listsep</varname> は、デフォルトでは HTML の改行
                ("&lt;br /&gt;") です。デフォルトでは、
                この要素は配列として扱われます。
                つまり、すべてのチェックボックスは同じ名前となり、
                入力内容は配列形式で送信されます。
            </para></listitem>

            <listitem><para>
                <code>formPassword($name, $value, $attribs):</code> &lt;input
                type="password" /&gt; 要素を作成します。
            </para></listitem>

            <listitem><para>
                <code>formRadio($name, $value, $attribs, $options):</code>
                一連の &lt;input type="radio" /&gt; 要素を、
                $options の要素ごとに作成します。$options は、
                ラジオボタンの値をキー、ラベルを値とする配列となります。
                $value はラジオボタンの初期選択状態を設定します。
            </para></listitem>

            <listitem><para>
                <code>formReset($name, $value, $attribs):</code> &lt;input
                type="reset" /&gt; 要素を作成します。
            </para></listitem>

            <listitem><para>
                <code>formSelect($name, $value, $attribs, $options):</code>
                &lt;select&gt;...&lt;/select&gt; ブロックを作成します。
                $options の要素ごとに &lt;option&gt; を作成します。
                $options は、選択肢の値をキー、
                ラベルを値とする配列となります。$value
                は初期選択状態を設定します。
            </para></listitem>

            <listitem><para>
                <code>formSubmit($name, $value, $attribs):</code> &lt;input
                type="submit" /&gt; 要素を作成します。
            </para></listitem>

            <listitem><para>
                <code>formText($name, $value, $attribs):</code> &lt;input
                type="text" /&gt; 要素を作成します。
            </para></listitem>

            <listitem><para>
                <code>formTextarea($name, $value, $attribs):</code>
                &lt;textarea&gt;...&lt;/textarea&gt; ブロックを作成します。
            </para></listitem>

            <listitem><para>
                <code>url($urlOptions, $name, $reset):</code>
                指定したルートにもとづく <acronym>URL</acronym> 文字列を作成します。
                <varname>$urlOptions</varname> は、そのルートで使用する
                キー/値 のペアの配列となります。
            </para></listitem>

            <listitem><para>
                <code>htmlList($items, $ordered, $attribs, $escape):</code>
                <varname>$items</varname> で渡した内容をもとに
                順序つきリストあるいは順序なしリストを作成します。
                <varname>$items</varname> が多次元配列の場合は、入れ子状のリストとなります。
                <varname>$escape</varname> フラグを true (デフォルト) にすると、
                各項目はビューオブジェクトに登録されているエスケープ方式でエスケープされます。
                リスト内でマークアップを行いたい場合は false を渡します。
            </para></listitem>

        </itemizedlist>

        <para>
            これらをビュースクリプト内で使用するのはとても簡単です。
            以下に例を示します。ただ単に、ヘルパーをコールするだけでよいことに注意しましょう。
            読み込みやインスタンス作成は、必要に応じて自動的に行われます。
        </para>

        <programlisting language="php"><![CDATA[
// ビュースクリプト内では、$this は Zend_View のインスタンスを指します。
//
// select の選択肢を、変数 $countries に
// array('us' => 'United States', 'il' => 'Israel', 'de' => 'Germany')
// として設定済みであることにします。
?>
<form action="action.php" method="post">
    <p><label>メールアドレス:
<?php echo $this->formText('email', 'you@example.com', array('size' => 32)) ?>
    </label></p>
    <p><label>国:
<?php echo $this->formSelect('country', 'us', null, $this->countries) ?>
    </label></p>
    <p><label>メールを受け取りますか?
<?php echo $this->formCheckbox('opt_in', 'yes', null, array('yes', 'no')) ?>
    </label></p>
</form>
]]></programlisting>

        <para>
            ビュースクリプトの出力結果は、次のようになります。
        </para>

        <programlisting language="php"><![CDATA[
<form action="action.php" method="post">
    <p><label>メールアドレス:
        <input type="text" name="email" value="you@example.com" size="32" />
    </label></p>
    <p><label>国:
        <select name="country">
            <option value="us" selected="selected">United States</option>
            <option value="il">Israel</option>
            <option value="de">Germany</option>
        </select>
    </label></p>
    <p><label>メールを受け取りますか?
        <input type="hidden" name="opt_in" value="no" />
        <input type="checkbox" name="opt_in" value="yes" checked="checked" />
    </label></p>
</form>
]]></programlisting>

        <xi:include href="Zend_View-Helpers-Action.xml" />
        <xi:include href="Zend_View-Helpers-BaseUrl.xml" />
        <xi:include href="Zend_View-Helpers-Cycle.xml" />
        <xi:include href="Zend_View-Helpers-Partial.xml" />
        <xi:include href="Zend_View-Helpers-Placeholder.xml" />
        <xi:include href="Zend_View-Helpers-Doctype.xml" />
        <xi:include href="Zend_View-Helpers-HeadLink.xml" />
        <xi:include href="Zend_View-Helpers-HeadMeta.xml" />
        <xi:include href="Zend_View-Helpers-HeadScript.xml" />
        <xi:include href="Zend_View-Helpers-HeadStyle.xml" />
        <xi:include href="Zend_View-Helpers-HeadTitle.xml" />
        <xi:include href="Zend_View-Helpers-HtmlObject.xml" />
        <xi:include href="Zend_View-Helpers-InlineScript.xml" />
        <xi:include href="Zend_View-Helpers-Json.xml" />
        <xi:include href="Zend_View-Helpers-Navigation.xml">
            <xi:fallback><xi:include href="../../en/module_specs/Zend_View-Helpers-Navigation.xml" /></xi:fallback>
        </xi:include>
        <xi:include href="Zend_View-Helpers-Translate.xml" />
    </sect2>

    <sect2 id="zend.view.helpers.paths">
        <title>ヘルパーのパス</title>

        <para>
            ビュースクリプトと同様、
            <classname>Zend_View</classname> がヘルパークラスを探すパスをコントローラから積み重ねて指定できます。
            デフォルトでは、<classname>Zend_View</classname> は "Zend/View/Helper/*" からヘルパークラスを探します。
            <classname>Zend_View</classname> に別の場所を探すように指定するには
            <methodname>setHelperPath()</methodname> および <methodname>addHelperPath()</methodname> メソッドを使用します。
            さらに、クラスプレフィックスを指定することもできます。
            これにより、ヘルパークラスに名前空間を設定できるようになります。
            デフォルトでクラスプレフィックスを指定しなかった場合は、
            'Zend_View_Helper_' であると見なされます。
        </para>

        <programlisting language="php"><![CDATA[
$view = new Zend_View();

// パスを /path/to/more/helpers 、プレフィックスを 'My_View_Helper' と設定します
$view->setHelperPath('/path/to/more/helpers', 'My_View_Helper');
]]></programlisting>

        <para>
            <methodname>addHelperPath()</methodname> メソッドを使用すると、検索パスを「積み重ねる」
            ことができます。これを使用すると、<classname>Zend_View</classname>
            は一番最後に追加されたパスからヘルパークラスを探し始めます。
            これにより、付属しているヘルパーの内容を上書きしたり、
            新しいヘルパーを追加したりすることができるようになります。
        </para>

        <programlisting language="php"><![CDATA[
$view = new Zend_View();
// /path/to/some/helpers をクラスプレフィックス 'My_View_Helper' で追加します
$view->addHelperPath('/path/to/some/helpers', 'My_View_Helper');
// /other/path/to/helpers をクラスプレフィックス 'Your_View_Helper' で追加します
$view->addHelperPath('/other/path/to/helpers', 'Your_View_Helper');

// $this->helperName() をコールすると、Zend_View は
// まず最初に "/path/to/some/helpers/HelperName" で
// "Your_View_Helper_HelperName" という名前のクラスを探し、
// 次に "/other/path/to/helpers/HelperName.php" で
// "My_View_Helper_HelperName" という名前のクラスを探し、
// そして最後に "Zend/View/Helpers/HelperName.php" で
// "Zend_View_Helper_HelperName" という名前のクラスを探します。
]]></programlisting>

    </sect2>

    <sect2 id="zend.view.helpers.custom">
        <title>独自のヘルパーを書く</title>

        <para>
            独自のヘルパーを書くのは簡単です。以下の規則に従ってください。
        </para>

        <itemizedlist>

            <listitem><para>
                絶対条件というわけではありませんが、ヘルパーを作成する際には
                <classname>Zend_View_Helper_Interface</classname> を実装するか
                <classname>Zend_View_Helper_Abstract</classname> を継承することを推奨します。
                1.6.0 以降、これらには <methodname>setView()</methodname> メソッドが定義されています。
                しかし、将来のリリースでは Strategy パターンを実装することを検討しており、
                以下に示す命名規約の多くを単純化する予定です。
                今のうちにこのようにしておくと、
                将来のバージョンでもあなたの書いたコードがそのまま動くようになるでしょう。
            </para></listitem>

            <listitem><para>
                クラス名は、少なくとも最後はヘルパーの名前と同じである必要があります。
                MixedCaps 方式を使用します。たとえば
                "specialPurpose" という名前のヘルパーを作成した場合は、そのクラス名には
                最低限 "SpecialPurpose" が含まれている必要があります。
                このクラス名にプレフィックスを指定できます。
                プレフィックスの一部に 'View_Helper' を含めることを推奨します。たとえば
                "My_View_Helper_SpecialPurpose" のようになります
                (<methodname>addHelperPath()</methodname> や
                <methodname>setHelperPath()</methodname> にはプレフィックスを指定する必要があります。
                最後のアンダースコアは含めても含めなくてもかまいません)。
            </para></listitem>

            <listitem><para>
                クラスは、ヘルパーと同じ名前の public メソッドを持っている必要があります。
                テンプレートが "$this->specialPurpose()" をコールした際に、
                このメソッドがコールされます。"specialPurpose" ヘルパーの例では、
                "public function specialPurpose()" というメソッドが必要です。
            </para></listitem>

            <listitem><para>
                一般に、クラスでは echo や print その他の出力を行ってはいけません。
                その代わりに、print あるいは echo される内容を返します。
                返り値は、適切にエスケープしなければなりません。
            </para></listitem>

            <listitem><para>
                クラスは、ヘルパークラスと同じ名前のファイルに作成しなければなりません。
                再び "specialPurpose" ヘルパーを例にとると、ファイル名は
                "SpecialPurpose.php" でなければなりません。
            </para></listitem>
        </itemizedlist>

        <para>
            指定したヘルパーパスのどこかにヘルパークラスのファイルを配置すると、
            <classname>Zend_View</classname> は自動的にそれを読み込んでインスタンスを作成し、
            必要に応じて実行します。
        </para>

        <para>
            <code>SpecialPurpose</code> ヘルパーのコードの例を示します。
        </para>

        <programlisting language="php"><![CDATA[
class My_View_Helper_SpecialPurpose extends Zend_View_Helper_Abstract
{
    protected $_count = 0;
    public function specialPurpose()
    {
        $this->_count++;
        $output = "'The Jerk' を {$this->_count} 回見ました。";
        return htmlspecialchars($output);
    }
}
]]></programlisting>

        <para>
            そして、ビュースクリプト内で <code>SpecialPurpose</code>
            ヘルパーを必要なだけコールします。いちどインスタンスが作成された後は、
            <classname>Zend_View</classname> インスタンスの中でそれが持続します。
        </para>

        <programlisting language="php"><![CDATA[
// ビュースクリプト内では、$this は Zend_View インスタンスを指すことを覚えておきましょう。
echo $this->specialPurpose();
echo $this->specialPurpose();
echo $this->specialPurpose();
]]></programlisting>

        <para>
            出力結果は、次のようになります。
        </para>
        <programlisting language="php"><![CDATA[
'The Jerk' を 1 回見ました。
'The Jerk' を 2 回見ました。
'The Jerk' を 3 回見ました。
]]></programlisting>

        <para>
            時には <classname>Zend_View</classname> オブジェクトを使用したくなることもあるでしょう。
            たとえば登録されているエンコーディングを使用する必要があったり、
            ヘルパー内で別のビュースクリプトをレンダリングしたくなったりといった場合です。
            ビューオブジェクトにアクセスするには、ヘルパークラス内で次のような
            <methodname>setView($view)</methodname> メソッドを定義しなければなりません。
        </para>

        <programlisting language="php"><![CDATA[
class My_View_Helper_ScriptPath
{
    public $view;

    public function setView(Zend_View_Interface $view)
    {
        $this->view = $view;
    }

    public function scriptPath($script)
    {
        return $this->view->getScriptPath($script);
    }
}
]]></programlisting>

        <para>
            ヘルパークラスで <methodname>setView()</methodname> メソッドを定義しておくと、
            最初にインスタンスが作成される際に自動的にこのメソッドがコールされ、
            現在のビューオブジェクトが引数として渡されます。
            渡されたオブジェクトをクラス内でどのように管理するかは特に決まっていません。
            お好みの方法で管理してください。
        </para>

        <para>
            <classname>Zend_View_Helper_Abstract</classname> を継承する場合は、
            このメソッドはすでに定義済みであるため定義する必要はありません。
        </para>
    </sect2>

    <!-- TODO : to be translated -->
    <sect2 id="zend.view.helpers.registering-concrete">
        <title>Registering Concrete Helpers</title>

        <para>
            Sometimes it is convenient to instantiate a view helper, and then register it with the
            view. As of version 1.10.0, this is now possible using the
            <methodname>registerHelper()</methodname> method, which expects two arguments: the
            helper object, and the name by which it will be registered.
        </para>

        <programlisting language="php"><![CDATA[
$helper = new My_Helper_Foo();
// ...do some configuration or dependency injection...

$view->registerHelper($helper, 'foo');
]]></programlisting>

        <para>
            If the helper has a <methodname>setView()</methodname> method, the view object will call
            this and inject itself into the helper on registration.
        </para>

        <note>
            <title>Helper name should match a method</title>

            <para>
                The second argument to <methodname>registerHelper()</methodname> is the name of the
                helper. A corresponding method name should exist in the helper; otherwise,
                <classname>Zend_View</classname> will call a non-existent method when invoking the
                helper, raising a fatal PHP error.
            </para>
        </note>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->