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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24872 -->
<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>
        ビュースクリプト内でヘルパーを使用するには、
        <command>$this->helperName()</command> をコールします。これをコールすると、裏側では
        <classname>Zend_View</classname> が <classname>Zend_View_Helper_HelperName</classname> クラスを読み込み、
        そのクラスのインスタンスを作成して <methodname>helperName()</methodname> メソッドをコールします。
        オブジェクトのインスタンスは <classname>Zend_View</classname> インスタンスの中に残り続け、
        後で <command>$this->helperName()</command> がコールされたときには再利用されます。
    </para>

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

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

        <itemizedlist>

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

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

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

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

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

                <para>
                    デフォルトでは、$value を指定せず $options
                    が存在しなかった場合は、未チェックの値として '0'
                    そしてチェック状態の値として '1' を使用します。
                    $value が渡されたけれど $options が存在しなかった場合は、
                    渡された値をチェック状態の値とみなします。
                    チェックボックスをレンダリングする前に hidden 入力要素をレンダリングすることにより、
                    unchecked 値を実装します。
                </para>

                <para>
                    $options は配列でなければなりません。
                    数値添字形式の配列の場合は、最初の要素がチェック状態の値となり、
                    その次の要素が未チェック状態の値となります。
                    3 番目以降の要素の内容は無視されます。
                    キー 'checked' および 'unChecked' を持つ連想配列を指定することもできます。
                    unchecked 値に対して hidden フィールドをレンダリングすることを防ぐには、
                    キー 'disableHidden' を true に設定できます。
                </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>
                    <methodname>formErrors($errors, $options):</methodname>
                    エラーの表示用に、<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>
                <methodname>formFile($name, $attribs):</methodname>
                type="file" /&gt; 要素を作成します。
            </para></listitem>

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

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

<programlisting language="php"><![CDATA[
echo $this->formImage(
    'foo',
    'bar',
    array(
        'src' => 'images/button.png',
        'alt' => 'Button',
    )
);
// 出力: <input type="image" name="foo" id="foo" src="images/button.png" value="bar" alt="Button" />
]]></programlisting>
            </listitem>

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

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

<programlisting language="php"><![CDATA[
// リスト・セパレーター ($listsep) を使用:

echo '<ul><li>';
echo $view->formMultiCheckbox(
    'foo',
    2,
    array(
        'class' => 'baz',
    ),
    array(
        1 => 'One',
        2 => 'Two',
        3 => 'Three',
    ),
    "</li>\n<li>"
);
echo '</li></ul>';

/*
出力:
<ul>
    <li>
        <label for="foo-1">
            <input type="checkbox" name="foo[]" id="foo-1" value="1" class="baz" />One
        </label>
    </li>
    <li>
        <label for="foo-2">
            <input type="checkbox" name="foo[]" id="foo-2" value="2" checked="checked" class="baz" />Two
        </label>
    </li>
    <li>
        <label for="foo-3">
            <input type="checkbox" name="foo[]" id="foo-3" value="3" class="baz" />Three</label>
        </li>
    </ul>
*/

// ラベル要素に対してオプションを使用:
echo $this->formMultiCheckbox(
    'foo',
    2,
    array(
        'label_placement' => 'prepend',
        'label_class'     => 'baz',
    ),
    array(
        1 => 'One',
        2 => 'Two',
        3 => 'Three',
    )
);

/*
出力:
<label class="baz" for="foo-1">
    One<input type="checkbox" name="foo[]" id="foo-1" value="1" />
</label>
<br />
<label class="baz" for="foo-2">
    Two<input type="checkbox" name="foo[]" id="foo-2" value="2" checked="checked" />
</label>
<br />
<label class="baz" for="foo-3">
    Three<input type="checkbox" name="foo[]" id="foo-3" value="3" />
</label>
*/
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <methodname>formNote($name, $value = null)</methodname>:
                    単純なテキスト・ノートを作成。例えば、
                    <classname>Zend_Form</classname> オブジェクトの見出しに対する要素として。
                </para>

<programlisting language="php"><![CDATA[
echo $this->formNote(null, 'This is an example text.');
// 出力: This is an example text.
]]></programlisting>
            </listitem>

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

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

<programlisting language="php"><![CDATA[
// リスト・セパレーター ($listsep) を使用

echo '<ul><li>';
echo $this->formRadio(
    'foo',
    2,
    array(
        'class' => 'baz',
    ),
    array(
        1 => 'One',
        2 => 'Two',
        3 => 'Three',
    ),
    "</li>\n<li>"
);
echo '</li></ul>';

/*
出力:
<ul>
    <li>
        <label for="foo-1">
            <input type="radio" name="foo" id="foo-1" value="1" class="baz" />One
        </label>
    </li>
    <li>
        <label for="foo-2">
            <input type="radio" name="foo" id="foo-2" value="2" checked="checked" class="baz" />Two
        </label>
    </li>
    <li>
        <label for="foo-3">
            <input type="radio" name="foo" id="foo-3" value="3" class="baz" />Three
        </label>
    </li>
</ul>
*/

// ラベル要素に対してオプションを使用:

echo $this->formRadio(
    'foo',
    2,
    array(
        'label_placement' => 'prepend',
        'label_class'     => 'baz',
    ),
    array(
        1 => 'One',
        2 => 'Two',
        3 => 'Three',
    )
);

/*
出力:
<label class="baz" for="foo-1">
    One<input type="radio" name="foo" id="foo-1" value="1" />
</label>
<br />
<label class="baz" for="foo-2">
    Two<input type="radio" name="foo" id="foo-2" value="2" checked="checked" />
</label>
<br />
<label class="baz" for="foo-3">
    Three<input type="radio" name="foo" id="foo-3" value="3" />
</label>
*/
]]></programlisting>
            </listitem>

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

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

<programlisting language="php"><![CDATA[
// オプション・グループを使用:

echo $view->formSelect(
    'foo',
    2,
    array(
        'class' => 'baz',
    ),
    array(
        1     => 'One',
        'Two' => array(
            '2.1' => 'One',
            '2.2' => 'Two',
            '2.3' => 'Three',
        ),
        3     => 'Three',
    )
);

/*
出力:
<select name="foo" id="foo" class="baz">
    <option value="1" label="One">One</option>
    <optgroup id="foo-optgroup-Two" label="Two">
        <option value="2.1" label="One">One</option>
        <option value="2.2" label="Two">Two</option>
        <option value="2.3" label="Three">Three</option>
    </optgroup>
    <option value="3" label="Three">Three</option>
</select>
*/

// 'multiple' オプションの例その１:

echo $this->formSelect(
    'foo[]',
    2,
    null,
    array(
        1 => 'One',
        2 => 'Two',
        3 => 'Three',
    )
);

/*
出力:
<select name="foo[]" id="foo" multiple="multiple">
    <option value="1" label="One">One</option>
    <option value="2" label="Two" selected="selected">Two</option>
    <option value="3" label="Three">Three</option>
</select>
*/

// 'multiple' オプションの例その２:

echo $this->formSelect(
    'foo',
    array(
        1,
        2,
    ),
    array(
        'multiple' => true,
    ),
    array(
        1 => 'One',
        2 => 'Two',
        3 => 'Three',
    )
);

/*
出力:
<select name="foo[]" id="foo" multiple="multiple">
    <option value="1" label="One" selected="selected">One</option>
    <option value="2" label="Two" selected="selected">Two</option>
    <option value="3" label="Three">Three</option>
</select>
*/
]]></programlisting>
            </listitem>

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

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

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

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

<programlisting language="php"><![CDATA[
// オプション無しで使用: (現行のリクエスト: user/id/1)
echo $this->url();
// 出力: user/info/id/1

// URL オプションを設定:
echo $this->url(
    array('controller' => 'user', 'action' => 'info', 'username' => 'foobar')
);
// 出力: user/info/username/foobar

// ルートを使用:
$router->addRoute(
    'user',
    new Zend_Controller_Router_Route(
        'user/:username',
        array(
            'controller' => 'user',
            'action'     => 'info',
        )
    )
);

echo $this->url(array('name' => 'foobar'), 'user');
// 出力: user/foobar

// リセットを使用: (現行のリクエスト: user/id/1)
echo $this->url(array('controller' => 'user', 'action' => 'info'), null, false);
// 出力: user/info/id/1

echo $this->url(array('controller' => 'user', 'action' => 'info'), null, true);
// 出力: user/info

// エンコードを使用:
echo $this->url(
    array('controller' => 'user', 'action' => 'info', 'username' => 'John Doe'), null, true, false
);
// 出力: user/info/username/John Doe

echo $this->url(
    array('controller' => 'user', 'action' => 'info', 'username' => 'John Doe'), null, true, false
);
// 出力: user/info/username/John+Doe
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <methodname>serverUrl($requestUri = null)</methodname>:
                    現行のサーバーの URL、および任意でリクエスト URI を返すヘルパー。
                </para>

<programlisting language="php"><![CDATA[
// この例の現行のサーバー URL: http://www.example.com/foo.html

echo $this->serverUrl();
// 出力: http://www.example.com

echo $this->serverUrl(true);
// 出力: http://www.example.com/foo.html

echo $this->serverUrl('/foo/bar');
// 出力: http://www.example.com/foo/bar

echo $this->serverUrl()->getHost();
// 出力: www.example.com

echo $this->serverUrl()->getScheme();
// 出力: http

$this->serverUrl()->setHost('www.foo.com');
$this->serverUrl()->setScheme('https');
echo $this->serverUrl();
// 出力: https://www.foo.com
]]></programlisting>
            </listitem>

            <listitem><para>
                <methodname>htmlList($items, $ordered, $attribs, $escape):</methodname>
                <varname>$items</varname> で渡した内容をもとに
                順序つきリストあるいは順序なしリストを作成します。
                <varname>$items</varname> が多次元配列の場合は、入れ子状のリストとなります。
                <varname>$escape</varname> フラグを <constant>TRUE</constant> (既定値) にすると、
                各項目はビューオブジェクトに登録されているエスケープ方式でエスケープされます。
                リスト内でマークアップを行いたい場合は <constant>FALSE</constant> を渡します。
            </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-Currency.xml">
            <xi:fallback><xi:include href="../../en/module_specs/Zend_View-Helpers-Currency.xml" /></xi:fallback>
        </xi:include>
        <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-Gravatar.xml">
            <xi:fallback><xi:include href="../../en/module_specs/Zend_View-Helpers-Gravatar.xml" /></xi:fallback>
        </xi:include>
        <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-RenderToPlaceholder.xml">
            <xi:fallback><xi:include href="../../en/module_specs/Zend_View-Helpers-RenderToPlaceholder.xml" /></xi:fallback>
        </xi:include>
        <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" />
        <xi:include href="Zend_View-Helpers-UserAgent.xml">
            <xi:fallback><xi:include href="../../en/module_specs/Zend_View-Helpers-UserAgent.xml" /></xi:fallback>
        </xi:include>
    </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>
            <classname>SpecialPurpose</classname> ヘルパーのコードの例を示します。
        </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>
            そして、ビュースクリプト内で <classname>SpecialPurpose</classname>
            ヘルパーを必要なだけコールします。いちどインスタンスが作成された後は、
            <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>

    <sect2 id="zend.view.helpers.registering-concrete">
        <title>実在するヘルパーを登録</title>

        <para>
            時には、ビュー・ヘルパーをインスタンス化して、それからビューで登録すると便利です。
            バージョン 1.10.0 時点で、これは <methodname>registerHelper()</methodname> メソッドを用いると可能です。
            それは２つの引数を期待します。それは、ヘルパー・オブジェクトと登録される名前です。
        </para>

        <programlisting language="php"><![CDATA[
$helper = new My_Helper_Foo();
// ...何らかの構成または依存性注入を行います...

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

        <para>
            ヘルパーに <methodname>setView()</methodname> メソッドがあると、
            ビュー・オブジェクトはこれを呼び出して、登録時に自分自身をヘルパーに注入します。
        </para>

        <note>
            <title>ヘルパー名はメソッドと一致しなければいけません</title>

            <para>
                <methodname>registerHelper()</methodname> の２番目の引数はヘルパー名です。
                対応するメソッド名がヘルパー内に存在しなければいけません。
                さもなければ、ヘルパー起動時に <classname>Zend_View</classname> が存在しないメソッドを呼び出して
                致命的な <acronym>PHP</acronym> エラーを引き起こします。
            </para>
        </note>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->