Deshabilitar controles de formulario con el API de Velneo

En cualquier aplicación empresarial donde se maneja información y permisos de lectura y escritura de la misma es necesario gestionar de forma sencilla los controles de los formularios y su estado de edición, es decir que estén habilitados o deshabilitados según los criterios de configuración, usuario o circunstancias que se produzcan durante la ejecución. En esta vitamina vamos a aprender a deshabilitar controles de formulario con el API de Velneo.

La solución propuesta en esta vitamina permite con una sola instrucción habilitar o deshabilitar todos los controles de un formulario, teniendo en cuenta aspectos importantes como que cuando deshabilitamos los controles no lo haremos a las vistas de datos (rejillas, casilleros, árboles, etc.) pues muestran información por la que debemos dejar al usuario moverse y cuyo control de permisos de edición se hará en el propio objeto.

Para que el usuario puede consultar toda la información del formulario tampoco debemos deshabilitar los separadores de pestañas (subformularios), ni las pilas ni cajas de formularios, tampoco los splitter ni las cajas de grupo. Si quieres cambiar alguno de estos criterios sólo tienes que revisar el array de tiposEnabled de la función deshabilitarControles() añadiendo o quitando los que te interesen. En la documentación de la clase VMainWindow encontrarás el enum de tipos de controles.

Deshabilitar todos los controles con una instrucción Velneo

Para implementar esta vitamina sólo tienes que hacer lo siguiente. Añade el código de las funciones deshabilitaControles() y habilitaControles() en un fichero JavaScript en el directorio de scripts. Es conveniente que tengas un repositorio de funciones JavaScript en el proyecto de datos o aplicación más bajo en el árbol de herencia, para que pueda ser usado desde todos los formularios de tus aplicaciones.

En cada formulario puedes ejecutar el siguiente código en el manejador de evento Post-inicializado o en el punto de ejecución donde te interese ya que al ejecutar la función deshabilitaControles( formulario ) estarás haciéndolo con una sola instrucción a todos los controles del formulario sean del tipo que sean.

#include "3b3uk7ol.vca/js/controlesFormulario.js"

// ----------------------------------------------------------------------
// Deshabilita los controles del formulario
// ----------------------------------------
var formulario = theRoot.dataView();
deshabilitaControles( formulario );

// Se habilita individualmente el botón Habilitar controles
var botonHabilita = formulario.control( "BTN_HAB_CTL" );
botonHabilita.enabled = true;

Recuerda que la primera línea con el #include debes sustituirla por la del fichero JavaScript que hayas añadido en tu repositorio con las funciones deshabilitaControles() y habilitaControles(). Esto puedes hacerlo usando el botón «#i» Asistente: #include otro JavaScript de la toolbar del editor de scripts.

En ese manejador de evento, tras deshabilitar todos los controles, habilito el botón habilitar controles. Es decir, que tras ejecutar ese función genérica siempre podemos habilitar individualmente los controles que nos interesen.

Para habilitar los controles de un formulario, tan sólo tienes que ejecutar este código.

#include "3b3uk7ol.vca/js/controlesFormulario.js"

// ----------------------------------------------------------------------
// Habilita los controles del formulario
// -------------------------------------
var formulario = theRoot.dataView();
habilitaControles( formulario );

A continuación está el código de las funciones deshabilitaControles() y habilitaControles() que debes añadir en un fichero JavaScript del directorio de scripts de tu proyecto de datos o aplicación.

// --------------------------------------------------------------------------------
// Deshabilita los controles del formulario
//
// Parámetros:
//     - formulario: Objeto de la clase VFormDataView con el formulario a procesar
// --------------------------------------------------------------------------------
var deshabilitaControles = function ( formulario )
{
    if ( formulario )
    {       
        var tiposEnabled = [ VMainWindow.WTypeDataView, VMainWindow.WTypeMdiView, 
                             VMainWindow.WTypeWebView, VMainWindow.WTypeTabWidget,
                             VMainWindow.WTypeStackedWidget, VMainWindow.WTypeToolBox,
                             VMainWindow.WTypeSplitter, VMainWindow.WTypeGroupBox ];

        var numControles = formulario.controlCount();
        for ( var numControl = 0; numControl < numControles ; numControl++ )
        {
            // Si el control es del tipo de adecuado se deshabilita
            var control = formulario.control( numControl );
            if ( control )
            {
                tipo = theMainWindow.widgetType( control );
                if ( tiposEnabled.indexOf( tipo ) === -1 )
                {
                    control.enabled = false;
                };
            };
        };
    };
};

// --------------------------------------------------------------------------------
// Habilita los controles del formulario
//
// Parámetros:
//     - formulario: Objeto de la clase VFormDataView con el formulario a procesar
// --------------------------------------------------------------------------------
var habilitaControles = function ( formulario )
{
    if ( formulario )
    {    
        var numControles = formulario.controlCount();
        for ( var numControl = 0; numControl < numControles; numControl ++ )
        {
            var control = formulario.control( numControl );
            
            if ( control )
            {
                control.enabled = false;
            };
        };
    };
};

Funciones configurales o personalizadas

Estas funciones que hemos visto son genéricas, pero a partir de ellas podemos crear nuestras propias funciones que habiliten o deshabiliten controles en base a una configuración que puede estar guardada en una tabla o a criterios personalizados en base al usuario, sus grupos de usuario, etc.

Es decir, que la función puede leer información de los identificadores de controles a deshabilitar o habilitar en un momento dado y aplicarlos de forma automática. Por este motivo es tan importante que seamos estrictos a la hora de poner los identificadores de los controles en los formularios de nuestras aplicaciones.

Ventajas y desventajas del API de Velneo respecto al CSS

Esta vitamina demuestra que deshabilitar y habilitar opciones con el API de Velneo y JavaScript es muy potente. En la próxima vitamina 9 veremos lo sencillo que resulta deshabilitar y habilitar controles mediante CSS. A continuación identifico algunas ventajas de hacerlo mediante el API de Velneo y JavaScript o con CSS:

Ventajas de hacerlo con el API de Velneo JavaScript:

• Muy configurable y personalizable mediante programación.
• Muy potente al permitir aplicarlo a todas las propiedades y funciones.
• Código muy reutilizable y de aplicación directa, no en cascada.

Ventajas de hacerlo con CSS:

• Más sencillo de aplicar.
• Se aplica en cascada a todos los formularios que se abran desde aquel en el que se haya aplicado el estilo.
• Permite individualizar el estilo de múltiples controles a la vez