boarspring
/
repo_zf1
mirror of https://github.com/bluescreen/zf1-php7.2.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532
							<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17133 -->
<!-- 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 CDN oder lokalen Pfades zu einer Dojo Installation.</para>
        </listitem>
        <listitem>
            <para>Spezifizieren von Pfaden zu eigenen Dojo Modulen.</para>
        </listitem>
        <listitem>
            <para>Spezifizieren von dojo.require Statements.</para>
        </listitem>
        <listitem>
            <para>Spezifizieren von Dijit Stylesheet Themen zur Verwendung.</para>
        </listitem>
        <listitem>
            <para>Spezifizieren von dojo.addOnLoad() 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>

    <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 HTML 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 CSS Selektoren geholt werden und dem
            entsprechenden Objektkonstruktoren in Dojo übergeben werden. Weil keine nicht-standard
            HTML 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
            CSS Datei die im Themenverzeichnis verwendet wird; im obigen Beispiel sucht Dojo das
            Thema in 'dijit/themes/tundra/tundra.css'.
        </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 dojo.require 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/book/dojo-book-0-9/part-4-meta-dojo/package-system-and-custom-builds">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 <code>dojo.require</code>
                    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 <code>$path</code>
                    entspricht von der Liste der registrierten Layer (eigene Builds) entfernen.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setCdnBase($url)</methodname>: Den Basis URL für ein CDN setzen;
                    typischerweise ist das <classname>Zend_Dojo::CDN_BASE_AOL</classname> oder
                    <classname>Zend_Dojo::CDN_BASE_GOOGLE</classname>, aber es wird der URL String
                    vor der Versionsnummer benötigt.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getCdnBase()</methodname>: Den Basis CDN URL empfangen.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setCdnVersion($version = null)</methodname>: Setzen selche Version
                    von Dojo vom CDN verwendet wird.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getCdnVersion()</methodname>: Die Dojo Version vom CDN erhalten die
                    verwendet wird.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setCdnDojoPath($path)</methodname>: Setzt den relativen Pfad zur
                    dojo.js oder dojo.xd.js Datei am CDN; typischerweise ist das entweder
                    <classname>Zend_Dojo::CDN_DOJO_PATH_AOL</classname> oder
                    <classname>Zend_Dojo::CDN_DOJO_PATH_GOOGLE</classname>, aber es wird der
                    Pfadstring nach der Versionsnummer benötigt.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getCdnDojoPath()</methodname>: Das letzte Pfadsegment der CDN URL
                    erhalten das auf die dojo.js Datei zeigt.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>useCdn()</methodname>: Dem Container mitteilen das CDN 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 dojo.js 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/Dijit
                    Konfigurationswerte (erwartet ein assoziatives Array).
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setDjConfigOption($option, $value)</methodname>: Setzt einen
                    einzelnen Dojo/Dijit Konfigurationswert.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getDjConfig()</methodname>: Retourniert alle Dojo/Dijit
                    Konfigurationswerte.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getDjConfigOption($option, $default = null)</methodname>:
                    Retourniert einen einzelnen Dojo/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 dojo.onLoad 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 dojo.onLoad 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 dojo.onLoad() verwendet werden sollen. Wenn $obj 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 dojo.onLoad().
                </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 HTML Stile und Skriptelemente dar.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->