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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.view.helpers.initial.partial">
    <title>Partial Helper</title>

    <para>
        The <classname>Partial</classname> view helper is used to render a specified
        template within its own variable scope. The primary use is for reusable
        template fragments with which you do not need to worry about variable
        name clashes. Additionally, they allow you to specify partial view
        scripts from specific modules.
    </para>

    <para>
        A sibling to the <classname>Partial</classname>, the <classname>PartialLoop</classname> view
        helper allows you to pass iterable data, and render a partial for each
        item.
    </para>

    <note>
        <title>PartialLoop Counter</title>

        <para>
            The <classname>PartialLoop</classname> view helper assigns a variable to the view named
            <emphasis>partialCounter</emphasis> which passes the current position of the array to
            the view script. This provides an easy way to have alternating colors on table rows for
            example.
        </para>
    </note>

    <example id="zend.view.helpers.initial.partial.usage">
        <title>Basic Usage of Partials</title>

        <para>
            Basic usage of partials is to render a template fragment in its own
            view scope. Consider the following partial script:
        </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>
            You would then call it from your view script using the following:
        </para>

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

        <para>
            Which would then render:
        </para>

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

    <note>
        <title>What is a model?</title>

        <para>
            A model used with the <classname>Partial</classname> view helper can be
            one of the following:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Array</emphasis>. If an array is passed, it
                    should be associative, as its key/value pairs are
                    assigned to the view with keys as view variables.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Object implementing toArray() method</emphasis>. If an object is
                    passed an has a <methodname>toArray()</methodname> method, the results of
                    <methodname>toArray()</methodname> will be assigned to the view
                    object as view variables.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Standard object</emphasis>. Any other object
                    will assign the results of
                    <methodname>object_get_vars()</methodname> (essentially all public
                    properties of the object) to the view object.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            If your model is an object, you may want to have it passed
            <emphasis>as an object</emphasis> to the partial script, instead
            of serializing it to an array of variables. You can do this by
            setting the 'objectKey' property of the appropriate helper:
        </para>

        <programlisting language="php"><![CDATA[
// Tell partial to pass objects as 'model' variable
$view->partial()->setObjectKey('model');

// Tell partial to pass objects from partialLoop as 'model' variable
// in final partial view script:
$view->partialLoop()->setObjectKey('model');
]]></programlisting>

        <para>
            This technique is particularly useful when passing
            <classname>Zend_Db_Table_Rowset</classname>s to
            <methodname>partialLoop()</methodname>, as you then have full access to your
            row objects within the view scripts, allowing you to call
            methods on them (such as retrieving values from parent or
            dependent rows).
        </para>
    </note>

    <example id="zend.view.helpers.initial.partial.partialloop">
        <title>Using PartialLoop to Render Iterable Models</title>

        <para>
            Typically, you'll want to use partials in a loop, to render the same
            content fragment many times; this way you can put large blocks of
            repeated content or complex display logic into a single location.
            However this has a performance impact, as the partial helper needs
            to be invoked once for each iteration.
        </para>

        <para>
            The <classname>PartialLoop</classname> view helper helps solve this issue. It
            allows you to pass an iterable item (array or object implementing
            <emphasis>Iterator</emphasis>) as the model. It then iterates over this,
            passing, the items to the partial script as the model. Items in the
            iterator may be any model the <classname>Partial</classname> view helper
            allows.
        </para>

        <para>
            Let's assume the following partial view script:
        </para>

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

        <para>
            And the following "model":
        </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>
            In your view script, you could then invoke the
            <classname>PartialLoop</classname> helper:
        </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>Rendering Partials in Other Modules</title>

        <para>
            Sometime a partial will exist in a different module. If you know the
            name of the module, you can pass it as the second argument to either
            <methodname>partial()</methodname> or <methodname>partialLoop()</methodname>, moving the
            <varname>$model</varname> argument to third position.
        </para>

        <para>
            For instance, if there's a pager partial you wish to use that's in
            the 'list' module, you could grab it as follows:
        </para>

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

        <para>
            In this way, you can re-use partials created specifically for other
            modules. That said, it's likely a better practice to put re-usable
            partials in shared view script paths.
        </para>
    </example>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->