Cómo Crear una Región de Búsquedas Personalizada en Oracle APEX 5.1

Por Clarisa Maman Orfali Oracle ACE
Publicado en Enero 2018


En este artículo quiero compartir una de las tantas formas de crear una región de tipo búsquedas personalizada en nuestra aplicación en Oracle Application Express 5.1.

Al finalizar este artículo obtendrás una página como la que se visualiza abajo:


Para este demo vamos a utilizar las siguientes tablas: EMP y DEPT.

En la tabla EMP he agregado la siguiente columna:

  • ACTIVE – Varchar2(1)

En esta columna colocaremos Y o N para representar si el empleado está activo o no.


En la tabla DEPT he agregado la siguiente columna:

  • SHORT_DNAME – Varchar2(2)

En esta columna colocaremos las 2 letras iniciales de cada registro de la columna DNAME:

  • ACCOUNTING = AC
  • RESEARCH = RE
  • SALES = SA
  • OPERATIONS = OP

Nota: trabajo de esta forma solo por simplicidad, por ello agrego la columna con los nombres cortos. Hay otras formas de capturar por ejemplo las dos primeras letras de una cadena usando la función SUBSTR.




Crear Página del Informe/Pantalla de Empleados


Ingresamos a la página de inicio de nuestra aplicación demo y creamos la página del Informe interactivo de Empleados con su respectivo formulario de carga de datos usando el asistente: “Informe con formulario en tabla”.


Accedemos al Diseñador de Páginas de la página del informe interactivo, en mi caso la página 2.

Seleccionamos la Región “Reporte 1” del informe interactivo y en propiedades seleccionamos:

  • En la sección Identificación
    • Título: Reporte Cards
    • Tipo: Informe Clásico
  • En la sección Apariencia
    • Plantilla: Blank with Attributes

Seleccionamos Atributos del Informe Clásico en el panel izquierdo de Presentación de Página.

  •  En la sección Apariencia
    • Tipo d Plantilla: Tema
    • Plantilla: Cards
  • En la sección Opciones de la Plantilla:
    • General: Check en Apply Theme Colors
    • Style: Featured
    • Icons: Display Initials
    • Layout: 3 Columns
    • Body Text: Auto
    • Animation: Color Fill

Guardamos los cambios y ejecutamos la página.


Como podemos ver en la imagen, esta plantilla Cards tiene varias variables de sustitución, el cual debemos reemplazar con las columnas en nuestra consulta SQL del informe clásico.

Las variables de sustitución que necesitamos reemplazar en la consulta SQL son las siguientes: 

  #CARD_INITIALS#
  #CARD_TITLE#
  #CARD_TEXT#
  #CARD_SUBTEXT#

Cada variable de sustitución nos indica en qué posición de la plantilla cards se mostrará la información de la columna seleccionada.


Para la asignación de las variables de sustitución a las columnas de nuestra tabla EMP, vamos a editar la consulta SQL del informe clásico, reemplazando dicha consulta SQL por la siguiente:

  SELECT e.empno,
  e.ename card_title,
  e.job card_text,
  e.mgr,
  e.hiredate,
  e.sal,
  e.comm,
  d.dname,
  d.short_dname card_initials,
  d.loc card_subtext,
  apex_util.prepare_url('f?p='||:APP_ID||':3:'||:APP_SESSION||':::3:P3_EMPNO:'||e.empno) card_link
  FROM Emp e, Dept  d
  WHERE e.deptno =  d.deptno
  ORDER BY  e.deptno

Guardamos y ejecutamos la página.


Como visualizamos en la imagen las variables de sustitución, Initials, Title, Text y SubText se muestran con el contenido de las columnas seleccionadas en la consulta SQL de la tabla EMP.

Cuando usamos la plantilla de tipo Cards para nuestro informe clásico, no contamos con una barra de búsquedas como cuando usamos el informe clásico o interactivo con la plantilla Standard, por ello si queremos encontrar un empleado con ciertas características debemos crear nuestra propia región de búsquedas.




Crear Región de Búsqueda Personalizada


Antes de todo necesitamos preparar nuestra página para tener una lateral que nos permita colocar los filtros de búsqueda visibles en nuestra página.

Para ello, vamos a cambiar de plantilla de página, en vez de usar la plantilla “Valor por Defecto de Tema” vamos a seleccionar “Left Side Column”, de ese modo cambia el layout de nuestra página agregando una columna en la izquierda del cuerpo de la página.


Creamos una nueva región de tipo estática que la llamaremos Buscar y le asignaremos la plantilla “Blank with Attributes”. Esta región se ubicará debajo del informe de tipo Cards y no es allí donde queremos que la región se encuentre.

Desde el panel de Presentación del diseñador de páginas no podemos ver la zona de la Left Column, por ello necesitamos seleccionar la región desde la ficha de Diseño y arrastrarla con el mouse a la sección Left Column, una vez adentro soltamos la tecla el mouse.


Una vez que la región se encuentra en la Left Column podemos visualizarla desde el panel de Presentación.




Crear Listas de Valores Dinámicas y Estáticas


Ante todo, necesitamos crear las Listas de Valores dinámicas para las columnas ENAME, JOB de la tabla EMP y las columnas DNAME y LOC de la tabla DEPT.

Lo hacemos desde Componentes Compartidos: Listas de Valores: Crear.

  • LISTA_ENAME
  • LISTA_JOB (usar SELECT DISTINCT)
  • LISTA_DNAME
  • LISTA_LOC

Además, vamos a crear una Lista de Valores estática para mostrar si está activo o no el Empleado, el cual se mostrará la etiqueta Activo y devolverá Y, y se mostrará la etiqueta Inactivo y devolverá la N.

  • LISTA_ACTIVO



Crear Elementos de Página en la Región de Búsquedas


En esta sección necesitamos crear todos los elementos que conformaran la región de búsquedas de nuestra página.

Ingresamos al diseñador de páginas de la página 2 y seleccionamos la región “Buscar”.


Creamos el elemento de página P2_SEARCH

 

  • En la sección Identificación
    • Nombre: P2_SEARCH
    • Tipo: Campo de Texto
  • En la sección Etiqueta
    • Etiqueta: en blanco
  • En la sección Apariencia
    • Plantilla: Hidden
    • Opciones de Plantilla
      • General: Stretch Form Item
      • Size: Large
      • Top Margin: Medium
      • Left Margin: Medium
      • Right Margin: Medium
    • Clases CSS de ícono: fa-search
    • Marcador de posición de valor: Buscar Empleados
  • En la sección Validación
    • Longitud Máxima: 500

Creamos el elemento de página P2_DNAME

  • En la sección Identificación
    • Nombre: P2_DNAME
    • Tipo: Lista de Selección
  • En la sección Etiqueta
    • Etiqueta: Departamento
  • En la sección Apariencia
    • Plantilla: Optional - Above
    • Opciones de Plantilla
      • General: Stretch Form Item
      • Left Margin: Medium
  • En la sección Lista de Valores
    • Tipo: Componente Compartido
    • Lista de Valores: LISTA_DNAME
    • Mostrar Valores Adicionales: No
    • Mostrar Valor Nulo: Sí
    • Valor de Visualización Nulo: - ALL -
    • Valor de Retorno Nulo: 0

Creamos el elemento de página P2_JOB

  • En la sección Identificación
    • Nombre: P2_JOB
    • Tipo: Casilla de Control
  • En la sección Etiqueta
    • Etiqueta: Función
  • En la sección Apariencia
    • Plantilla: Optional - Above
    • Opciones de Plantilla
      • Left Margin: Medium
    • Clases CSS: referencia_funcion_box
  • En la sección Lista de Valores
    • Tipo: Componente Compartido
    • Lista de Valores: LISTA_JOB
    • Mostrar Valores Adicionales: No
    • Mostrar Valor Nulo: No
  • En la sección Ayuda
    • Texto de Ayuda en Línea (construimos el botón con HTML y CSS)
	<button class="t-Button  t-Button--small"
	 id="funcion_check_box"  type="button">Check All</button>


Creamos el elemento de página P2_ACTIVO

 

  • En la sección Identificación
    • Nombre: P2_ACTIVO
    • Tipo: Casilla de Control
  • En la sección Etiqueta
    • Etiqueta: ¿Empleado Activo?
  • En la sección Apariencia
    • Plantilla: Optional – Above
    • Opciones de Plantilla
      • Left Margin: Medium
    • Clases CSS: referencia_estatus_box
  • En la sección Lista de Valores
    • Tipo: Componente Compartido
    • Lista de Valores: LISTA_ACTIVO
    • Mostrar Valores Adicionales: No
    • Mostrar Valor Nulo: No
  • En la sección Ayuda
    • Texto de Ayuda en Línea (construimos el botón con HTML y CSS)
	<button class="t-Button  t-Button--small" id="estatus_check_box"
  	type="button">Check All</button>

    • Texto de Ayuda: Check Activo / Inactivo. Si un Empleado está activo o inactivo usted verá el resultado al hacer check en la casilla.

Creamos el Botón RESET

  • En la sección Identificación
    • Nombre del Botón: RESET
    • Etiqueta: Reset
  • En la sección Diseño
    • Posición del Botón: Parte Inferior de la Región
    • Alineación Horizontal: Derecha
  • En la sección Apariencia
    • Plantilla: Text with Icon
    • Directa: No
    • Opciones de Plantilla
      • Size: Large
      • Icon Position: Left
    • Clases CSS de Icono: fa-undo-alt
  • En la sección Avanzada
    • Identificador Estático: reset_button



Modificar la Consulta SQL de Origen del Reporte de Cards


Ingresamos a la consulta SQL del reporte de tipo cards y agregamos la cláusula WHERE para los diferentes filtros.

  SELECT e.empno,
  e.ename  card_title,
  e.job card_text,
  e.mgr,
  e.hiredate,
  e.sal,
  e.comm,
  d.dname,
  d.short_dname  card_initials,
  d.loc  card_subtext,
  apex_util.prepare_url('f?p='||:APP_ID||':3:'||:APP_SESSION||':::3:P3_EMPNO:'||e.empno)  card_link
  FROM Emp e, Dept  d
  WHERE e.deptno = d.deptno
  AND (:P2_SEARCH  is null or instr(upper(e.ename),upper(:P2_SEARCH)) > 0)
  AND  (NVL(:P2_DNAME,'0')= '0' OR :P2_DNAME = d.deptno)
  AND (:P2_JOB is  null or ':'||:P2_JOB||':'like '%:'|| e.job|| ':%') 
  AND (:P2_ACTIVO  is null or ':'||:P2_ACTIVO||':'like '%:'|| e.active|| ':%') 
  ORDER BY  e.deptno



Crear Funcionalidad en los Filtros con Acciones Dinámicas


Hay muchas maneras diferentes de implementar la funcionalidad en los elementos de página para filtrar la información de nuestro reporte. En esta oportunidad vamos a trabajar con acciones dinámicas el cual pienso que es muy fácil de crear estas funcionalidades porque lo hacemos en forma declarativa y sin grandes cantidades de código.

Elemento P2_SEARCH

Este elemento SEARCH es un campo de texto y la idea es que el reporte de cards se vaya filtrando a medida que el usuario ingresa el texto de búsqueda del nombre del empleado dentro del campo. Para manejar esto vamos a crear una acción dinámica que se dispare con el evento de Liberación de Tecla (Key Release) con dos acciones verdaderas.

Desde el panel de Presentación, seleccionamos el elemento P2_SEARCH y con el botón derecho del mouse seleccionamos “Crear Acción Dinámica”.

Acción Dinámica

  • En la sección Identificación
    • Nombre: Key Release – campo SEARCH
  • En la sección Cuando
    • Evento: Liberación de Tecla
    • Tipo de Selección: Elementos
    • Elementos: P2_SEARCH

Acción Verdadera

  • En la sección Identificación
    • Acción: Ejecutar Código PL/SQL
  • En la sección Configuración
    • Código PL/SQL: NULL;
    • Elementos a Ejecutar: P2_SEARCH

Creamos otra Acción Verdadera dentro del elemento P2_SEARCH

  • En la sección Identificación
    • Acción: Refrescar
  • En la sección Elementos Afectados
    • Tipo de Selección: Región
    • Región: Reporte Cards

Guardamos los cambios y probamos la búsqueda de nombre de Empleados en el campo SEARCH.

Ahora vamos a crear una acción dinámica que refresque los resultados tanto cuando usamos la lista de selección del nombre de los departamentos como las casillas de control de funciones y si el empleado está activo o no en la organización.

Para ello vamos a la ficha de Acciones Dinámicas en el panel de la izquierda. Seleccionamos el evento Cambiar y con el botón derecho del mouse seleccionamos “Crear Acción Dinámica”.

Acción Dinámica

  • En la sección Identificación
    • Nombre: Refrescar Resultados – campos DNAME, JOB, ACTIVO
  • En la sección Cuando
    • Evento: Cambiar
    • Tipo de Selección: Elementos
    • Elementos: P2_DNAME,P2_JOB,P2_ACTIVO

Acción Verdadera

  • En la sección Identificación
    • Acción: Ejecutar Código PL/SQL
  • En la sección Configuración
    • Código PL/SQL: NULL;
    • Elementos a Ejecutar: P2_DNAME,P2_JOB,P2_ACTIVO

Creamos otra Acción Verdadera

  • En la sección Identificación
    • Acción: Refrescar
  • En la sección Elementos Afectados
    • Tipo de Selección: Región
    • Región: Reporte Cards

Guardamos los cambios y probamos los filtros de nombre de departamento, funciones y activo.




Crear Acción Dinámica del botón Reset


Acción Dinámica

  • En la sección Identificación
    • Nombre: Limpiar Resultados
  • En la sección Cuando
    • Evento: Clic
    • Tipo de Selección: Botón
    • Botón: RESET

Acción Verdadera

  • En la sección Identificación
    • Acción: Borrar
  • En la sección Elementos Afectados
    • Tipo de Selección: Elementos
    • Elementos: P2_SEARCH,P2_DNAME,P2_JOB,P2_ACTIVO



Crear Acción Dinámica para los botones “Check All”


En esta sección no vamos a trabajar con acciones dinámicas que se relacionan a un elemento o a un botón de nuestra página, los cuales son muy fáciles de identificar quién es el que dispara el evento de la acción dinámica, así sea un clic, un cambio de un elemento, etc.

En este caso vamos a trabajar con un Selector de jQuery que nos va a permitir a nosotros identificar quién es el que dispara el evento.

A menudo las acciones dinámicas actúan sobre alguna entrada del usuario o alguna acción del usuario, por ejemplo, un valor de un elemento cambia, o un clic del ratón, una pulsación de tecla, etc.  el elemento de disparo es el elemento o los elementos que hace que la acción dinámica se dispare.

Sin embargo, cuando la acción dinámica utiliza un selector de jQuery para el tipo de selección, no podemos identificar el elemento el cual dispara el evento porque la acción dinámica no está asociada a ningún elemento.

Como nuestros botones “Check All” están construidos a base de HTML y CSS, no están asociados a ningún elemento de página ni a ningún botón, por ello es que usamos el Selector de jQuery.



Crear Acciones Dinámicas para el botón “Check All” - Elemento P2_JOB

Creamos una Acción Dinámica desde la ficha de Acciones Dinámicas del Panel de la izquierda seleccionamos el evento Clic con el botón derecho del mouse y seleccionamos “Crear Acción Dinámica”.

Acción Dinámica

  • En la sección Identificación
    • Nombre: Check All - Funciones
  • En la sección Cuando
    • Evento: Clic
    • Tipo de Selección: Selector de jQuery
    • Selector de jQuery: #funcion_check_box
  • En la sección Condición de Cliente
    • Tipo: Expresión JavaScript
    • Expresión JavaScript:
       $(this.triggeringElement).text() === "Check All"

Acción Verdadera

  • En la sección Identificación
    • Acción: Ejecutar Código JavaScript
  • En la sección Configuración
    • Código:
      - $(".referencia_funcion_box  input[type=checkbox]").prop('checked', true);
      - $(this.triggeringElement).text('Uncheck All');

Creamos otra Acción Verdadera

  • En la sección Identificación
    • Acción: Refrescar
  • En la sección Elementos Afectados
    • Tipo de Selección: Región
    • Región: Reporte Cards

Nota: En nuestro Reporte de Cards necesitamos colocar el identificador estático como CARDS.


Crear Acción Falsa

  • En la sección Identificación
    • Acción: Ejecutar Código JavaScript
  • En la sección Configuración
    • Código:
      $(".referencia_funcion_box 
      input[type=checkbox]").prop('checked', false); 
      $(this.triggeringElement).text('Check  All');

Crear otra Acción Falsa

  • En la sección Identificación
    • Acción: Refrescar
  • En la sección Elementos Afectados
    • Tipo de Selección: Región
    • Región: Reporte Cards


Crear Acciones Dinámicas para el botón “Check All” - Elemento P2_ACTIVO

Creamos una Acción Dinámica desde la ficha de Acciones Dinámicas del Panel de la izquierda seleccionamos el evento Clic con el botón derecho del mouse y seleccionamos “Crear Acción Dinámica”.

Acción Dinámica

  • En la sección Identificación
    • Nombre: Check All - Activo
  • En la sección Cuando
    • Evento: Clic
    • Tipo de Selección: Selector de jQuery
    • Selector de jQuery: #estatus_check_box
  • En la sección Condición de Cliente
    • Tipo: Expresión JavaScript
    • Expresión JavaScript:
      $(this.triggeringElement).text() === "Check All"

Acción Verdadera

  • En la sección Identificación
    • Acción: Ejecutar Código JavaScript
  • En la sección Configuración
    • Código:
      $(".referencia_estatus_box  
      input[type=checkbox]").prop('checked', true);
      $(this.triggeringElement).text('Uncheck All');

Creamos otra Acción Verdadera

  • En la sección Identificación
    • Acción: Refrescar
  • En la sección Elementos Afectados
    • Tipo de Selección: Región
    • Región: Reporte Cards

Crear Acción Falsa

  • En la sección Identificación
    • Acción: Ejecutar Código JavaScript
  • En la sección Configuración
    • Código: $(".referencia_estatus_box input[type=checkbox]").prop('checked', false);
      $(this.triggeringElement).text('Check All');

Crear otra Acción Falsa

  • En la sección Identificación
    • Acción: Refrescar
  • En la sección Elementos Afectados
    • Tipo de Selección: Región
    • Región: Reporte Cards


De este modo tenemos finalizada nuestra región de búsquedas personalizada en nuestra página demo.

Podemos crear tantos elementos de página como necesitemos para buscar información en nuestro reporte.

Lo que debemos tener en cuenta es agregar cada uno de los filtros en la cláusula WHERE de la consulta SQL del reporte para que se filtre la información que se busca en el reporte.



Clarisa Maman Orfali es fundadora y CEO de ClarTech Solutions Inc. Se ha convertido en Oracle ACE hace algunos años, tiene más de 15 años de experiencia en el desarrollo y la capacitación en tecnologías de la información. Hace unos años descubrió la belleza de Oracle Application Express (APEX) y se ha especializado en esa área. Ella también es una Co-Fundadora y Directora del Argentina Oracle User Group (AROUG) y ha participado activamente en la organización de grandes y populares eventos. Ella tiene una gran pasión por las tecnologías de Oracle y quiere ampliar esa pasión e influencia transfiriendo su conocimiento y experiencia a la totalidad de las comunidades de Oracle América Latina y en todo el mundo.

Este artículo ha sido revisado por el equipo de productos Oracle y se encuentra en cumplimiento de las normas y prácticas para el uso de los productos Oracle.