<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect2 id="zend.dojo.view.dojo">
    <title>dojo() View Helfer</title>

    <para>
        Der <methodname>dojo()</methodname> View Helfer ist dazu gedacht das konfigurieren der Dojo
        Umgebung zu vereinfachen, was die folgenden Notwendigkeiten beinhaltet:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                Spezifizieren eines <acronym>CDN</acronym> oder lokalen Pfades zu einer Dojo
                Installation.
            </para>
        </listitem>

        <listitem><para>Spezifizieren von Pfaden zu eigenen Dojo Modulen.</para></listitem>

        <listitem>
            <para>Spezifizieren von <command>dojo.require</command> Statements.</para>
        </listitem>

        <listitem><para>Spezifizieren von Dijit Stylesheet Themen zur Verwendung.</para></listitem>

        <listitem>
            <para>Spezifizieren von <command>dojo.addOnLoad()</command> Events.</para>
        </listitem>
    </itemizedlist>

    <para>
        Die <methodname>dojo()</methodname> View Helfer Implementation ist ein Beispiel einer
        Platzhalter Implementation. Das Datenset in Ihm ist persistent zwischen den View Objekten,
        und kann direkt im eigenen Layout Skript ausgegeben werden.
    </para>

    <example id="zend.dojo.view.dojo.usage">
        <title>Beispiel für die Verwendung des dojo() View Helfers</title>

        <para>
            Für dieses Beispiel nehmen wir an das der Entwickler Dojo von einem lokalen Pfad aus
            verwenden wird, verschiedene Dijits benötigt, und das Tundra Dijit Thema anpasst.
        </para>

        <para>
            Auf vielen Seiten, kann der Entwickler Dojo nicht einmal verwenden. Deshalb werden wir
            uns zuerst auf ein View Skript fokusieren indem Dojo benötigt wird, und dann auf das
            Layout Skript, indem wir einiges der Dojo Umgebung einstellen und anschließend
            darstellen werden.
        </para>

        <para>
            Zuerst müssen wir unserem View Objekt mitteilen das es die Dojo View Helferpfade
            verwenden soll. Das kann in der eigenen Bootstrap Datei getan werden oder in einem
            Plugin das früh abläuft; einfach das View Objekt nehmen und das folgende ausführen:
        </para>

        <programlisting language="php"><![CDATA[
$view->addHelperPath('Zend/Dojo/View/Helper/', 'Zend_Dojo_View_Helper');
]]></programlisting>

        <para>
            Als nächstes das View Skript. In diesem Fall werden die spezifizieren das ein
            FilterSelect verwendet werden soll -- welcher einen eigenen Speicher basierend auf
            QueryReadStore verwenden wird, und den wir 'PairedStore' nennen und in unserem 'custom'
            Modul speichern.
        </para>

        <programlisting language="php"><![CDATA[
<?php // Datenspeicher für FilteringSelect einstellen ?>
<div dojoType="custom.PairedStore" jsId="stateStore"
    url="/data/autocomplete/type/state/format/ajax"
    requestMethod="get"></div>

<?php // Eingabeelement: ?>
State: <input id="state" dojoType="dijit.form.FilteringSelect"
    store="stateStore" pageSize="5" />

<?php // Notwendige Dojo Elemente einstellen:
$this->dojo()->enable()
             ->setDjConfigOption('parseOnLoad', true)
             ->registerModulePath('custom', '../custom/')
             ->requireModule('dijit.form.FilteringSelect')
             ->requireModule('custom.PairedStore'); ?>
]]></programlisting>

        <para>
            In unserem Layout Skript, prüfen wir anschließend ob Dojo aktiviert ist, und wenn das
            der Fall ist, erledigen wir einige generelle Konfigurationen und fügen Sie hinzu:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->doctype() ?>
<html>
<head>
    <?php echo $this->headTitle() ?>
    <?php echo $this->headMeta() ?>
    <?php echo $this->headLink() ?>
    <?php echo $this->headStyle() ?>
<?php if ($this->dojo()->isEnabled()){
    $this->dojo()->setLocalPath('/js/dojo/dojo.js')
                 ->addStyleSheetModule('dijit.themes.tundra');
    echo $this->dojo();
   }
?>
    <?php echo $this->headScript() ?>
</head>
<body class="tundra">
    <?php echo $this->layout()->content ?>
    <?php echo $this->inlineScript() ?>
</body>
</html>
]]></programlisting>

        <para>
            An diesem Punkt muß man nur sicherstellen das die Dateien am richtigen Ort vorhanden
            sind und das man die Aktion des Endpunktes für das FilteringSelect erstellt hat!
        </para>
    </example>

    <note>
        <title>Standardmäßig wird die UTF-8 Kodierung verwendet</title>

        <para>
            Standardmäßig verwendet Zend Framework <acronym>UTF-8</acronym> als seine
            Standardkodierung, und speziell in diesem Fall, macht das
            <classname>Zend_View</classname> genauso. Die Zeichenkodierung kann im View Objekt
            selbst auf etwas anderes gesetzt werden indem die Methode
            <methodname>setEncoding()</methodname> verwendet wird (oder der Parameter
            <property>encoding</property> bei der Instanzierung angegeben wird). Trotzdem, da
            <classname>Zend_View_Interface</classname> keine Zugriffsmethoden für die Kodierung
            anbietet ist es möglich dass, wenn man eine eigene View Implementation verwendet, man
            keine <methodname>getEncoding()</methodname> Methode hat, welche der View Helfer intern
            für die Erkennung des Zeichensets verwendet in das kodiert werden soll.
        </para>

        <para>
            Wenn man <acronym>UTF-8</acronym> in solch einer Situation nicht verwenden will, muss
            man in der eigenen View Implementation eine <methodname>getEncoding()</methodname>
            Methode implementieren.
        </para>
    </note>

    <sect3 id="zend.dojo.view.dojo.declarative">
        <title>Programtechnische und Deklarative Verwendung von Dojo</title>

        <para>
            Dojo erlaubt sowohl die <emphasis>deklarative</emphasis> als auch die
            <emphasis>programmtechnische</emphasis> Verwendung von vielen Ihrer Features.
            <emphasis>Deklarative</emphasis> Verwendung verwendet Standard <acronym>HTML</acronym>
            Elemente mit nicht-standard Attributen die geparst werden wenn die Seite geladen wird.
            Wärend das eine mächtige und einfach verwendbare Syntax ist, kann Sie für viele
            Entwickler Probleme bei der Überprüfung einer Seite verursachen.
        </para>

        <para>
            <emphasis>Programmtechnische</emphasis> Verwendung erlaubt dem Entwickler existierende
            Elemente zu dekorieren indem Sie anhand von ID oder <acronym>CSS</acronym> Selektoren
            geholt werden und dem entsprechenden Objektkonstruktoren in Dojo übergeben werden. Weil
            keine nicht-standard <acronym>HTML</acronym> Attribute verwendet werden, bleiben Seiten
            hiermit gültig.
        </para>

        <para>
            In der Praxis, erlauben beide Fälle eine zierliche Degeneration wenn Javascript
            ausgeschaltet ist, oder die verschiedenen Dojo Skriptresourcen nicht erreichbar sind. Um
            Standards und Dokumentüberprüfungen zu gestatten verwendet Zend Framework standardmäßig
            die programmtechnische Verwendung; die verschiedenen Viewhelfer erzeugen Javascript und
            übergeben dieses an den <methodname>dojo()</methodname> Viewhelfer für die Einbeziehung
            wenn er dargestellt wird.
        </para>

        <para>
            Entwickler die diese Technik verwenden wollen eventuell auch die Option kennenlernen mit
            der Sie Ihre eigene programmtechnische Deklaration auf der Seite schreiben können. Ein
            Vorteil wäre die Möglichkeit Handler für Dijit Events zu spezifizieren.
        </para>

        <para>
            Um das zu erlauben, wie auch die Möglichkeit die deklarative Syntax zu verwenden, sind
            es eine Anzahl von statischen Methoden vorhanden die dieses Verhalten global setzen.
        </para>

        <example id="zend.dojo.view.dojo.declarative.usage">
            <title>
                Spezifizieren der deklarativen und programmtechnischen Verwendung von Dojo
            </title>

            <para>
                Um die deklarative Verwendung zu spezifizieren muß einfach die statische
                <methodname>setUseDeclarative()</methodname> Methode aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
Zend_Dojo_View_Helper_Dojo::setUseDeclarative();
]]></programlisting>

            <para>
                Wenn man stattdessen die programmtechnische Verwendung verwenden will, muß die
                statische <methodname>setUseProgrammatic()</methodname> Methode aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();
]]></programlisting>

            <para>
                Letztendlich, wenn man programmtechnische Regeln selbst erstellen will, sollte man
                die programmtechnische Verwendung spezifizieren, aber den Wert '-1' übergeben; in
                diesem Fall wird kein Javascript, für die Dekoration von verwendeten Dijits,
                erstellt.
            </para>

            <programlisting language="php"><![CDATA[
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.view.dojo.themes">
        <title>Themen</title>

        <para>
            Dojo erlaubt die Erstellung von Themen für seine Dijits (Widgets). Man kann eines
            auswählen indem ein Modulpfad übergeben wird:
        </para>

        <programlisting language="php"><![CDATA[
$view->dojo()->addStylesheetModule('dijit.themes.tundra');
]]></programlisting>

        <para>
            Der Modulpfad wird durch die Verwendung des Zeichens '.' als Trennzeichen vom
            Verzeichnis erkannt und der Verwendung des letzten Wertes in der Liste als den Namen der
            <acronym>CSS</acronym> Datei die im Themenverzeichnis verwendet wird; im obigen Beispiel
            sucht Dojo das Thema in '<filename>dijit/themes/tundra/tundra.css</filename>'.
        </para>

        <para>
            Wenn ein Thema verwendet wird ist es wichtig daran zu denken die Themenklasse, zumindest
            an den Container der jedes Dijit das verwendet wird umgibt, zu übergeben; im üblichsten
            Fällen wird es an den Body übergeben:
        </para>

        <programlisting language="html"><![CDATA[
<body class="tundra">
]]></programlisting>
    </sect3>

    <sect3 id="zend.dojo.view.dojo.layers">
        <title>Layer verwenden (eigene Builds)</title>

        <para>
            Wenn ein <command>dojo.require</command> Statement verwendet wird, wird Dojo
            standardmäßig eine Anfrage an den Server zurücksenden um die richtige Javascript Datei
            zu holen. Wenn man viele Dijits verwendet, resultiert das in vielen Anfragen an den
            Server -- was nicht optimal ist.
        </para>

        <para>
            Dojo's Antwort darauf ist es die Möglichkeit anzubieten
            <emphasis>eigene Builds</emphasis> zu erstellen. Builds machen verschiedene Dinge:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Benötigte Dateien in <emphasis>Layern</emphasis> gruppieren; ein Layer sammelt
                    alle benötigten Dateien in eine einzelne JS Datei. (Daher der Name dieses
                    Kapitels)
                </para>
            </listitem>

            <listitem>
                <para>
                    "Interne" nicht-javascript Dateien die von Dijits verwendet werden
                    (typischerweise Templatedateien). Diese werden auch in der gleichen JS Datei
                    gruppiert wie der Layer.
                </para>
            </listitem>

            <listitem>
                <para>
                    Die Datei wird an ShrinkSafe übergeben, welches Leerzeichen und Kommentare
                    entfernt, sowie Variablennamen verkleinert.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Einige Dateien können nicht in einen Layer gelegt werden, aber der Buildprozess wird
            ein spezielles Releaseverzeichnis mit der Layerdatei und allen anderen Dateien
            erstellen. Das erlaubt es eine verkleinerte eigene Distribution für die eigene Site oder
            Anwendungen zu erhalten.
        </para>

        <para>
            Um einen Layer zu verwenden, hat der <methodname>dojo()</methodname> Viewhelfer eine
            <methodname>addLayer()</methodname> Methode für das hinzufügen von Pfaden zu benötigten
            Layern:
        </para>

        <programlisting language="html"><![CDATA[
$view->dojo()->addLayer('/js/foo/foo.js');
]]></programlisting>

        <para>
            Für weitere Informationen über die Erstellung von eigenen Build, schauen Sie bitte
            <ulink
                url="http://dojotoolkit.org/reference-guide/dojo/index.html#package-system">in
                die Dojo Builddokumentation</ulink>.
        </para>
    </sect3>

    <sect3 id="zend.dojo.view.dojo.methods">
        <title>Vorhandene Methoden</title>

        <para>
            Der <methodname>dojo()</methodname> Viewhelfer gibt immer eine Instanz des Dojo
            Platzhaltercontainers zurück. Dieses Containerobjekt bietet die folgenden Methoden an:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setView(Zend_View_Interface $view)</methodname>: Setzt eine
                    Viewinstanz im Container
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>enable()</methodname>: Die Dojo Integration explizit einschalten.
                </para>
            </listitem>
            <listitem>
                <para><methodname>disable()</methodname>: Die Dojo Integration ausschalten.</para>
            </listitem>

            <listitem>
                <para>
                    <methodname>isEnabled()</methodname>: Ermitteln ob die Dojo Integration
                    eingeschaltet ist oder nicht.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>requireModule($module)</methodname>: Ein
                    <command>dojo.require</command> Statement konfigurieren.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getModules()</methodname>: Erkennen welche Module benötigt werden.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>registerModulePath($module, $path)</methodname>: Einen Dojo
                    Modulpfad registrieren.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getModulePaths()</methodname>: Eine Liste von registrierten
                    Modulpfaden erhalten.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>addLayer($path)</methodname>: Einen Layerpfad (eigenen Build) für
                    die Verwendung hinzufügen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getLayers()</methodname>: Eine Liste von allen registrierten
                    Layerpfaden (eigene Builds) erhalten.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>removeLayer($path)</methodname>: Den Layer der
                    <varname>$path</varname> entspricht von der Liste der registrierten Layer
                    (eigene Builds) entfernen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setCdnBase($url)</methodname>: Den Basis <acronym>URL</acronym> für
                    ein <acronym>CDN</acronym> setzen; typischerweise ist das
                    <constant>Zend_Dojo::CDN_BASE_AOL</constant> oder
                    <constant>Zend_Dojo::CDN_BASE_GOOGLE</constant>, aber es wird der
                    <acronym>URL</acronym> String vor der Versionsnummer benötigt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getCdnBase()</methodname>: Den Basis <acronym>CDN</acronym> Url
                    empfangen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setCdnVersion($version = null)</methodname>: Setzen selche Version
                    von Dojo vom <acronym>CDN</acronym> verwendet wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getCdnVersion()</methodname>: Die Dojo Version vom
                    <acronym>CDN</acronym> erhalten die verwendet wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setCdnDojoPath($path)</methodname>: Setzt den relativen Pfad zur
                    <filename>dojo.js</filename> oder <filename>dojo.xd.js</filename> Datei am
                    <acronym>CDN</acronym>; typischerweise ist das entweder
                    <constant>Zend_Dojo::CDN_DOJO_PATH_AOL</constant> oder
                    <constant>Zend_Dojo::CDN_DOJO_PATH_GOOGLE</constant>, aber es wird der
                    Pfadstring nach der Versionsnummer benötigt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getCdnDojoPath()</methodname>: Das letzte Pfadsegment der
                    <acronym>CDN</acronym> Url erhalten das auf die <filename>dojo.js</filename>
                    Datei zeigt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>useCdn()</methodname>: Dem Container mitteilen das
                    <acronym>CDN</acronym> verwendet werden soll; aktiviert die Integration
                    implizit.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setLocalPath($path)</methodname>: Dem Container den Pfad zu einer
                    lokalen Dojo Installation mitteilen (sollte ein Pfad relativ zum Server sein,
                    und die <filename>dojo.js</filename> Datei selbst enthalten); aktiviert die
                    Integration implizit.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getLocalPath()</methodname>: Erkennen welches lokale Pfad zu Dojo
                    verwendet
                    wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>useLocalPath()</methodname>: Verwendet die Integration einen
                    lokalen Dojopfad?
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setDjConfig(array $config)</methodname>: Setzt Dojo oder Dijit
                    Konfigurationswerte (erwartet ein assoziatives Array).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setDjConfigOption($option, $value)</methodname>: Setzt einen
                    einzelnen Dojo oder Dijit Konfigurationswert.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getDjConfig()</methodname>: Retourniert alle Dojo oder Dijit
                    Konfigurationswerte.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getDjConfigOption($option, $default = null)</methodname>:
                    Retourniert einen einzelnen Dojo oder Dijit Konfigurationswert.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>addStylesheetModule($module)</methodname>: Fügt ein Stylesheet
                    hinzu basierend auf einem Modulthema.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getStylesheetModules()</methodname>: Retourniert die als Modulthema
                    registrierten Modulthemen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>addStylesheet($path)</methodname>: Fügt einen lokalen Stylesheet
                    zur Verwendung mit Dojo hinzu.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getStylesheets()</methodname>: Retourniert die lokalen Dojo
                    Stylesheets.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>addOnLoad($spec, $function = null)</methodname>: Fügt ein Lambda
                    für <command>dojo.onLoad</command> hinzu das dieses aufruft. Wenn ein Argument
                    übergeben wird, wird dieses entweder als Funktionsname oder als
                    Javascriptabschluss angenommen. Wenn zwei Argumente übergeben werden, wird das
                    erste als Name der Variablen der Objektinstanz angenommen und der zweite
                    entweder als Methodenname in diesem Objekt oder ein Abschluß um dieses Objekt zu
                    verwenden.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>prependOnLoad($spec, $function = null)</methodname>: genau wie
                    <methodname>addOnLoad()</methodname>, außer das vor den Anfang des onLoad
                    Stacks angefügt wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getOnLoadActions()</methodname>: Gibt alle im Container
                    registrierten <command>dojo.onLoad</command> Aktionen zurück. Das ist ein Array
                    von Arrays.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>onLoadCaptureStart($obj = null)</methodname>: Empfange Daten die
                    als Lambda für <command>dojo.onLoad()</command> verwendet werden sollen. Wenn
                    <varname>$obj</varname> angegeben wird, wird der bekommene JS Code als Abschluß
                    angenommen der mit diesem Javascript Objekt verwendet werden soll.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>onLoadCaptureEnd($obj = null)</methodname>: Beendet das Empfangen
                    von Daten für die Verwendung mit <command>dojo.onLoad()</command>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>javascriptCaptureStart()</methodname>: Empfange Javascript das im
                    Dojo JS inkludiert werden soll (onLoad, require, und andere Anweisungen).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>javascriptCaptureEnd()</methodname>: Beende das Empfangen von
                    Javascript.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>__toString()</methodname>: Castet den Container zu einem String;
                    stellt alle <acronym>HTML</acronym> Stile und Skriptelemente dar.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>
</sect2>
