repo_zf1/documentation/manual/ja/module_specs/Zend_Layout-Options.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.layout.options">
    <title>Zend_Layout の設定オプション</title>

    <para>
        <classname>Zend_Layout</classname> にはさまざまな設定オプションがあります。
        オプションを設定する方法には次のようなものがあります。
        まずアクセサメソッドをコールすること、
        次に配列や <classname>Zend_Config</classname> オブジェクトをコンストラクタあるいは
        <methodname>startMvc()</methodname> に渡すこと、
        オプションの配列を <methodname>setOptions()</methodname> に渡すこと、
        そして <classname>Zend_Config</classname> オブジェクトを <methodname>setConfig()</methodname>
        に渡すことです。
    </para>

    <itemizedlist>
        <listitem><para>
                <emphasis>layout</emphasis>:
                使用するレイアウト。現在のインフレクタを使用して名前を解決し、
                適切なレイアウトビュースクリプトを使用します。デフォルトでは、この値は
                'layout' で、'layout.phtml' に解決されます。
                アクセサは <methodname>setLayout()</methodname> と <methodname>getLayout()</methodname> です。
        </para></listitem>

        <listitem><para>
                <emphasis>layoutPath</emphasis>:
                レイアウトビュースクリプトの基底パス。
                アクセサは <methodname>setLayoutPath()</methodname> と
                <methodname>getLayoutPath()</methodname> です。
        </para></listitem>

        <listitem><para>
                <emphasis>contentKey</emphasis>:
                デフォルトのコンテンツに使用するレイアウト変数
                (<acronym>MVC</acronym> と組み合わせて使用する場合のみ)。
                デフォルト値は 'content' です。
                アクセサは <methodname>setContentKey()</methodname> と
                <methodname>getContentKey()</methodname> です。
        </para></listitem>

        <listitem><para>
                <emphasis>mvcSuccessfulActionOnly</emphasis>:
                <acronym>MVC</acronym> とともに使用します。このフラグを <constant>TRUE</constant> にすると、
                アクションが例外をスローした際にレイアウトをレンダリングしません
                (これにより、
                <link linkend="zend.controller.plugins.standard.errorhandler">ErrorHandler
                プラグイン</link> を使用している際の二重レンダリング問題を回避します)。
                デフォルトでは、このフラグは <constant>TRUE</constant> です。
                アクセサは <methodname>setMvcSuccessfulActionOnly()</methodname> と
                <methodname>getMvcSuccessfulActionOnly()</methodname> です。
        </para></listitem>

        <listitem><para>
                <emphasis>view</emphasis>:
                レンダリングの際に使用するビューオブジェクト。
                <acronym>MVC</acronym> と組み合わせて使用した場合、
                ビューオブジェクトを明示しなければ <classname>Zend_Layout</classname> は
                <link linkend="zend.controller.actionhelpers.viewrenderer">
                ViewRenderer</link>
                で登録されたビューオブジェクトを使用します。
                アクセサは <methodname>setView()</methodname> と
                <methodname>getView()</methodname> です。
        </para></listitem>

        <listitem><para>
                <emphasis>helperClass</emphasis>:
                <classname>Zend_Layout</classname> を <acronym>MVC</acronym>
                コンポーネントを組み合わせて使用する際のアクションヘルパークラス。
                デフォルトでは、これは
                <classname>Zend_Layout_Controller_Action_Helper_Layout</classname> です。
                アクセサは <methodname>setHelperClass()</methodname> と
                <methodname>getHelperClass()</methodname> です。
        </para></listitem>

        <listitem><para>
                <emphasis>pluginClass</emphasis>:
                <classname>Zend_Layout</classname> を <acronym>MVC</acronym>
                コンポーネントを組み合わせて使用する際のフロントコントローラプラグインクラス。
                デフォルトでは、これは
                <classname>Zend_Layout_Controller_Plugin_Layout</classname> です。
                アクセサは <methodname>setPluginClass()</methodname> と
                <methodname>getPluginClass()</methodname> です。
        </para></listitem>

        <listitem><para>
                <emphasis>inflector</emphasis>:
                レイアウト名をレイアウトビュースクリプトのパスに解決する際に使用するインフレクタ。
                詳細は <link
                    linkend="zend.layout.advanced.inflector">
                    <classname>Zend_Layout</classname> インフレクタのドキュメント
                    </link> を参照ください。
                アクセサは <methodname>setInflector()</methodname> と
                <methodname>getInflector()</methodname> です。
        </para></listitem>
    </itemizedlist>

    <note>
        <title>helperClass と pluginClass は startMvc() で渡す必要がある</title>

        <para>
            <property>helperClass</property> と
            <property>pluginClass</property> の設定を有効にするには、
            <methodname>startMvc()</methodname> のオプションで指定する必要があります。
            それ以降で指定しても効果はありません。
        </para>
    </note>

    <sect2 id="zend.layout.options.examples">
        <title>例</title>

        <para>
            以下の例では、次のような <code>$options</code>
            配列と <code>$config</code> オブジェクトを前提としています。
        </para>

        <programlisting language="php"><![CDATA[
$options = array(
    'layout'     => 'foo',
    'layoutPath' => '/path/to/layouts',
    'contentKey' => 'CONTENT',           // MVC を使わない場合は無視されます
);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
[layout]
layout = "foo"
layoutPath = "/path/to/layouts"
contentKey = "CONTENT"
*/
$config = new Zend_Config_Ini('/path/to/layout.ini', 'layout');
]]></programlisting>

        <example id="zend.layout.options.examples.constructor">
            <title>オプションをコンストラクタあるいは startMvc() で渡す</title>

            <para>
                コンストラクタおよび静的メソッド <methodname>startMvc()</methodname>
                は、どちらもオプションの配列か
                <classname>Zend_Config</classname> オブジェクトを受け取ることができます。
                受け取った内容をもとに
                <classname>Zend_Layout</classname> インスタンスの設定を行います。
            </para>

            <para>
                まず、配列を渡す方法を見てみましょう。
            </para>

            <programlisting language="php"><![CDATA[
// コンストラクタを使用します
$layout = new Zend_Layout($options);

// startMvc() を使用します
$layout = Zend_Layout::startMvc($options);
]]></programlisting>

            <para>
                次に config オブジェクトを使用する方法です。
            </para>

            <programlisting language="php"><![CDATA[
$config = new Zend_Config_Ini('/path/to/layout.ini', 'layout');

// コンストラクタを使用します
$layout = new Zend_Layout($config);

// startMvc() を使用します
$layout = Zend_Layout::startMvc($config);
]]></programlisting>

            <para>
                基本的に、これは <classname>Zend_Layout</classname>
                インスタンスをカスタマイズするためのもっとも簡単な方法となります。
            </para>
        </example>

        <example id="zend.layout.options.examples.setoptionsconfig">
            <title>setOption() および setConfig() の使用</title>

            <para>
                時には、インスタンスを作成した後で <classname>Zend_Layout</classname>
                を設定したくなることもあるでしょう。そんな場合は
                <methodname>setOptions()</methodname> や <methodname>setConfig()</methodname>
                を使用します。
            </para>

            <programlisting language="php"><![CDATA[
// オプションの配列を使用します
$layout->setOptions($options);

// Zend_Config オブジェクトを使用します
$layout->setConfig($options);
]]></programlisting>

            <para>
                しかし、ここで注意すべき点があります。
                <property>pluginClass</property> や <property>helperClass</property>
                のように、オプションによってはこのメソッドで指定しても無意味なものもあるのです。
                これらは、コンストラクタあるいは <methodname>startMvc()</methodname>
                メソッドで指定する必要があります。
            </para>
        </example>

        <example id="zend.layout.options.examples.accessors">
            <title>アクセサの使用</title>

            <para>
                最後に、<classname>Zend_Layout</classname>
                のインスタンスをアクセサで設定することもできます。
                すべてのアクセサは流れるようなインターフェイスを実装しており、
                メソッドコールを連結して行えます。
            </para>

            <programlisting language="php"><![CDATA[
$layout->setLayout('foo')
       ->setLayoutPath('/path/to/layouts')
       ->setContentKey('CONTENT');
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->