Eventos de Componentes

Un evento evento representa la interacción del usuario ("El usuario presiona guardar enviando los datos de la factura") a través de un componente de interfaz. El evento sirve como medio de comunicación del cliente con el servidor, llevando los parámetros particulares del suceso.

Como se encuentra en un ambiente web, la comunicación entre cliente y servidor no es continua, se le dice desconectada. El usuario trabaja en su browser modificando la información que se visualiza en la página actual y cuando decide ir al servidor (ej. Guardar) todos los componentes de esa pantalla seguramente van a notificar los distintos sucesos que acontecieron durante su estadía en el cliente. Este es un concepto fundamental que diferencia a las aplicaciones web de las de escritorio, en donde este dialogo tiene más frecuencia y menor caudal.

toba_evento_usuario: Forma gráfica que contiene el disparador del evento (por ej. un botón) evento_ei: Estructura de datos que representa un evento en javascript.

Modelos

Cada componente posee distintos modelos de eventos que pueden ser utilizados en la definición en el editor. Por ejemplo un /ut_formulario ei_formulario tiene dos modelos, uno clásico ABM (cuatro eventos: alta, baja, modificacion y cancelar) y otro básico que sólo incluye la modificación como evento implícito, sin botón asociado.

El programador no está forzado a utilizar estos modelos, pueden crear sus propios eventos y utilizar los modelos sólo como punto inicial en la definición de los eventos.

Propiedades

Identificador: Nombre lógico del evento, determina el nombre que toman los listeners y la forma en general de referenciarlos.
Etiqueta: Es el nombre a nivel de usuario del evento, este nombre será el label del botón si se define en botonera.
Imagen: En el caso de se muestren como botones se antepone la imagen al texto del botón.
En botonera: El evento se muestra disponible como botón en el área de botonera del objeto.
Implícito: Un evento implícito se lanza cuando el usuario no explicita ningún otro evento en el componente. Por ejemplo si se cuenta con tres formularios que contienen eventos implícitos y se decide cambiar de solapa, éstos notificaran estos eventos al servidor a pesar de que el usuario no presionó ningún botón de estos formularios.
Maneja datos: Indica si el evento depende de los datos cargados, esto condiciona la validación del componente. Por ejemplo el evento cancelar no maneja_datos por lo que no es necesario validarlo, lo mismo sucede al borrar, en cambio el alta o la modificacion sí manejan datos y requieren validación.
Predeterminado: Indica que el botón se dispara en forma predeterminada al presionar la tecla ENTER (excepto dentro de un textarea o que no se tenga foco en el documento). La idea es que exista uno solo por pantalla y que sea el botón más obvio (y menos peligroso) de la pantalla. En caso de existir más de uno en una página el browser utiliza el primero en el orden del fuente HTML.
Estilo: Clase CSS a aplicar al botón que dispara el evento. Por defecto la clase css es ei-boton alineándose a la derecha en la botonera. Es posible ingresar la clase ei-boton-izq que alinea el botón a la izquierda de la botonera, o cualquier clase definida en el CSS del proyecto. Es posible ingresar más de una valor, separando las clases con un espacio.
Confirmación: Indica si el evento necesita una confirmación explícita del usuario para lanzarse. Es común encontrarlo en eliminaciones, en caso de no querer la confirmación dejarla vacía.
Ayuda: Descripción del significado del evento. Generalmente se muestra como tooltip.
Sobre Fila: Propiedad que sólo entienden aquellos objetos con múltiples filas, como el cuadro o el formulario_ml e indica que el evento opera sobre una única fila y no sobre todo el conjunto de datos. El evento se mostrará al lado de cada fila.
Pantallas: Solo aplica a eventos de un ci, determina en cuales pantallas se mostrará el evento. Otra forma de setear lo mismo es editar la pantalla y seleccionar qué eventos mostrar.
Grupos: se pueden definir varios separándolos por coma, ver más abajo sobre su utilidad.

Agrupación

A través de la propiedad Grupos es posible agrupar los eventos a los que pertenece el evento en cuestión. La conveniencia de esta funcionalidad es poder activar y desactivar conjuntos de eventos con un sólo método. Existe un servicio toba_ei::set_grupo_eventos_activo que permite definir el grupo activo en tiempo de ejecución. Los componentes ei_formulario y ei_filtro poseen un comportamiento predefinido respecto de este tema:

Cuando se inicializa el elemento en se establece al grupo no\_cargado como activo.
Si se brindan datos al componente durante su configuración se establece el grupo cargado como activo.

Esta funcionalidad permite definir el comportamiento predeterminado del formulario en un ABM simple: Cuando el formulario esta vacío muestra un boton Agregar, si se le cargaron datos muestra los botones Modificación, Baja y Cancelar. También es el comportamiento normal de un filtro: Cuando se encuentra vacío muestra un botón filtrar y cuando esta cargado un botón filtrar y otro cancelar.

Listeners

Escuchar un evento es definir un método en el multi_etapa ci contenedor del componente. Este método denominado listener será invocado informando a través de parámetros el contexto del evento. El nombre de este método necesita estar definido con el prefijo evt__ seguido por el id del objeto origen, con el nombre de evento como sufijo __evento. Por ejemplo en el caso de un alta en un formulario form se dispara el evento alta, y se puede escuchar desde su contenedor definiendo el siguiente método:

    <?php
        function evt__form__alta($registro)
        {
            //Código que reacciona al evento
        }
    ?>

En caso de que este método no sea definido, el evento queda sin atrapar, informándose en el logger. Cuando el evento es lanzado por el mismo CI, el id del componente origen es omitido, por ejemplo el evento procesar del CI se escucha de la siguiente manera:

    <?php
        function evt__procesar()
        {
            //Código que reacciona al evento
        }
    ?>

La forma de atrapar estos eventos en javascript es similar, sólo que siempre se utiliza esta última notación evt__evento. Por ejemplo se puede atrapar el evento cancelar de un formulario justo cuando el usuario lo invoca en javascript:

    <?php
    class extension_formulario extends toba_ei_formulario
    {
        function extender_objeto_js()
        {
            //--Agrega una confirmación al cancelar en caso de que algo dinamico pase...
            echo "
                {$this->objeto_js}.evt__cancelar = function() {
                    if (condicion_dinamica) {
                        return confirm('¿Esta seguro?');
                    } else {
                        return true;
                    }
                }
            ";
        }   
    }
    ?>

Configuración en ejecución

Los botones,imagenes y demás propiedades de los eventos pueden ser modificados en ejecución

En PHP

Existe una clase llamada toba_evento_usuario que contiene los servicios para modificar a un evento. La forma de acceder a este objeto es a través del método toba_ei::evento($id) del componente. Por ejemplo configurando un formulario:

    <?php
    function conf_form($form)
    {
        $form->evento('modificacion')->set_etiqueta('Modificar!!!');
    }
    ?>

En Javascript

Generalmente requiere una [referencia/ExtensionesJavascript extensión del componente]. El evento en sí no tiene una API propia sino que es parte del api del ei (por ej. ocultar_boton, mostrar_boton, etc.). También se puede acceder al elemento HTML que contiene el evento con el método get_boton($id).

Acciones predefinidas

Existen acciones predefinidas que pueden ser asignadas a los eventos, esto evita tener que definir las acciones a través de listeners. Las acciones predefinidas disponibles actualmente son:

Imprimir: Solo disponible en el componente controlador de interface, imprime el ci en el cliente, utilizando el servicio Impresión HTML, opcionalmente se puede mostrar una Vista Previa de la impresión.
Vincular: permite navegar a un nuevo ítem, dentro de la misma pagina o en un popup. Crea automáticamente la URL y el tag html que lo contiene.
Respuesta al ef_popup: Disponibles en los componentes que manejan fila (cuadro y form ml), consiste en brindar la clave de la fila actual al ef que invocó el popup.

SIU-Toba

next