<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="learning.view.placeholders.basics">
    <title>Grundsätzliche Verwendung von Platzhaltern</title>

    <para>
        Zend Framework definiert einen generischen <methodname>placeholder()</methodname> View
        Helfer den man für so viele eigene Platzhalter verwenden kann wie man will. Er bietet auch
        eine Vielzahl an Platzhalter Implementationen für oft benötigte Funktionalitäten, wie die
        Spezifikation der <emphasis>DocType</emphasis> Deklaration, den Titel des Dokuments und
        mehr.
    </para>

    <para>
        Alle Platzhalter arbeiten einigermaßen auf die selbe Art und Weise. Sie sind Container und
        erlauben es deshalb das man mit Ihnen als Kollektion arbeitet. Mit Ihnen kann man:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis>Anhängen</emphasis> oder <emphasis>voranstellen</emphasis> von Elementen
                an die Kollektion.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Ersetzen</emphasis> der kompletten Kollektion mit einem einzelnen Wert.
            </para>
        </listitem>

        <listitem>
            <para>
                Einen String spezifizieren welcher der <emphasis>Ausgaben vorangestellt</emphasis>
                wird wenn die Kollektion dargestellt wird.
            </para>
        </listitem>

        <listitem>
            <para>
                Einen String spezifizieren welcher der <emphasis>Ausgaben angehängt</emphasis>
                wird wenn die Kollektion dargestellt wird.
            </para>
        </listitem>

        <listitem>
            <para>
                Einen String spezifizieren mit dem <emphasis>Elemente geteilt</emphasis> werden wenn
                die Kollektion dargestellt wird.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Inhalte holen</emphasis> die sich in der Kollektion befinden.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Darstellen</emphasis> der gesammelten Inhalte.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Typischerweise ruft man den Helper ohne Argumente auf, damit er einen Container zurückgibt
        mit dem man arbeiten kann. Man gibt diesen Container aus (echo) um Ihn darzustellen, oder
        ruft auf Ihm Methoden auf um Ihn zu konfigurieren oder auszugeben. Wenn der Container leer
        ist, wird seine Darstellung einfach einen leeren String zurückgeben; andernfalls wird der
        Inhalt zusammengefasst entsprechend der Regeln welche konfiguriert worden sind.
    </para>

    <para>
        Als Beispiel erstellen wir eine Sidebar die aus einer Anzahl an "Blöcken" von Inhalten
        besteht. Man wird normalerweise die Struktur jeden Blocks aus dem Bauch heraus wissen;
        nehmen wir für dieses Beispiel an dass Sie wie folgt aussieht:
    </para>

    <programlisting language="html"><![CDATA[
<div class="sidebar">
    <div class="block">
        <p>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus
            consectetur aliquet odio ac consectetur. Nulla quis eleifend
            tortor. Pellentesque varius, odio quis bibendum consequat, diam
            lectus porttitor quam, et aliquet mauris orci eu augue.
        </p>
    </div>
    <div class="block">
        <ul>
            <li><a href="/some/target">Link</a></li>
            <li><a href="/some/target">Link</a></li>
        </ul>
    </div>
</div>
]]></programlisting>

    <para>
        Der Inhalt veriiert basieren auf dem Controller und der Aktion, aber die Struktur ist die
        gleiche. Zuerst stellen wir die Sidebar in der Sidebar einer Ressource Methode unserer
        Bootstrap ein:
    </para>

    <programlisting language="php"><![CDATA[
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    // ...

    protected function _initSidebar()
    {
        $this->bootstrap('View');
        $view = $this->getResource('View');

        $view->placeholder('sidebar')
             // "prefix" -> Markup der einmalig vor allen Elementen
             // der Kollektion auszugeben ist
             ->setPrefix("<div class=\"sidebar\">\n    <div class=\"block\">\n")
             // "separator" -> Markup der zwischen Elementen
             // der Kollektion auszugeben ist
             ->setSeparator("</div>\n    <div class=\"block\">\n")
             // "postfix" -> Markup der einmalig nach allen Elementen
             // der Kollektion auszugeben ist
             ->setPostfix("</div>\n</div>");
    }

    // ...
}
]]></programlisting>

    <para>
        Das obige definiert den Platzhalter "sidebar" der keine Elemente hat. Er konfiguriert die
        grundsätzliche Struktur des Markups dieses Platzhalter, aber basieren auf unseren
        Anforderungen.
    </para>

    <para>
        Jetzt nehmen wir für den "user" Controller an das wir für alle Aktionen einen Block ganz
        oben wollen der einige Informationen enthält. Wir können das auf zwei Wegen erreichen: (a)
        wir könnten den Inhalt direkt dem Platzhalter mit der Methode
        <methodname>preDispatch()</methodname> des Controllers hinzufügen, oder (b) wir könnten ein
        View Skript in der <methodname>preDispatch()</methodname> Methode darstellen. Wir verwenden
        (b) da es einer besseren Trennung der Wünsche folgt (indem es View-betreffende Logik und
        Funktionalität im View Skript behält).
    </para>

    <para>
        Wir benennen das View Skript "<filename>user/_sidebar.phtml</filename>", und machen es wir
        folgt bekannt:
    </para>

    <programlisting language="php"><![CDATA[
<?php $this->placeholder('sidebar')->captureStart() ?>
<h4>Benutzer Administration</h4>
<ul>
    <li><a href="<?php $this->url(array('action' => 'list')) ?>">
        Liste</a></li>
    <li><a href="<?php $this->url(array('action' => 'create')) ?>">
        Erstellen</a></a></li>
</ul>
<?php $this->placeholder('sidebar')->captureEnd() ?>
]]></programlisting>

    <para>
        Das obige Beispiel verwendet das Capture Feature für den Inhalt des Platzhalters.
        Standardmäßig wird Inhalt dem Container als neues Element angehängt, was es erlaubt Ihn zu
        sammeln. Dieses Beispiel verwendet View Helfer und statisches <acronym>HTML</acronym> um
        Markup zu erzeugen. Der Inhalt wird anschließend gefangen und dem Platzhalter selbst
        angehängt.
    </para>

    <para>
        Um das oben stehende View Skript einzubinden würden wir das folgende in unserer
        <methodname>preDispatch()</methodname> Methode schreiben:
    </para>

    <programlisting language="php"><![CDATA[
class UserController extends Zend_Controller_Action
{
    // ...

    public function preDispatch()
    {
        // ...

        $this->view->render('user/_sidebar.phtml');

        // ...
    }

    // ...
}
]]></programlisting>

    <para>
        Es ist zu beachten das wir den dargestellten Wert nicht fangen; es gibt keine Notwendigkeit
        dafür da die komplette View in einem Platzhalter gefangen wird.
    </para>

    <para>
        Nehmen wir also an das unsere "view" Aktion die im selben Controlle ist einige Informationen
        anzeigen muss. Im View Skript "<filename>user/view.phtml</filename>" könnten wie den
        folgende Inhalts Abschnitt haben:
    </para>

    <programlisting language="php"><![CDATA[
$this->placeholder('sidebar')
     ->append('<p>Benutzer: ' . $this->escape($this->username) .  '</p>');
]]></programlisting>

    <para>
        Dieses Beispiel verwendet die <methodname>append()</methodname> Methode und übergibt Ihr
        etwas einfachen Markup zum sammeln.
    </para>

    <para>
        Letztendlich verändern wir das Layout View Skript und stellen den Platzhalter dar.
    </para>

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

    <para>
        Für Controller und Aktionen welche den "sidebar" Platzhalter nicht verwenden wird kein
        Inhalt dargestellt; für jene die es tun wird, wenn der Platzhalter ausgegeben wird der
        Inhalt, entsprechend der Regeln die in unserer Bootstrap erstellt wurden, dargestellt als
        auch der Inhalt den wir über die Anwendung hinaus sammeln. Im Falle der
        "<filename>/user/view</filename>" Aktion, und der Annahme des Benutzernamens "matthew"
        würden wir den folgenden Inhalt der Sidebar erhalten (aus Gründen der Lesbarkeit
        formatiert):
    </para>

    <programlisting language="html"><![CDATA[
<div class="sidebar">
    <div class="block">
        <h4>Benutzer Administration</h4>
        <ul>
            <li><a href="/user/list">Liste</a></li>
            <li><a href="/user/create">Erstellen</a></a></li>
        </ul>
    </div>
    <div class="block">
        <p>Benutzer: matthew</p>
    </div>
</div>
]]></programlisting>

    <para>
        Es gibt eine große Anzahl an Dinge die man tun kann wenn Platzhalter und Layout Skripte
        kombiniert werden; man sollte mit Ihnen experimentieren und das <link
            linkend="zend.view.helpers.initial.placeholder">betreffende Kapitel im Handbuch</link>
        für weitere Informationen lesen.
    </para>
</sect1>
