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

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

    <para>
        <code>Placeholder</code> ビューヘルパーは、
        ビュースクリプトとビューのインスタンスとの間でコンテンツを永続化させます。
        それ以外の便利な機能としては次のようなものがあります。
        たとえばコンテンツの集約、ビュースクリプトの内容をキャプチャして後で再利用、
        コンテンツの前後へのテキストの追加 (そして集約したコンテンツ間のセパレータの追加)
        などです。
    </para>

    <example id="zend.view.helpers.initial.placeholder.usage">
        <title>プレースホルダの基本的な使用法</title>

        <para>
            プレースホルダの基本的な使用法は、ビューのデータを永続化させることです。
            <code>Placeholder</code> ヘルパーを起動する際にプレースホルダ名を指定し、
            ヘルパーはプレースホルダコンテナオブジェクトを返します。
            これを処理するなり、単純に echo するなりして使用できます。
        </para>

        <programlisting role="php"><![CDATA[
<?php $this->placeholder('foo')->set("Some text for later") ?>

<?php
    echo $this->placeholder('foo');
    // 出力は "Some text for later" となります
?>
]]>
        </programlisting>
    </example>

    <example id="zend.view.helpers.initial.placeholder.aggregation">
        <title>プレースホルダによるコンテンツの集約</title>

        <para>
            プレースホルダによるコンテンツの集約も、時には便利です。
            たとえば、ビュースクリプトで変数の配列を保持し、
            後で表示するためのメッセージを取得しておくと、
            それをどのようにレンダリングするかを後で決めることができます。
        </para>

        <para>
            <code>Placeholder</code> ビューヘルパーは、
            <code>ArrayObject</code> を継承したコンテナを使用します。
            これは、配列をより高機能に操作できるものです。
            さらに、コンテナに格納された内容をフォーマットするために
            さまざまなメソッドが用意されています。
        </para>

        <itemizedlist>
            <listitem><para>
                    <code>setPrefix($prefix)</code> は、
                    コンテンツの先頭に付加するテキストを設定します。
                    <code>getPrefix()</code> を使用すると、
                    その時点での設定内容を取得できます。
            </para></listitem>

            <listitem><para>
                    <code>setPostfix($prefix)</code> は、
                    コンテンツの末尾に付加するテキストを設定します。
                    <code>getPostfix()</code> を使用すると、
                    その時点での設定内容を取得できます。
            </para></listitem>

            <listitem><para>
                    <code>setSeparator($prefix)</code> は、
                    各コンテンツの間に挿入するテキストを設定します。
                    <code>getSeparator()</code> を使用すると、
                    その時点での設定内容を取得できます。
            </para></listitem>

            <listitem><para>
                    <code>setIndent($prefix)</code> は、
                    コンテンツの字下げ幅を設定します。
                    整数値を渡すと、渡された数のスペースを使用します。
                    文字列を渡すと、その文字列を使用します。
                    <code>getIndent()</code> を使用すると、
                    その時点での設定内容を取得できます。
            </para></listitem>
        </itemizedlist>

        <programlisting role="php"><![CDATA[
<!-- 最初のビュースクリプト -->
<?php $this->placeholder('foo')->exchangeArray($this->data) ?>
]]>
        </programlisting>

        <programlisting role="php"><![CDATA[
<!-- 後で使用するビュースクリプト -->
<?php
$this->placeholder('foo')->setPrefix("<ul>\n    <li>")
                         ->setSeparator("</li><li>\n")
                         ->setIndent(4)
                         ->setPostfix("</li></ul>\n");
?>

<?php
    echo $this->placeholder('foo');
    // 順序なしリストをきれいに字下げして出力します
?>
]]>
        </programlisting>

        <para>
            <code>Placeholder</code> コンテナオブジェクトは
            <code>ArrayObject</code> を継承しているので、
            単純にコンテナに格納するのではなく
            そのコンテナの特定のキーにコンテンツを格納するのも簡単です。
            キーへのアクセスは、オブジェクトのプロパティか配列のキーのいずれでも可能です。
        </para>

        <programlisting role="php"><![CDATA[
<?php $this->placeholder('foo')->bar = $this->data ?>
<?php echo $this->placeholder('foo')->bar ?>

<?php
$foo = $this->placeholder('foo');
echo $foo['bar'];
?>
]]>
        </programlisting>
    </example>

    <example id="zend.view.helpers.initial.placeholder.capture">
        <title>プレースホルダによるコンテンツのキャプチャ</title>

        <para>
            時には、プレースホルダの中身を
            テンプレートに渡しやすいようビュースクリプトで保持することもあるでしょう。
            <code>Placeholder</code> ビューヘルパーは、
            任意のコンテンツをキャプチャして後でレンダリングすることができます。
            そのために使用する API は次のようなものです。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>captureStart($type, $key)</code> は、
                    コンテンツのキャプチャを開始します。
                </para>

                <para>
                    <code>$type</code> は、
                    <code>Placeholder</code> の定数 <code>APPEND</code> あるいは
                    <code>SET</code> のいずれかとなります。<code>APPEND</code>
                    を指定すると、キャプチャされたコンテンツが
                    プレースホルダ内の現在のコンテンツの末尾に追加されます。
                    <code>SET</code> の場合は、
                    キャプチャされたコンテンツをそれ単体でプレースホルダの値として使用します
                    (それまでに登録されていたコンテンツを上書きします)。
                    デフォルトの <code>$type</code> は
                    <code>APPEND</code> です。
                </para>

                <para>
                    <code>$key</code> には、コンテンツのキャプチャ先として
                    プレースホルダのコンテナの特定のキーを指定することができます。
                </para>

                <para>
                    <code>captureStart()</code> は、
                    <code>captureEnd()</code> がコールされるまで他のキャプチャをロックします。
                    同一のプレースホルダコンテナでキャプチャをネストすることはできません。
                    しようとすると例外が発生します。
                </para>
            </listitem>

            <listitem><para>
                    <code>captureEnd()</code> は、
                    コンテンツのキャプチャを終了して、
                    <code>captureStart()</code>
                    がコールされたときの指定に応じてそれをコンテナに格納します。
            </para></listitem>
        </itemizedlist>

        <programlisting role="php"><![CDATA[
<!-- デフォルトのキャプチャは追記モードです -->
<?php $this->placeholder('foo')->captureStart();
foreach ($this->data as $datum): ?>
<div class="foo">
    <h2><?php echo $datum->title ?></h2>
    <p><?php echo $datum->content ?></p>
</div>
<?php endforeach; ?>
<?php $this->placeholder('foo')->captureEnd() ?>

<?php echo $this->placeholder('foo') ?>
]]>
        </programlisting>

        <programlisting role="php"><![CDATA[
<!-- 特定のキーにキャプチャします -->
<?php $this->placeholder('foo')->captureStart('SET', 'data');
foreach ($this->data as $datum): ?>
<div class="foo">
    <h2><?php echo $datum->title ?></h2>
    <p><?php echo $datum->content ?></p>
</div>
 <?php endforeach; ?>
<?php $this->placeholder('foo')->captureEnd() ?>

<?php echo $this->placeholder('foo')->data ?>
]]>
        </programlisting>
    </example>

    <sect4 id="zend.view.helpers.initial.placeholder.implementations">
        <title>プレースホルダの具象実装</title>

        <para>
            Zend Framework には、"具体的な"
            プレースホルダの実装が標準でいくつか含まれています。
            これらはみな一般的に用いられるもので、doctype
            やページのタイトル、&lt;head&gt; の要素群などを扱います。
            どのプレースホルダについても、
            引数なしでコールするとその要素自身を返します。
        </para>

        <para>
            各要素のドキュメントは、以下のリンク先で個別に扱います。
        </para>

        <itemizedlist>
            <listitem><para>
                    <link linkend="zend.view.helpers.initial.doctype">Doctype</link>
            </para></listitem>

            <listitem><para>
                    <link linkend="zend.view.helpers.initial.headlink">HeadLink</link>
            </para></listitem>

            <listitem><para>
                    <link linkend="zend.view.helpers.initial.headmeta">HeadMeta</link>
            </para></listitem>

            <listitem><para>
                    <link linkend="zend.view.helpers.initial.headscript">HeadScript</link>
            </para></listitem>

            <listitem><para>
                    <link linkend="zend.view.helpers.initial.headstyle">HeadStyle</link>
            </para></listitem>

            <listitem><para>
                    <link linkend="zend.view.helpers.initial.headtitle">HeadTitle</link>
            </para></listitem>

            <listitem><para>
                    <link linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>
            </para></listitem>
        </itemizedlist>
    </sect4>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->