# Zend_Dojo_Data: Envolturas de dojo.data

Dojo proporciona abstracciones de datos para los widgets de datos habilitados a través de su componente dojo.data. Este componente proporciona la capacidad de adjuntar un datastore, ofrecer algunos metadatos relativos al campo identidad, opcionalmente una etiqueta de campo, y una API para efectuar consultas, clasificación, recuperación de archivos y conjuntos de registros del datastore.

dojo.data se utiliza a menudo con XmlHttpRequest para traer dinámicamente datos desde el servidor. El principal mecanismo para esto es extender el QueryReadStore para que apunte a una URL y especificar la información a consultar. El lado del servidor después devuelve los datos con el siguiente formato JSON :

    {
        identifier: '<name>',
        <label: '<label>',>
        items: [
            { name: '...', label: '...', someKey: '...' },
            ...
        ]
    }

`Zend_Dojo_Data` ofrece una interfaz simple para la construcción de estas estructuras programáticamente, interactuando con ellos, y serializándolos a un array o a JSON .

## Uso de Zend_Dojo_Data

En su forma más simple, dojo.data requiere que se proporcione el nombre del campo identificador en cada item, y un conjunto de items (datos). Puede pasarlos tanto via el constructor, o via mutators:

### Inicialización de Zend_Dojo_Data via constructor

    $data = new Zend_Dojo_Data('id', $items);

### Inicialización de Zend_Dojo_Data via mutators

    $data = new Zend_Dojo_Data();
    $data->setIdentifier('id')
         ->addItems($items);

También puede añadir un solo item a la vez, o agregar items utilizando `addItem()` y `addItems()` .

### Agregando datos a Zend_Dojo_Data

    $data = new Zend_Dojo_Data($identifier, $items);
    $data->addItem($someItem);

    $data->addItems($someMoreItems);

### Siempre use un identificador!

Cada datastore de dojo.data requiere que la columna identificadora se proporcione como metadatos, incluyendo `Zend_Dojo_Data` . De hecho, si intenta añadir items sin un identificador, se generará una excepción.

Los items individuales pueden ser uno de los siguientes:

- Arrays asociativos

- Objectos implementando un método `toArray()`

- Cualquiera de los otros objetos (se serializarán via get_object_vars())

Puede adjuntar colecciones de los items anteriores via `addItems()` o `setItems()` (sobreescribe todos los items previamente establecidos); cuando lo haga, puede pasar un solo argumento:

- Arrays

- Objectos implementando la interfaz `Traversable` , que incluye las interfaces `Iterator` y `ArrayAccess` .

Si quiere especificar un campo que actuará como una etiqueta para el item, llame a `setLabel()` :

### Especificando la etiqueta de un campo en Zend_Dojo_Data

    $data->setLabel('name');

Por último, también puede cargar un item `Zend_Dojo_Data` de un array JSON dojo.data, utilizando el método `fromJson()` .

### Alimentando Zend_Dojo_Data desde JSON

    $data->fromJson($json);

## Agregando metadatos a sus contenedores

Algunos componentes de Dojo requieren metadatos adicionales junto al conjunto de datos de dojo.data. Como ejemplo, `dojox.grid.Grid` puede tirar datos dinámicamente desde un `dojox.data.QueryReadStore` . Para que la paginación funcione correctamente, cada conjunto de datos de regreso debería contener una clave numRows con el número total de filas que podrían ser devueltas por la consulta. Con estos datos, la plantilla sabe cuando seguir haciendo pequeños pedidos de subconjuntos de datos al servidor y cuando dejar de hacer más peticiones (es decir, ha llegado a la última página de datos). Esta técnica es útil para despachar grandes conjuntos de datos en sus plantillas sin cargar todo el conjunto de una sola vez.

`Zend_Dojo_Data` permite asignar propiedades a los metadatos como al objeto. Lo siguiente ilustra su uso:

    // Establece el "numRows" a 100
    $data->setMetadata('numRows', 100);

    // Establece varios items a la vez:
    $data->setMetadata(array(
        'numRows' => 100,
        'sort'    => 'name',
    ));

    // Inspecciona un único valor de metadatos:
    $numRows = $data->getMetadata('numRows');

    // Inspecciona todos los metadatos:
    $metadata = $data->getMetadata();

    // Elimina un item de metadatos:
    $data->clearMetadata('numRows');

    // Elimina todos los metadatos:
    $data->clearMetadata();

## Casos Avanzados de Uso

Además de actuar como un contenedor de datos serializable, `Zend_Dojo_Data` también ofrece la posibilidad de manipular y recorrer los datos en una variedad de formas.

`Zend_Dojo_Data` implementa las interfaces `ArrayAccess` , `Iterator` , y `Countable` . Por lo tanto, puede usar la recopilación de datos casi como si fuera un array.

Todos los items son referenciados por el identificador de campo. Dado que los identificadores deben ser únicos, puede usar los valores de este campo para sacar los registros individuales. Hay dos maneras de hacer esto: con el método `getItem()` , o via notación de array.

    // Usando getItem():
    $item = $data->getItem('foo');

    // O usando notación de array:
    $item = $data['foo'];

Si conoce el identificador, puede utilizarlo para recuperar un item, actualizarlo, borrarlo, crearlo, o probarlo:

    // Actualizar o crear un item:
    $data['foo'] = array('title' => 'Foo', 'email' => 'foo@foo.com');

    // Borrar un item:
    unset($data['foo']);

    // Efectuar una prueba para un item:
    if (isset($data[foo])) {
    }

También puede hacer un loop sobre todos los items. Internamente, todos los items se almacenan como arrays.

    foreach ($data as $item) {
        echo $item['title'] . ': ' . $item['description'] . "\n";
    }

O inclusive contar para ver cuántos ítems tiene:

    echo count($data), " items encontrados!";

Por último, como la clase implementa `__toString()` , también puede convertirlo a JSON simplemente con "echo" de PHP o convertirlo a string:

    echo $data; // echo como un string JSON

    $json = (string) $data; // conversión a string == conversión a JSON

### Métodos Disponibles

Además de los métodos necesarios para aplicar las interfaces enumeradas anteriormente, están disponibles los siguientes métodos.

- `setItems($items)` : establece varios items a la vez, sobrescribiendo cualquier item que figurase anteriormente en el objeto. `$items` debe ser un array o un objeto `Traversable` .

- `setItem($item, $id = null)` : establece un item individual, opcionalmente puede pasar un identificador explícito. Sobreescribe el item si ya existe en la colección. Los items válidos incluyen a arrays asociativos, objetos implementando `toArray()` , o cualquier objeto con propiedades públicas.

- `addItem($item, $id = null)` : añade un item individual, opcionalmente puede pasar un identificador explícito. Generará una excepción si el item ya existe en la colección. Los items válidos incluyen a arrays asociativos, objetos implementando `toArray()` , o cualquier objeto con propiedades públicas.

- `addItems($items)` : agrega múltiples items a la vez, añadiendolos a cualquiera de los items actuales. Generará una excepción si alguno de los nuevos items tiene un identificador concordante a un identificador ya existente en la colección. `$items` debe ser un array o un objeto `Traversable` .

- `getItems()` : recupera todos los items como un array de arrays.

- `hasItem($id)` : determina si un item con el identificador dado existe en la colección.

- `getItem($id)` : recupera un item con el identificador dado de la colección; el item retornado será un array asociativo. Si ningún item coincide, se devolverá un valor `NULL`.

- `removeItem($id)` : elimina de la colección un item con el identificador dado.

- `clearItems()` : elimina todos los items de la colección.

- `setIdentifier($identifier)` : establece el nombre del campo que representa el identificador único para cada item en la colección.

- `getIdentifier()` : recupera el nombre del campo identificador.

- `setLabel($label)` : establece el nombre de un campo para ser utilizado como la etiqueta a mostrar para un item.

- `getLabel()` : recupera la etiqueta del nombre del campo.

- `toArray()` : enviar el objeto a un array. Como mínimo, el array contendrá las claves 'identifier', 'items', y 'label' si una etiqueta de campo ha sido establecida en el objeto.

- `toJson()` : enviar el objeto a una representación JSON .