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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect3 id="zend.view.helpers.initial.partial">
    <title>Partial ヘルパー</title>

    <para>
        <classname>Partial</classname> ビューヘルパーは、
        指定したテンプレートを自分自身のスコープ内でレンダリングします。
        主な使い道は、
        再利用可能な部分テンプレートを変数名の競合を気にせずに使うというものです。
        さらに、特定のモジュールから部分ビュースクリプトを指定できるようになります。
    </para>

    <para>
        <classname>Partial</classname> と兄弟関係にある <classname>PartialLoop</classname>
        ビューヘルパーは、反復処理可能なデータを渡して
        その各要素に対してレンダリングを行うものです。
    </para>

    <note>
        <title>PartialLoop カウンタ</title>
        <para>
            <classname>PartialLoop</classname> ビューヘルパーは、変数を
            <emphasis>partialCounter</emphasis> というビューに代入します。
            これは、配列の現在の位置をビュースクリプトに渡します。
            これを利用すると、たとえばテーブルの行の色を一行おきに入れ替えるなどが簡単にできます。
        </para>

    </note>

    <example id="zend.view.helpers.initial.partial.usage">
        <title>Partial の基本的な使用法</title>

        <para>
            partial の基本的な使用法は、
            自分自身のビューのスコープで部分テンプレートをレンダリングすることです。
            次のようなスクリプトを考えてみましょう。
        </para>

        <programlisting language="php"><![CDATA[
<?php // partial.phtml ?>
<ul>
    <li>From: <?php echo $this->escape($this->from) ?></li>
    <li>Subject: <?php echo $this->escape($this->subject) ?></li>
</ul>
]]></programlisting>

        <para>
            これを、ビュースクリプトから次のようにコールします。
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->partial('partial.phtml', array(
    'from' => 'Team Framework',
    'subject' => 'view partials')); ?>
]]></programlisting>

        <para>
            レンダリングした結果は、このようになります。
        </para>

        <programlisting language="html"><![CDATA[
<ul>
    <li>From: Team Framework</li>
    <li>Subject: view partials</li>
</ul>
]]></programlisting>

    </example>
        <note>
            <title>モデルは何?</title>

            <para>
                <classname>Partial</classname> ビューヘルパーが使用するモデルは、
                次のいずれかとなります。
            </para>

            <itemizedlist>
                <listitem><para>
                        <emphasis>配列</emphasis>。
                        配列を渡す場合は、連想配列形式でなければなりません。
                        そのキーと値のペアがビューに渡され、
                        キーが変数名となります。
                </para></listitem>

                <listitem><para>
                        <emphasis>toArray() メソッドを実装したオブジェクト</emphasis>。
                        そのオブジェクトの <methodname>toArray()</methodname>
                        メソッドを実行した結果が、ビューオブジェクトに渡されます。
                </para></listitem>

                <listitem><para>
                        <emphasis>標準のオブジェクト</emphasis>。
                        それ以外のオブジェクトについては、
                        <methodname>object_get_vars()</methodname> の結果
                        (そのオブジェクトのすべての public プロパティ)
                        がビューオブジェクトに渡されます。
                </para></listitem>
            </itemizedlist>

            <para>
                使用するモデルがオブジェクトである場合は、
                それを変数の配列などに変換するのではなく
                <emphasis>オブジェクトのまま</emphasis> 直接
                partial スクリプトに渡したくなるものでしょう。
                そのためには、しかるべきヘルパーでプロパティ
                'objectKey' を設定します。
            </para>

            <programlisting language="php"><![CDATA[
// オブジェクトを、変数 'model' として渡すよう通知します
$view->partial()->setObjectKey('model');

// partialLoop のオブジェクトを、最終的なビュースクリプト内で
// 変数 'model' として渡すよう通知します
$view->partialLoop()->setObjectKey('model');
]]></programlisting>

            <para>
                このテクニックが特に役立つのは、
                <classname>Zend_Db_Table_Rowset</classname> を
                <methodname>partialLoop()</methodname> に渡すような場合です。
                ビュースクリプト内で row オブジェクトに自由にアクセスでき、
                そのメソッド (親の値を取得したり従属行を取得したりなど)
                を自在に使えるようになります。
            </para>
        </note>

    <example id="zend.view.helpers.initial.partial.partialloop">
        <title>PartialLoop による反復処理可能なモデルのレンダリング</title>

        <para>
            一般に、ループ内で partial
            を使用して特定のコンテンツを繰り返しレンダリングしたくなることもあるでしょう。
            こうすることで、繰り返し表示される大量のコンテンツや複雑な表示ロジックを
            ひとつにまとめることができます。
            しかし、この方法はパフォーマンスに影響を及ぼします。
            というのも、partial ヘルパーをループ内で毎回実行することになるからです。
        </para>

        <para>
            <classname>PartialLoop</classname> ビューヘルパーは、
            この問題を解決します。これを使用すると、反復処理可能な内容
            (配列、あるいは <emphasis>Iterator</emphasis> を実装したオブジェクト)
            をモデルに渡せるようになります。
            そしてその各要素が partial スクリプトへモデルとして渡されます。
            各要素の内容は、<classname>Partial</classname>
            ビューヘルパーが受け付ける任意の形式のモデルとできます。
        </para>

        <para>
            次のような部分ビュースクリプトを考えます。
        </para>

        <programlisting language="php"><![CDATA[
<?php // partialLoop.phtml ?>
    <dt><?php echo $this->key ?></dt>
    <dd><?php echo $this->value ?></dd>
]]></programlisting>

        <para>
            そして "モデル" はこのようになります。
        </para>

        <programlisting language="php"><![CDATA[
$model = array(
    array('key' => 'Mammal', 'value' => 'Camel'),
    array('key' => 'Bird', 'value' => 'Penguin'),
    array('key' => 'Reptile', 'value' => 'Asp'),
    array('key' => 'Fish', 'value' => 'Flounder'),
);
]]></programlisting>

        <para>
            そして、ビュースクリプト内で
            <classname>PartialLoop</classname> ヘルパーを実行します。
        </para>

        <programlisting language="php"><![CDATA[
<dl>
<?php echo $this->partialLoop('partialLoop.phtml', $model) ?>
</dl>
]]></programlisting>

        <programlisting language="html"><![CDATA[
<dl>
    <dt>Mammal</dt>
    <dd>Camel</dd>

    <dt>Bird</dt>
    <dd>Penguin</dd>

    <dt>Reptile</dt>
    <dd>Asp</dd>

    <dt>Fish</dt>
    <dd>Flounder</dd>
</dl>
]]></programlisting>
    </example>

    <example id="zend.view.helpers.initial.partial.modules">
        <title>他のモジュールの Partial のレンダリング</title>

        <para>
            時には partial が別のモジュールに存在することもあるでしょう。
            そのモジュールの名前がわかっていれば、モジュール名を
            <methodname>partial()</methodname> あるいは <methodname>partialLoop()</methodname>
            の 2 番目の引数として渡し、
            <varname>$model</varname> を 3 番目の引数に移動させることができます。
        </para>

        <para>
            たとえば、'list' モジュールにある pager というスクリプトを使用したい場合は、
            次のようにします。
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->partial('pager.phtml', 'list', $pagerData) ?>
]]></programlisting>

        <para>
            こうすると、特定の partial を他のモジュールで再利用できるようになります。
            再利用可能な partial は、共有のビュースクリプトのパスに配置することをおすすめします。
        </para>
    </example>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->