<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="learning.layout.usage">
    <title>Zend_Layout verwenden</title>

    <para>
        Die grundsätzliche Verwendung von <classname>Zend_Layout</classname> ist recht trivial.
        Angenommen man verwendet bereits <classname>Zend_Application</classname>, dann kann man
        einfach ein paar Konfigurations Optionen übergeben und ein Layout View Skript erstellen.
    </para>

    <sect2 id="learning.layout.usage.configuration">
        <title>Layout Konfiguration</title>

        <para>
            Der empfohlene Ort für Layouts ist im Unterverzeichnis
            "<filename>layouts/scripts/</filename>" in der eigenen Anwendung:
        </para>

        <programlisting language="text"><![CDATA[
application
|-- Bootstrap.php
|-- configs
|   `-- application.ini
|-- controllers
|-- layouts
|   `-- scripts
|       |-- layout.phtml
]]></programlisting>

        <para>
            Um <classname>Zend_Layout</classname> zu initialisieren muss das folgende in die eigene
            Konfigurationsdatei eingefügt werden
            ("<filename>application/configs/application.ini</filename>"):
        </para>

        <programlisting language="dosini"><![CDATA[
resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"
resources.layout.layout = "layout"
]]></programlisting>

        <para>
            Die erste Zeile zeigt wo nach Layout Skripten nachgesehen werden soll; die zweite Zeile
            gibt den Namen des Layouts an, welches verwendet werden soll, abzüglich der
            Erweiterung für View Skripts (welche standardmäßig mit "<filename>.phtml</filename>"
            angenommen wird).
        </para>
    </sect2>

    <sect2 id="learning.layout.usage.layout-script">
        <title>Ein Layout Skript erstellen</title>

        <para>
            Jetzt da man die Konfiguration gesetzt hat, muss man sein Layout Skript erstellen.
            Zuerst muss man sicherstellen dass das Verzeichnis
            "<filename>application/layouts/scripts</filename>" erstelt wurde; dann ist ein Editor
            zu öffnen und das Markup für das eigene Layout zu erstellen. Layout Skripte sind einfach
            View Skripte, mit einigen kleinen Unterschieden.
        </para>

        <programlisting language="php"><![CDATA[
<html>
<head>
    <title>Meine Site</title>
</head>
<body>
    <?php echo $this->layout()->content ?>
</body>
</html>
]]></programlisting>

        <para>
            Im obigen Beispiel ist der Aufruf zum <methodname>layout()</methodname> View Helper zu
            sehen. Wenn man die <classname>Zend_Layout</classname> Ressource registriert, erhält man
            auch Zugriff zum Action und zum View Helper welche es erlauben die
            <classname>Zend_Layout</classname> Instanz anzusprechen; man kann anschließend
            Befehle auf dem Layout Objekt aufrufen. In diesem Fall wird eine benannte Variable,
            <varname>$content</varname>, empfangen und ausgegeben. Standardmäßig wird die Variable
            <varname>$content</varname> vom Anwendungs-View Skript dargestellt. Andererseits ist
            alles was man normalerweise in einem View Skript macht perfekt gültig -- aufrufen von
            Helfern oder View Methoden wie man es will.
        </para>

        <para>
            An diesem Punkt hat man ein funktionierendes Layout Skript, und die eigene Anwendung ist
            über seinen Ort informiert und weis wie es darzustellen ist.
        </para>
    </sect2>

    <sect2 id="learning.layout.usage.access">
        <title>Auf das Layout Objekt zugreifen</title>

        <para>
            Manchmal ist ein Direktzugriff auf das Layout Objekt notwendig. Es gibt drei Wege wie
            man das tun kann:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>In den View Skripten:</emphasis> der <methodname>layout()</methodname>
                    View Helfer ist zu verwenden, der die Instanz von
                    <classname>Zend_Layout</classname> zurückgibt welche im Front Controller Plugin
                    registriert ist.
                </para>

                <programlisting language="php"><![CDATA[
<?php $layout = $this->layout(); ?>
]]></programlisting>

                <para>
                    Da er die Layout Instanz zurückgibt, kann man also einfach Methoden auf Ihm
                    aufrufen statt Ihn einer Variablen zuordnen zu müssen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>In Action Controllern</emphasis>: der
                    <methodname>layout()</methodname> Action Helfer ist zu verwenden, welcher wie
                    der View Helfer arbeitet.
                </para>

                <programlisting language="php"><![CDATA[
// Aufruf des Helfers als eine Methode auf dem Helfer Broker:
$layout = $this->_helper->layout();

// Oder etwas komplizierter:
$helper = $this->_helper->getHelper('Layout');
$layout = $helper->getLayoutInstance();
]]></programlisting>

                <para>
                    Wie mit dem View Helfer gibt der Action Helfer die Instanz des Layouts zurück,
                    man kann also einfach Methoden auf Ihm aufrufen, statt diese einer Variable
                    zuordnen zu müssen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Andernorts</emphasis>: verwenden der statischen Methode
                    <methodname>getMvcInstance()</methodname>. Das gibt die Layout Instanz zurück,
                    welche durch die Bootstrap Ressource registriert wurde.
                </para>

                <programlisting language="php"><![CDATA[
$layout = Zend_Layout::getMvcInstance();
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Über die Bootstrap</emphasis>: empfangen der Layout Ressource, welche
                    die <classname>Zend_Layout</classname> Instanz ist.
                </para>

                <programlisting language="php"><![CDATA[
$layout = $bootstrap->getResource('Layout');
]]></programlisting>

                <para>
                    Überall wo man auf das Bootstrap Objekt Zugriff hat, wird diese Methode
                    empfohlen und nicht die statische <methodname>getMvcInstance()</methodname>
                    Methode.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="learning.layout.usage.other-operations">
        <title>Andere Operationen</title>

        <para>
            In den meisten Fällen empfängt die obige Konfiguration und das Layout Skript (mit
            Änderungen) das, was benötigt wird. Trotzdem existieren einigen andere Funktionalitäten
            die man früher oder später verwenden wird. In allen der folgenden Beispiele kann man
            eine der <link
                linkend="learning.layout.usage.access">oben aufgeführten Methoden</link> verwenden
            um das Layout Objekt zu erhalten.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Setzen von Layout Variablen</emphasis>:
                    <classname>Zend_Layout</classname> hat seine eigene Registry von
                    Layout-spezifischen View Variablen auf die man zugreifen kann; der
                    <varname>$content</varname> Schlüssel welche im ursprünglichen Layout Skript
                    gezeigt wird, ist so ein Beispiel. Man kann diese zuweisen und empfangen indem
                    ein normaler Zugriff auf Eigenschaften verwendet wird, oder über die
                    <methodname>assign()</methodname> Methode.
                </para>

                <programlisting language="php"><![CDATA[
// Inhalt setzen:
$layout->somekey = "foo"

// Den selben Inhalt ausgeben:
echo $layout->somekey; // 'foo'

// Verwenden der assign() Methode:
$layout->assign('someotherkey', 'bar');

// Der Zugriff auf assign()'ed Variablen bleibt der gleiche:
echo $layout->someotherkey; // 'bar'
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <methodname>disableLayout()</methodname>: Üblicherweise wird man Layouts
                    ausschalten wollen; zum Beispiel wenn eine Ajax Anfrage beantwortet wird, oder
                    eine RESTvolle Darstellung einer Ressource angeboten wird. In diesem Fällen kann
                    man die <methodname>disableLayout()</methodname> Methode auf dem Layout Objekt
                    ausführen.
                </para>

                <programlisting language="php"><![CDATA[
$layout->disableLayout();
]]></programlisting>

                <para>
                    Das Gegenteil dieser Methode ist natürlich
                    <methodname>enableLayout()</methodname>, welches jederzeit aufgerufen werden
                    kann um Layouts für die angefragte Aktion wieder einzuschalten.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Ein alternatives Layout auswählen</emphasis>: Wenn man mehrere Layouts
                    für die eigene Site oder Anwendung hat, kann das Layout welches verwendet werden
                    soll jederzeit ausgewählt werden indem einfach die
                    <methodname>setLayout()</methodname> Methode aufgerufen wird. Es ist
                    aufzurufen indem der Name des Layout Skripts ohne die Dateiendung spezifiziert
                    wird.
                </para>

                <programlisting language="php"><![CDATA[
// Verwendung des Layout Skripts "alternate.phtml":
$layout->setLayout('alternate');
]]></programlisting>

                <para>
                    Das Layout Skript sollte im <varname>$layoutPath</varname> Verzeichnis enthalten
                    sein, welche in der eigenen Konfiguration spezifiziert ist.
                    <classname>Zend_Layout</classname> wird anschließend dieses neue Layout bei der
                    Darstellung verwenden.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>
