Cuadro

Un ei\_cuadro es una grilla de registros pensados para visualización. Es común que cada uno de estos registros tenga identidad propia, por lo que el cuadro permite seleccionarlo a través de eventos.

toba_ei_cuadro

ei_cuadro

Definición

En la definición del cuadro se incluye:

• Columnas clave: Aquí se listan las clave del registro, si es que la tiene. Es de especial utilidad para cuando se desean incluir eventos asociados a los registros (por ejemplo seleccion). A estos eventos se les enviará sólo el contenido de estas columnas en un arreglo.

• Paginar: Establece si el cuadro podrá ser visualizado en varias páginas diferentes, función especialmente útil cuando se espera que el conjunto de datos a mostrar sea extenso.

• Ordenar: Indica si el usuario tiene posibilidad de ordenar el conjunto de datos a partir de alguna columna.

• EOF: El EOF se muestra cuando no hay ningún registro en la carga, existe un mensaje por defecto asociado, éste puede ser modificado o directamente ocultado al cliente.

Configuración

Para establecer los datos a mostrar en el cuadro, es necesario configurarlo, desde un CI se debería escuchar la callback conf__cuadro. En este método el cuadro espera recibir los datos en formato RecordSet

    <?php
        function conf__cuadro(toba_ei_cuadro $cuadro)
        {
           $datos = array(
                array('id' => 1, 'importe' => 100),
                array('id' => 3, 'importe' => 412),
            );
            $cuadro->set_datos($datos);
        }
    ?>

Paginado

Si en la definición del cuadro se especifica que podrá ser paginado, además del número de registros por página es necesario seleccionar un tipo de paginado:

• Propio: Es la opción más adecuada cuando el conjunto de registros a mostrar es pequeño, y por lo tanto el hecho de que el CI entregue al cuadro el total de los datos no representa una sobrecarga considerable. En este caso la lógica del paginado es propia del cuadro, y por lo tanto no se requieren consideraciones especiales a la hora de aplicarlo.

• A cargo del CI: Esta alternativa permite que el CI entregue la cantidad total de registro junto los datos parciales al cuadro mediante los métodos toba_ei_cuadro::set_total_registros y toba_ei_cuadro::set_datos respectivamente. Para poder obtener esta información, el CI generalmente necesita saber el toba_ei_cuadro::get_tamanio_pagina y la toba_ei_cuadro::get_pagina_actual.

Por ejemplo si cargarmos el cuadro a partir de una SQL:

    <?php
        function conf__cuadro($cuadro)
        {
            //--- Le informa al cuadro el total de registros
            $sql = "SELECT count(*) as total FROM tabla";
            $totales = toba::db('proyecto')->consultar($sql);
            $cuadro->set_total_registros($totales[0]['total]);

            //--- Le informa al cuadro los datos de la página actual
            $tamanio_pagina = $cuadro->get_tamanio_pagina();
            $offset = ($cuadro->get_pagina_actual() - 1) * $tamanio_pagina;
            $sql = "SELECT id,importe FROM tabla LIMIT $tamanio_pagina OFFSET $offset";
            $datos = toba::db('proyecto')->consultar($sql);
            $cuadro->set_datos($datos);
        }
    ?>

Ordenamiento

Cuando desde el editor se activa la posibilidad de ordenamiento en el cuadro, se permite al usuario seleccionar un orden Ascendente o Descendente en una columna. El ordenamiento de los datos puede estar a cargo de:

• El CI contenedor. Si así se decide se debe escuchar el evento evt__idcuadro__ordenar que recibe como parametro un arreglo conteniendo el sentido y la columna del orden. Por ejemplo: array('sentido' => 'asc', 'columna' => 'importe');. Estas opciones deberían incidir en el mecanismo de recepción de datos (típicamente el ORDER BY de una consulta SQL).

• El mismo cuadro: En caso que el evento no se escuche, el cuadro tomará la iniciativa de ordenar por sí mismo el set de datos. Para esto debe tener el conjunto completo de datos. Si por ejemplo el cuadro está páginado y sólo se carga la página actual, el cuadro sólo podrá ordenar esa página.

Modelos de evento

El cuadro posee el modelo de eventos seleccion con un evento con el mismo nombre. El evento selección es uno que se adhiere a nivel de registro, como parámetro envía los valores de las columnas claves del registro seleccionado en forma de arreglo asociativo. Esta selección cambia el estilo visual de la fila seleccionada, es responsabilidad del contenedor el determinar cuando este estilo deja de aplicar (porque por ejemplo se cancelo su edición). Para esto existe un método toba_ei_cuadro::deseleccionar asociado al cuadro.

Cuando se agregan eventos particulares se puede especificar que el evento es a nivel de una fila y no global del cuadro con la propiedad sobre_fila. Esto va a permitir que el evento sea lanzado de manera similar al seleccion, es decir con las claves de la fila desde donde se lanzó el evento. A manera gráfica estos eventos van a ser posicionados a un lado de cada fila del cuadro.

Filtrado de eventos por fila

La presencia o ausencia de un evento (a nivel de fila y no global) puede depender del contenido de cada fila. Para controlar el comportamiento de este tipo de eventos debe existir un método con el nombre conf_evt__idcomp__nombreevento. El método recibe como parámetro el evento y es posible por ejemplo anular el evento en esta fila

    <?php
        function conf_evt__cuadro__eliminar(toba_evento_usuario $evt, $fila)
        {
            //---En caso de tener una clave multiple, hay que hacer un explode para poder dividirla
            list($proyecto, $usuario) = explode(apex_qs_separador, $evt->get_parametros());
            if ($usuario == toba::usuario()->get_id()) {
                $evt->anular(); 
            }
        }
    ?>

Cortes de Control

Los Cortes de Control permiten agrupar las filas a partir de campos con valores comunes. Su finalidad es parcializar los datos para poder visualizarlos en un modo más comprensible, generalmente en un reporte.

Cada corte requiere determinar:

• Campos del corte: Campos que se utilizan para la agrupación. Por ejemplo si es un listado de localidades y todas las localidades tienen una zona, un campo de corte puede ser cod_zona

• Campos descripción del corte: Se utilizan para mostrar una descripción entendible al usuario del corte. En el caso de la zona seguramente existe un campo zona_nombre candidato a la descripción.

A partir de la version 1.5 de Toba, los cortes de control pueden colapsarse dinámicamente en runtime, el esquema es similar al que se utiliza con los eventos en un cuadro u otro componente. Se debe definir un método conf__cc_inicio_colapsado en el contenedor del cuadro el cual será utilizado como callback para determinar si el corte de control debe ser colapsado o no. El mismo recibe como parámetro la clave del nodo en cuestión.

Para establecer una sumarización por una columna específica se necesita definirla en la solapa Columnas del editor del cuadro.

@TODO: Falta explicar la extensión PHP de los cortes