# dojo() View Helfer

Der `dojo()` View Helfer ist dazu gedacht das konfigurieren der Dojo Umgebung zu vereinfachen, was die folgenden Notwendigkeiten beinhaltet:

- Spezifizieren eines CDN oder lokalen Pfades zu einer Dojo Installation.

- Spezifizieren von Pfaden zu eigenen Dojo Modulen.

- Spezifizieren von dojo.require Statements.

- Spezifizieren von Dijit Stylesheet Themen zur Verwendung.

- Spezifizieren von dojo.addOnLoad() Events.

Die `dojo()` 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.

## Beispiel für die Verwendung des dojo() View Helfers

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.

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.

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:

    $view->addHelperPath('Zend/Dojo/View/Helper/', 'Zend_Dojo_View_Helper');

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.

    <?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'); ?>

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:

    <?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>

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!

## Programtechnische und Deklarative Verwendung von Dojo

Dojo erlaubt sowohl die deklarative als auch die programmtechnische Verwendung von vielen Ihrer Features. Deklarative 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.

Programmtechnische 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.

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 `dojo()` Viewhelfer für die Einbeziehung wenn er dargestellt wird.

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.

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.

### Spezifizieren der deklarativen und programmtechnischen Verwendung von Dojo

Um die deklarative Verwendung zu spezifizieren muß einfach die statische `setUseDeclarative()` Methode aufgerufen werden:

    Zend_Dojo_View_Helper_Dojo::setUseDeclarative();

Wenn man stattdessen die programmtechnische Verwendung verwenden will, muß die statische `setUseProgrammatic()` Methode aufgerufen werden:

    Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();

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.

    Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);

## Themen

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

    $view->dojo()->addStylesheetModule('dijit.themes.tundra');

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'.

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:

    <body class="tundra">

## Layer verwenden (eigene Builds)

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.

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

- Benötigte Dateien in Layern gruppieren; ein Layer sammelt alle benötigten Dateien in eine einzelne JS Datei. (Daher der Name dieses Kapitels)

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

- Die Datei wird an ShrinkSafe übergeben, welches Leerzeichen und Kommentare entfernt, sowie Variablennamen verkleinert.

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.

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

    $view->dojo()->addLayer('/js/foo/foo.js');

Für weitere Informationen über die Erstellung von eigenen Build, schauen Sie bitte in die Dojo Builddokumentation.

## Vorhandene Methoden

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

- `setView(Zend_View_Interface $view)`: Setzt eine Viewinstanz im Container

- `enable()`: Die Dojo Integration explizit einschalten.

- `disable()`: Die Dojo Integration ausschalten.

- `isEnabled()`: Ermitteln ob die Dojo Integration eingeschaltet ist oder nicht.

- `requireModule($module)`: Ein dojo.require Statement konfigurieren.

- `getModules()`: Erkennen welche Module benötigt werden.

- `registerModulePath($module, $path)`: Einen Dojo Modulpfad registrieren.

- `getModulePaths()`: Eine Liste von registrierten Modulpfaden erhalten.

- `addLayer($path)`: Einen Layerpfad (eigenen Build) für die Verwendung hinzufügen.

- `getLayers()`: Eine Liste von allen registrierten Layerpfaden (eigene Builds) erhalten.

- `removeLayer($path)`: Den Layer der `$path` entspricht von der Liste der registrierten Layer (eigene Builds) entfernen.

- `setCdnBase($url)`: Den Basis URL für ein CDN setzen; typischerweise ist das `Zend_Dojo::CDN_BASE_AOL` oder `Zend_Dojo::CDN_BASE_GOOGLE`, aber es wird der URL String vor der Versionsnummer benötigt.

- `getCdnBase()`: Den Basis CDN URL empfangen.

- `setCdnVersion($version = null)`: Setzen selche Version von Dojo vom CDN verwendet wird.

- `getCdnVersion()`: Die Dojo Version vom CDN erhalten die verwendet wird.

- `setCdnDojoPath($path)`: Setzt den relativen Pfad zur dojo.js oder dojo.xd.js Datei am CDN; typischerweise ist das entweder `Zend_Dojo::CDN_DOJO_PATH_AOL` oder `Zend_Dojo::CDN_DOJO_PATH_GOOGLE`, aber es wird der Pfadstring nach der Versionsnummer benötigt.

- `getCdnDojoPath()`: Das letzte Pfadsegment der CDN URL erhalten das auf die dojo.js Datei zeigt.

- `useCdn()`: Dem Container mitteilen das CDN verwendet werden soll; aktiviert die Integration implizit.

- `setLocalPath($path)`: 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.

- `getLocalPath()`: Erkennen welches lokale Pfad zu Dojo verwendet wird.

- `useLocalPath()`: Verwendet die Integration einen lokalen Dojopfad?

- `setDjConfig(array $config)`: Setzt Dojo/Dijit Konfigurationswerte (erwartet ein assoziatives Array).

- `setDjConfigOption($option, $value)`: Setzt einen einzelnen Dojo/Dijit Konfigurationswert.

- `getDjConfig()`: Retourniert alle Dojo/Dijit Konfigurationswerte.

- `getDjConfigOption($option, $default = null)`: Retourniert einen einzelnen Dojo/Dijit Konfigurationswert.

- `addStylesheetModule($module)`: Fügt ein Stylesheet hinzu basierend auf einem Modulthema.

- `getStylesheetModules()`: Retourniert die als Modulthema registrierten Modulthemen.

- `addStylesheet($path)`: Fügt einen lokalen Stylesheet zur Verwendung mit Dojo hinzu.

- `getStylesheets()`: Retourniert die lokalen Dojo Stylesheets.

- `addOnLoad($spec, $function = null)`: 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.

- `prependOnLoad($spec, $function = null)`: genau wie `addOnLoad()`, außer das vor den Anfang des onLoad Stacks angefügt wird.

- `getOnLoadActions()`: Gibt alle im Container registrierten dojo.onLoad Aktionen zurück. Das ist ein Array von Arrays.

- `onLoadCaptureStart($obj = null)`: 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.

- `onLoadCaptureEnd($obj = null)`: Beendet das Empfangen von Daten für die Verwendung mit dojo.onLoad().

- `javascriptCaptureStart()`: Empfange Javascript das im Dojo JS inkludiert werden soll (onLoad, require, und andere Anweisungen).

- `javascriptCaptureEnd()`: Beende das Empfangen von Javascript.

- `__toString()`: Castet den Container zu einem String; stellt alle HTML Stile und Skriptelemente dar.