# dojo() Ayudante de Vista

El ayudante de vista `dojo()` está destinado a simplificar el establecimiento del medio ambiente de Dojo, incluyendo las siguientes responsabilidades:

- Especificar bien un CDN o un path local para instalar Dojo.

- Especificando paths a módulos Dojo personalizados.

- Especificando sentencias dojo.require.

- Especificando hojas de estilo dijit a usar.

- Especificando eventos dojo.addOnLoad().

La implementación del ayudante de vista `dojo()` es un ejemplo de implementación de un marcador de posición. El conjunto de datos en él, persiste entre los objetos vista y puede ser directamente activado con en "echo" de PHP desde su script.

## dojo() Ejemplo de Uso del Ayudante de Vista

En este ejemplo, asumamos que el desarrollador estará usando Dojo desde un path local, se necesitarán varios dijits, y se utilizará el tema de dijit Tundra.

En muchas páginas, el desarrollador no podrá utilizar Dojo para nada. Así, vamos a centrarnos primero en un view script donde Dojo es necesario y luego en el layout script, en donde vamos a configurar algo del medio ambiente de Dojo y luego lo mostraremos.

En primer lugar, tenemos que decir nuestro objeto vista que utilice el path del ayudante de vista de Dojo. Esto puede hacerse en el arranque o en un plugin de ejecución temprana; simplemente apoderarse de su objeto vista y ejecutar lo siguiente:

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

El paso siguiente, el view script. En este caso, vamos a especificar que vamos a estar utilizando un FilteringSelect -- que consumirá un almacén personalizado basado en QueryReadStore, al que llamamos 'PairedStore' y almacenado en nuestro módulo 'custom'.

    <?php // establecer el data store para FilteringSelect ?>
    <div dojoType="custom.PairedStore" jsId="stateStore"
        url="/data/autocomplete/type/state/format/ajax"
        requestMethod="get"></div>

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

    <?php // establecer elementos requeridos por dojo:
    $this->dojo()->enable()
                 ->setDjConfigOption('parseOnLoad', true)
                 ->registerModulePath('custom', '../custom/')
                 ->requireModule('dijit.form.FilteringSelect')
                 ->requireModule('custom.PairedStore'); ?>

En nuestro script de esquema, vamos entonces a comprobar si Dojo está habilitado, y si es así, haremos algunas configuraciones más generales y lo ensamblaremos:

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

En este punto, sólo necesita asegurarse de que sus archivos están en el lugar correcto y que ha creado el punto final de acción para su FilteringSelect!

## UTF-8 encoding used by default

By default, Zend Framework uses UTF-8 as its default encoding, and, specific to this case, `Zend_View` does as well. Character encoding can be set differently on the view object itself using the `setEncoding()` method (or the the `encoding` instantiation parameter). However, since `Zend_View_Interface` does not define accessors for encoding, it's possible that if you are using a custom view implementation with the Dojo view helper, you will not have a `getEncoding()` method, which is what the view helper uses internally for determining the character set in which to encode.

If you do not want to utilize UTF-8 in such a situation, you will need to implement a `getEncoding()` method in your custom view implementation.

## Uso Programático y Declarativo de Dojo

Dojo permite usar a ambos declarative y programmatic en muchas de sus características. El uso de Declarative utiliza elementos HTML con atributos no estándar que se parsean cuando la página se está cargado. Mientras que ésta es una sintaxis poderosa y simple de utilizar, para muchos desarrolladores esto puede causar problemas con la validación de páginas.

El uso de Programmatic permite al desarrollador decorar los elementos existentes tirando de ellos por ID o selectores CSS y pasarlos a los constructores apropiados de objetos en Dojo. Debido a que no se usan atributos HTML no standard, las páginas continúan con la validación.

En la práctica, ambos casos de uso permiten una degradación elegante cuando javascript está desactivado o los diversos recursos de Dojo script están fuera de alcance. Para promover las normas y validación de documentos, Zend Framework hace uso de los usos programáticos por defecto; los diversos ayudantes de vista generarán javascript y lo empujan al ayudante de vista `dojo()` para su inclusión cuando sean presentados.

Utilizando esta técnica los desarrolladores pueden también desear explorar la posibilidad de escribir sus propia decoración programática de la página. Uno de los beneficios sería la posibilidad de especificar handlers para eventos dijit.

Para permitir esto, así como la posibilidad de usar sintaxis declarativa, hay disponibles una serie de métodos estáticos para establecer globamente este comportamiento.

### Especificando el Uso Declarativo y Programático de Dojo

Para especificar el uso declarativo, simplemente llame al método estático `setUseDeclarative()` :

    Zend_Dojo_View_Helper_Dojo::setUseDeclarative();

Si decide más bien utilizar el uso programático, llame al método estático `setUseProgrammatic()` :

    Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();

Por último, si quiere crear sus propias normas programáticas, debe especificar el uso programático, pero al pasarle el valor '-1'; en esta situación, no se creará ningún javascript para decorar cualquier dijit usado.

    Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);

## Temas

Dojo permite la creación de los temas de su dijits (widgets). Puede seleccionar uno pasándolo en un path de módulo:

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

La ruta del módulo es descubierta por utilizar el carácter '.' como separador de directorio y utilizando el último valor en la lista como el nombre del archivo CSS en ese directorio del tema a usar; en el ejemplo de arriba, Dojo buscará el tema en 'dijit/themes/tundra/tundra.css'.

Cuando se utiliza un tema, es importante recordar pasar la calse del tema a, por lo menos un contenedor rodeando cualquier dijits que se utilice; el caso de uso más común es pasárselo en el body:

    <body class="tundra">

## Usando Layers (Construcciones Personalizadas)

Por defecto, cuando utilice uns sentencia dojo.require, dojo hará una solicitud de retorno al servidor para agarrar al archivo javascript apropiado. Si hay muchos dijits en el lugar, esto se traduce en muchas peticiones al servidor -- lo que no es óptimo.

La respuesta de Dojo a esto es proporcionar la capacidad de crear custom builds (construcciones personalizadas . Las contrucciones hacen varias cosas:

- Grupos de archivos necesarios en layers ; una capa (layer) agrupa a todos archivos necesarios en un único archivo JS. (De ahí el nombre de esta sección.)

- "Interns" no son archivos javascript usados por dijits (típicamente, archivos de plantilla). También están agrupados en el mismo archivo JS como la capa.

- Pasa el archivo a través de ShrinkSafe, que elimina espacios en blanco y comentarios, así como acorta nombres de variables.

Algunos archivos pueden no ser superpuestos, pero el proceso creará una versión especial del directorio con la archivo capa y todos los otros archivos. Esto le permite tener una distribución reducida adaptada a su sitio o necesidades de aplicación.

Para usar una capa, el ayudante de vista `dojo()` tiene el método `addLayer()` para añadir paths de capas requeridas:

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

Para más información sobre la creación de construcciones personalizadas, por favor consulte la docuemntación de Build de Dojo .

## Métodos Disponibles

El ayudante de vista `dojo()` siempre devuelve una instancia del contenedor del marcador de posición dojo. Ese objeto contenedor dispone de los siguientes métodos:

- `setView(Zend_View_Interface $view)` : establecer una instancia de vista en el contenedor.

- `enable()` : habilitar explícitamente la integración de Dojo.

- `disable()` : deshabilitar la integración de Dojo.

- `isEnabled()` : determinar cuándo la integración de Dojo está habilitada o no.

- `requireModule($module)` : establecer una sentencia `dojo.require`

- `getModules()` : determinar qué módulos han sido requeridos.

- `registerModulePath($module, $path)` : registrar un path de un módulo personalizado de Dojo.

- `getModulePaths()` : obtener la lista de los paths de módulos registrados.

- `addLayer($path)` : añadir una capa (construcción personalizada) del path a utilizar.

- `getLayers()` : conseguir una lista de todos los paths de capas registrados (construcción personalizada).

- `removeLayer($path)` : eliminar la capa que concuerde con `$path` de la lista de capas registradas (construcción personalizada).

- `setCdnBase($url)` : establecer la URL base para un CDN; típicamente, una de las `Zend_Dojo::CDN_BASE_AOL` o `Zend_Dojo::CDN_BASE_GOOGLE` , pero sólo necesita ser el string del URL antes del número de versión.

- `getCdnBase()` : recuperar el CDN de la url base a utilizar.

- `setCdnVersion($version = null)` : establecer cuál es la versión de Dojo a utilizar desde el CDN.

- `getCdnVersion()` : recuperar que versión de Dojo será utilizada desde el CDN.

- `setCdnDojoPath($path)` : establecer el path relativo a un archivo dojo.js o dojo.xd.js sobre un CDN; típicamente, uno de los `Zend_Dojo::CDN_DOJO_PATH_AOL` o `Zend_Dojo::CDN_DOJO_PATH_GOOGLE` , pero sólo debe ser el string del path detrás del número de versión.

- `getCdnDojoPath()` : recuperar el último segmento del path del CDN de la url apuntando al archivo dojo.js.

- `useCdn()` : decirle al contenedor que utilice el CDN; implícitamente permite integración.

- `setLocalPath($path)` : decirle al contenedor el path a una instalación local de Dojo (deberá ser una ruta relativa al servidor, y contener el propio archivo dojo.js); implícitamente permite integración.

- `getLocalPath()` : determinar qué ruta local a Dojo está siendo utilizada.

- `useLocalPath()` : ¿la integración está utilizando un path local de Dojo?

- `setDjConfig(array $config)` : conjunto de valores de configuración dojo/dijit (espera un array asociativo).

- `setDjConfigOption($option, $value)` : establecer un único valor de configuración para dojo/dijit.

- `getDjConfig()` : obtener todos los valores de configuración de dojo/dijit.

- `getDjConfigOption($option, $default = null)` : conseguir un único valor de configuración de dojo/dijit.

- `addStylesheetModule($module)` : agregar una hoja de estilo sobre la base del tema de un módulo.

- `getStylesheetModules()` : obtener hojas de estilo registradas como temas de módulos.

- `addStylesheet($path)` : agregar una hoja de estilo local para su uso con Dojo.

- `getStylesheets()` : obtener hojas de estilo locales Dojo.

- `addOnLoad($spec, $function = null)` : agregar un lambda para dojo.onLoad para llamadas. Si se pasa un argumento, se supone que que puede ser tanto el nombre de una función o dar por terminado javascript. Si se pasan dos argumentos, el primero se supone que es el nombre de la variable de la instancia de un objeto y el segundo ya sea un nombre de método en ese objeto o un cierre a utilizar con ese objeto.

- `prependOnLoad($spec, $function = null)` : exactamente como `addOnLoad()` , excluyendo agregar al principio el comienzo de onLoad stack.

- `getOnLoadActions()` : recuperar todas las acciones dojo.onLoad registradas con el contenedor. Esto será un array de arrays.

- `onLoadCaptureStart($obj = null)` : capturar los datos que se utilizarán como lambda para dojo.onLoad(). Si se provee $obj, los códigos JS capturados serán considerados un cierre a utilizar con ese objeto Javascript.

- `onLoadCaptureEnd($obj = null)` : finalizar la captura de datos para su uso con dojo.onLoad().

- `javascriptCaptureStart()` : captura javascript arbitrario para ser incluido en Dojo JS (onLoad, require, etc. statements).

- `javascriptCaptureEnd()` : finalizar la captura de javascript.

- `__toString()` : emitir el contenedor a un string; muestra todo el estilo HTML y elementos del script.