Todo sobre reportes interactivos – Parte 8

Sumamos una entrega más en esta serie y ya tenemos 8, en las entregas anteriores hemos visto:

• Todo sobre reportes interactivos – Parte 1. (Introducción)
• Todo sobre reportes interactivos – Parte 2. (Personalizado de atributos de región y reporte)
• Todo sobre reportes interactivos – Parte 3. (La barra de búsqueda y el menú de acciones)
• Todo sobre reportes interactivos – Parte 4. (Vistas de icono y detalle)
• Todo sobre reportes interactivos – Parte 5. (Personalización de atributos de columna)
• Todo sobre reportes interactivos – Parte 6. (Enlace a reportes interactivos con parámetros predefinidos)
• Todo sobre reportes interactivos – Parte 7. (Permitir enviar por correo o suscripciones a reportes interactivos)

En las siguientes secciones me voy a dedicar un tema más técnico sobre los reportes interactivos y les voy a mostrar cómo podemos modificar de manera programática el menú de acciones de un reporte interactivo.

Vamos a tratar los siguientes temas:

1. Marco conceptual
2. Cómo ocultar o mostrar opciones del menú de acciones
3. Cómo habilitar o deshabilitar opciones del menú de acciones
4. Cómo condicionar el que aparezcan o desaparezcan opciones del menú de acciones

Marco Conceptual

¿Cómo funciona un reporte interactivo? La respuesta rápida es: “un reporte interactivo es un motor declarativo de exploración de datos que combina SQL + Metadatos + Estado de Usuario + Javascript”. El desarrollador define una consulta (SQL) para que luego APEX construya de manera automática: filtros, ordenamiento, agrupaciones, cálculos y vistas personalizadas entre otras.

Internamente el motor toma la consulta que definiste para el reporte y de manera dinámica lo envuelve con filtros, order by, agregaciones, paginación, convirtiendo una consulta como:

SELECT *
  FROM EMP

En algo como:

SELECT *
  FROM (
    SELECT t.*, ROW_NUMBER() OVER (...) rn
    FROM (TU_QUERY) t
    WHERE ...filtros usuario...
)
WHERE rn BETWEEN :X AND :Y

Como posiblemente ya sepas, cada usuario a la hora de la ejecución del reporte, puede crear sus propios filtros, ordenar su reporte y personalizar el reporte interactivo de acuerdo a sus necesidades específicas, todas estas modificaciones se almacenan internamente para adecuarse a lo que cada usuario solicita del reporte y estos cambios pueden ser temporales (durante el tiempo de vida de la sesión) o permanentes (cuando se guardan los cambios hechos al reporte).

Con todo esto definido, cuando el usuario final llama un reporte interactivo el motor ejecuta el SQL modificado, genera JSON/HTML y presenta el resultado al usuario utilizando un widget Javascript.

Este último componente es el que nos va a permitir realizar cambios de manera programática al reporte interactivo y de una manera sencilla.

Si abrimos la consola de nuestro navegador en la pestaña donde hemos solicitado un reporte interactivo y ejecutamos:

apex.region("COMENTA").widget();

en donde “COMENTA” corresponde al nombre del identificador estático asignado a la región del reporte interactivo.

Vamos a obtener como respuesta algo como:

Object { 0: div#COMENTA_ir.a-IRR-container, length: 1 }
0: 

length: 1
: Object { jquery: "3.6.4", constructor: w(e, t), length: 0, … }

Este es el widget correspondiente al reporte interactivo, donde se define tanto su contenido como las funcionalidades del mismo.

Por supuesto, esta es la versión abreviada del mismo, porque incluirlo aquí ocuparía demasiado espacio y en realidad no es algo que nos interesa ver.

En la siguiente tabla, puedes encontrar cada una de las opciones posibles del menú de acciones, una breve explicación y cual es el identificador por medio del cual podemos referenciar dicha opción.

Los valores de la columna Identificador, los vamos a utilizar más tarde en los ejemplos que desarrollemos y te van a ser útiles cuando quieras o necesites hacer modificaciones programáticas el menú Acciones, así que te recomiendo que guardes está página en tus marcadores.

Mostrar y Ocultar opciones

-Muy bien. Ya entendemos como funcionan los reportes interactivos, empecemos entonces a ver como podemos realizar cambios en el menú Acciones.

En esta sección vamos a ver como podemos ocultar o mostrar una opción del menú acciones que se encuentra oculta.

Para conseguir esto, lo que vamos a hacer es utilizar una acción dinámica y un poco de Javascript.

Vamos a suponer que tenemos una página con un reporte interactivo que muestra comentarios, cuya región de reporte interactivo se llama precisamente Comentarios. También vamos a suponer que queremos ocultar la opción Flashback del sub-menú Datos y la opción Filas por Página del sub-menú Formato, así como la opción Dinámica del menú general.

El procedimiento que vamos a aplicar es:

1. Ingrese a la página principal de su ambiente de desarrollo APEX.
2. Ingrese a la página principal del  Creador de aplicaciones.
3. Seleccione la aplicación en la que tiene su reporte.
4. Abra en el Diseñador de páginas, la página que contiene su reporte interactivo.
5. En el paño de la izquierda, haga clic sobre la pestaña correspondiente a las Acciones Dinámicas.
6. Ahora posicione el cursor del ratón sobre la sección Perder Enfoque y haga clic con el botón derecho del ratón en la opción Crear Acción Dinámica.
7. Muévase al paño de la derecha que muestra las propiedades de la acción dinámica recién creada y realice los siguientes cambios:
   1. En Nombre, escriba OcultaAcciones, o el nombre que desee asignar a la acción dinámica.
   2. En la sección Cuando, en Tipo de Selección, seleccione Selector de jQuery.
   3. En Selector de jQuery, escriba .a-IRR-button–actions
8. Por defecto la acción dinámica crea una acción verdadera del tipo Mostrar, haga clic en ella en el paño de la izquierda de la pantalla y regrese al paño derecho para redefinir la acción verdadera.
   1. En Acción, cambie de Mostrar a Ejecutar Código Javascript.
   2. En la sección Configuración, en el atributo Código agregue el siguiente código:
      

      $(".icon-irr-flashback").parents("li").hide();$(".icon-irr-rows").parents("li").hide();$(".icon-irr-pivot").parents("li").hide();

9. Haga clic en el botón Guardar.

Como puede notar en las líneas de Javascript de arriba, estamos utilizando los valores de la columna Identificador de la tabla de la sección anterior, correspondientes a cada una de las acciones que queremos ocultar.

Si ejecuta su reporte y abre el menú Acciones, podrá comprobar que las opciones de Flashback, Resaltar y Dinámica ya no aparecen en el menú.

Las líneas de Javascript proporcionadas en el ejemplo anterior funcionan sin ningún problema cuando en la página existe un solo reporte interactivo, o bien, cuando existes más de uno pero quieres aplicar la misma regla a cada uno de ellos.

Si este no es el caso y quieres aplicar las reglas a un solo reporte lo que debes hacer diferente es lo siguiente:

1. Asignar un identificador estático a la región del reporte interactivo al que quieres aplicar las modificaciones.
2. Cambiar el código Javascript de la acción dinámica por el siguiente:

$(document).on("focusout", "#IR_TRANSACCIONES .a-IRR-button--actions", function () {

    $(".icon-irr-flashback").patents("li").hide();
    $(".icon-irr-rows").patents("li").hide();
    $(".icon-irr-pivot").patents("li").hide();

});

En el ejemplo, se está usando como identificador único de la región IR_TRANSACCIONES.

Cómo puede ver en la primera línea del código, se hace referencia a este identificador en la sentencia jQuery “$document.on …”

Con lo anterior ya cubrimos el cómo ocultar opciones, ahora veamos como podemos hacer que aparezcan aquellas opciones que se encuentran ocultas.

👉Es importante aclarar aquí, que lo que estamos haciendo hasta el momento y lo que haremos en adelante, depende de que previamente hallamos habilitado en los atributos del menú acciones todas las alternativas para poder utilizarlas.

No podemos por ejemplo mostrar un opción de menú si como desarrolladores no la habilitamos previamente en el diseñador de páginas. Esto por cuanto lo que estamos realizando es a nivel del DOM del documento y NO PODEMOS entonces agregar toda la funcionalidad relacionada con una opción del menú.

Para mostrar una opción del menú de opciones que ha sido ocultada de previo, lo que haremos básicamente es utilizar la función show del widget, el lugar de usar la función hide como hasta ahora lo hemos venido haciendo.

Dicho lo anterior, en el código que les proporcioné arriba para la acción dinámica, lo que haremos es cambiar en las líneas, la parte del código que dice “hide()” y en su lugar vamos a escribir “show()”.

Entonces, el código de la acción dinámica debería lucir como:

$(document).on("focusout", "#IR_TRANSACCIONES .a-IRR-button--actions", function () {

    $(".icon-irr-flashback").patents("li").show();
    $(".icon-irr-rows").patents("li").show();
    $(".icon-irr-pivot").patents("li").show();

});

Habilitar o deshabilitar opciones

Para mostrar y ocultar opciones utilizamos las funciones show y hide respectivamente.

En el caso que nos ocupa ahora, no existen funciones enable y disable para habilitar y deshabilitar una opción del menú de Acciones, por lo que debemos trabajar un poco más con nuestro Javascript para poder lograr ambos efectos.

Veamos primero como deshabilitar una opción del menú de acciones y, aquí me voy a limitar a proporcionar y explicar un poco el código Javascript que utilizaremos para lograrlo.

$(document).on("focusout", "#IRR_TRANSACCIONES .a-IRR-button--actions", function () {

    $(".icon-irr-flashback")
        .closest("li")
        .addClass("is-disabled")
        .attr("aria-disabled", "true")
        .css({
            "pointer-events": "none",
            "opacity": "0.5"
        });
    $(".icon-irr-filter")
        .closest("li")
        .addClass("is-disabled")
        .attr("aria-disabled", "true")
        .css({
            "pointer-events": "none",
            "opacity": "0.5"
        });
    $(".icon-irr-chart")
        .closest("li")
        .addClass("is-disabled")
        .attr("aria-disabled", "true")
        .css({
            "pointer-events": "none",
            "opacity": "0.5"
        });

});

Analicemos algunas de las líneas del código anterior.

En primer lugar, en la línea 1, puedes ve que aparece “#IRR_TRANSACCIONES”, esto corresponde al identificador estático asignado a la región del reporte interactivo sobre el que vamos a aplicar las modificaciones.

En la línea 3 vas a observar “.icon-irr-flashback”, que como recordarás es el nombre del identificador de la opción del menú acciones, es este caso la opción Flashback. Recuerda que puedes consultar estos identificadores en la tabla proporcionada en la parte superior de este artículo.

La línea 4, hace referencia a la ocurrencia más cercana del elemento “li”, en esta línea puedes usar tanto closest como parents, ambas funcionarán para nuestro cometido.

En la línea 5, estamos agregando una nueva clase al elemento “li” sobre el que estamos trabajando, si observas bien, la clase que estamos agregando es “is-disabled”.

La línea 6 le agrega el atributo “aria-disabled” al mismo elemento.

Y en las líneas 7 a 10 se le agrega al elemento las propiedades CSS para simular la apariencia de deshabilitado.

Las demás líneas repiten lo mismo para las otras opciones incluidas para deshabilitar.

Entonces, para deshabilitar uno o varios elementos, como en el ejemplo, solo debes ejecutar el procedimiento que se indicó para el proceso de ocultar, con la única diferencia de que el código Javascript que vas a utilizar es el que acabamos de analizar.

Ahora bien, ¿qué vamos a hacer si lo que queremos es habilitar nuevamente una opción previamente deshabilitada?

Lo que haremos es utilizar el siguiente código:

$(document).on("focusout", "#IRR_TRANSACCIONES .a-IRR-button--actions", function () {

    $(".icon-irr-flashback")
         .closest("li")
         .removeClass("is-disabled")
         .removeAttr("aria-disabled")
         .css({
             "pointer-events": "",
             "opacity": ""
         }); 
    $(".icon-irr-filter")
         .closest("li")
         .removeClass("is-disabled")
         .removeAttr("aria-disabled")
         .css({
             "pointer-events": "",
             "opacity": ""
         }); 
    $(".icon-irr-chart")
         .closest("li")
         .removeClass("is-disabled")
         .removeAttr("aria-disabled")
         .css({
             "pointer-events": "",
             "opacity": ""
         }); 
});

Si eres observador, habrás notado que a diferencia del código para deshabilitar, donde hacíamos “add…”, ahora estamos haciendo un “remove…” y en el caso del CSS estamos eliminando los valores que asignamos previamente y asignando valores nulos.

Y eso es todo, las opciones regresaron a la normalidad.

Uso condicional

Hemos visto ya como mostrar u ocultar las opciones del menú Acciones de manera programática. También hemos visto como habilitar o deshabilitar estas opciones, de manera que tenemos dos maneras diferentes de controlar el uso o no de las mismas al momento de la ejecución de un reporte interactivo.

Sin embargo, no siempre vamos a querer o necesitar simplemente ocultar/deshabilitar o mostrar/habilitar las opciones del menú Acciones. En la mayoría de los casos, vamos a realizar un manejo condicional de estas opciones, dependiendo de factores que van a determinar si un usuario puede o no utilizar una opción del menú Acciones. Mencionemos algunas posibles condicionales:

1. El usuario tiene asignado un rol específico.
2. EL usuario pertenece a un grupo determinado de usuarios.
3. El usuario es un usuario público o uno autenticado.

Solo por mencionar tres condicionales.

¿Qué demos hacer en este caso? Porque si utilizamos lo hasta ahora aprendido, todos los usuarios van a poder utilizar una opción o ninguno de ellos podrá hacerlo.

La respuesta claramente, es condicionar el uso (habilitar/deshabilitar o mostrar/ocultar) de la opción de acuerdo con lo que se defina para cada reporte en particular.

Aquí tenemos diferentes formas de aplicar la condicionalidad al proceso, lo que si es claro, es que necesitamos un valor que podamos evaluar para determinar si el uso de la opción es permitido o no, independientemente del método que utilicemos para permitirlo o denegarlo.

Podemos por ejemplo, manejar un elemento oculto dentro de la página que contiene el reporte interactivo. También podemos utilizar el valor de un elemento de la página, como un Switch, una casilla de control o un grupo de botones de radio, que lógicamente vamos a mostrar u ocultar dependiendo de los permisos del usuario.

Supongamos que los usuarios de nuestras aplicaciones tienen asignados diferentes roles, por ejemplo ADMIN, CONTADOR, CAJERO. Hay algunos reportes a los que tanto los usuarios CONTADOR como CAJERO van a tener acceso, pero no es conveniente que los puedan descargar o se puedan suscribir a ellos, mientras que a los usuarios con rol ADMIN si se les permite tanto descargarlos como suscribirse a ellos para recibirlos en su cuenta de correo electrónico.

Entonces, primeramente vamos a crear un elemento oculto PX_IS_ADMIN, cuyo valor no esté protegido para no tener problemas cuando lo modificamos.

Luego vamos a crear una función que verifique si el usuario proporcionado es ADMIN que va a retornar un valor ‘Y’ si el usuario tiene el rol o un valor ‘N‘ si no lo tiene, la cual vamos a utilizar para asignar un valor al elemento PX_IS_ADMIN.

Finalmente, vamos a utilizar el valor de PX_IS_ADMIN para determinar si las opciones del menú Acciones para suscripciones y descargar se van a habilitar/mostrar o no.

No me voy a detener en la creación de la función, solo voy a suponer que ya ha sido creada y se llama “usuario_administrador” y que recibe el nombre de usuario como parámetro.

Teniendo todo esto en cuenta, el proceso para configurar el menú Acciones de manera condicional es el siguiente:

1. Ingrese a la aplicación que contiene el reporte interactivo.
2. Abra en el Diseñador de Páginas, la página con el reporte interactivo.
3. En la región del reporte interactivo, cree un elemento con las siguientes características:
   1. Nombre: PX_IS_ADMIN
   2. Tipo: Oculto
   3. Protegido: Desactivado/Apagado
4. Expanda Representación Previa (Pre Rendering)
5. Ha clic con el botón derecho del ratón sobre Antes de cabecera y luego haga clic en la opción Crear Cálculo.
6. En las propiedades de Cálculo defina los siguientes valores:
   1. Nombre del elemento: PX_IS_ADMIN
   2. Consulta SQL: select usuario_administrador(:APP_USER) from dual
7. Cámbiese a la pestaña de Acciones Dinámicas y sobre Perder Enfoque, haga clic con el botón derecho del ratón y luego seleccione la opción Crear Acción Dinámica.
8. Para la acción dinámica realice los siguientes cambios:
   1. Nombre: controlarAcciones
   2. Evento: Perder Enfoque
   3. Tipo de selección: Selector jQuery
   4. Selector de jQuery: .a-IRR-button–actions
   5. Modifique la acción verdadera creada por defecto:
      1. Acción: Ejecutar código Javascript
      2. Código:
         

         $(document).on("focusout", "#IRR_TRANSACCIONES .a-IRR-button--actions", function () {    if ($v("P4_IS_ADMIN") === 'N') {        $(".icon-irr-subscription")            .closest("li")            .addClass("is-disabled")            .attr("aria-disabled", "true")            .css({                "pointer-events": "none",                "opacity": "0.5"            });        $(".icon-irr-download")            .closest("li")            .addClass("is-disabled")            .attr("aria-disabled", "true")            .css({                "pointer-events": "none",                "opacity": "0.5"            });    } else {       $(".icon-irr-subscription")            .closest("li")            .removeClass("is-disabled")            .removeAttr("aria-disabled")            .css({                "pointer-events": "",                "opacity": ""            });        $(".icon-irr-download")            .closest("li")            .removeClass("is-disabled")            .removeAttr("aria-disabled")            .css({                "pointer-events": "",                "opacity": ""            });     };});

9. Haga clic en el botón Guardar.

Observe en el código que hemos agregado un expresión “if” al código, donde preguntamos por el valor de PX_IS_ADMIN, si este valor es igual a ‘N‘ entonces deshabilitamos las opciones de suscripción y descarga, en caso contrario, las habilitamos. De esta manera, cuando la función devuelve un valor de ‘Y’, porque el usuario es administrador, las opciones se habilitan, sino, las opciones se deshabilitan.

👉 Puede usar el código para mostrar/ocultar las opciones, si lo que desea es que del todo no se muestren.

Más información

Si desea obtener más información acerca de los temas aquí tratados puede hacerlo en:

Widgets y Javascript en APEX.
Uso de Acciones Dinámicas.