Si no eres nuevo en APEX, sabes que esta herramienta utiliza para temas para armar las páginas que genera y que estos temas, están compuestos por plantillas. Y si eres nuevo en APEX y no lo sabías, acabas de aprender algo nuevo sobre APEX.
Las plantillas son una herramienta extremadamente potente en APEX, pues definen la manera en que se presentan cada uno de los elementos visibles de una página APEX, así como la parte fundamental de su funcionamiento.
Existen plantillas para páginas, regiones, campos, botones, menús; en fin, para cada elemento físico que puede agregarse a una página de su aplicación.
En la actualidad, dentro de APEX, contamos con una funcionalidad llamada “Directivas de Plantilla” y en este artículo voy a tratar de explicarte ¿qué son y para qué sirven estas directivas de plantilla”.
El artículo incluye:
Introducción
Antes de que aparecieran las directivas de plantilla, teníamos la opción de utilizar Javascript, PL/SQL, expresiones HTML, sustituciones simples y condicionamiento APEX tradicional para ayudarnos a dar formatos específicos a los diferentes elementos de una aplicación (páginas, regiones, campos, botones, menús, columnas de reportes, etc.).
Todo esto, demandaba de parte del desarrollador, conocimientos en cada una de las herramientas mencionados, así como trabajo considerable, dependiendo de lo que se quisiera o necesitara hacer para que la presentación de los elementos cumplieran con los requerimientos de los usuarios.
En la versión 21.1 de APEX, aparecieron las directivas de plantilla, de manera que no es algo nuevo, aunque en muchos casos, es poco utilizado por los desarrolladores porque no las conocen.
¿Qué son las directivas de plantilla?
De acuerdo con la documentación oficial de APEX, “Las directivas de plantilla son tokens especiales que controlan el procesamiento del texto circundante.
Se utilizan para controlar el procesamiento de los atributos que admiten cadenas de sustitución. Estas directivas solo son compatibles con los componentes de plantilla, atributos específicos de las plantillas de correo electrónico, tarjetas, cuadrículas interactivas, informes clásicos y regiones de informes interactivos. Las directivas de plantilla se procesan como parte de las sustituciones del lado del cliente o del servidor. Si un atributo admite directivas de plantilla, la ayuda del Diseñador de páginas incluye el texto «Admite directivas de plantilla del lado del servidor» o «Admite directivas de plantilla del lado del cliente».”.
Resumiendo lo anterior, las directivas de plantilla es una funcionalidad que podemos utilizar en atributos específicos (no en todos) de:
- plantillas de correo electrónico,
- tarjetas,
- cuadrículas interactivas,
- reportes interactivos,
- reportes clásicos,
- algunos otros elementos que podemos identificar por medio de la ayuda del elemento, pues están “señalados” con una leyenda que indica que se pueden utilizar directivas de plantilla en dicho elemento.
Estás directivas, básicamente nos permiten controlar como se procesa el texto de estos elementos o cadenas de sustitución.
Al final, son una forma de agregar lógica de manera sencilla y sin necesidad de escribir mucho código a los elementos de página nombrados anteriormente. Lógica que en la mayoría de los casos se procesa del lado del cliente, aunque también puede ser procesada del lado del servidor en algunas ocasiones.
Además, antes de las directivas era necesario el uso de Javascript y PL/SQL en plantillas que en la mayoría de los casos eran rígidas a la hora de realizar la presentación de los datos. En cambio ahora, con el uso de las directivas de plantilla:
- tenemos un mayor control del “frontend” de nuestras aplicaciones,
- necesitamos menos código personalizado para hacerlo,
- el rendimiento es mejor y,
- la mantenibilidad es más sencilla.
¿Cómo se definen?
La sintaxis general de las directivas es:
{ directiva/}
contenido
{ fin-directiva/}
Las directivas, de manera similar a las etiquetas HTML, tienen una etiqueta de apertura y una de cierre, las cuales están encapsuladas dentro de corchetes “{ }” y que además llevan un caracter “/” antes del corchete de cierre.
Estas directivas, son procesadas por el motor de presentación de APEX, de manera que se aplican cuando la página se está armando.
¿Para qué son útiles?
Algunos casos tipos de uso dentro de nuestras aplicaciones incluyen:
- Dashboards dinámicos. Nos permiten hacer diferenciación de colores según estados, incluir indicadores visuales.
- Reportes tipo tarjetas. Para adecuar el formato y presentar información de manera visual más que textual (uso de íconos sobre texto).
- Interfaces de usuario condicionales sin la necesidad de utilizar Javascript.
- Interfaces de chat en nuestras aplicaciones.
Y los anteriores son solo unos cuantos ejemplos que nos muestran la versatilidad en el uso de las directivas de plantilla.
De la misma manera es importante hacer notar, ¿para qué no son útiles?
Las directivas de plantilla no son útiles para:
- Incluir lógica de negocio compleja.
- Ejecutar procesos de “backend”.
- Realizar validaciones críticas.
Directivas de plantilla
Ahora que ya conocemos un poco más sobre lo que son las directivas de plantilla y para que son útiles, conozcamos las diferentes directivas que existen y podemos utilizar.
Estas directivas son:
Directiva if
Las directivas if, son directivas de condicionamiento, las cuales utilizamos para mostrar contenido basado en la evaluación del valor de un campo de página o una columna de reporte.
Ejemplos clásicos del uso de una directiva if son:
- mostrar u ocultar contenido,
- hacer cambios de estilo de manera dinámica.
Es importante recalcar que el funcionamiento de la directiva if, no es similar al de un if de PL/SQL. En el caso de los if de PL/SQL, si bien se evalúa una expresión a falso o verdadero, tenemos operadores que nos permiten por ejemplo verificar si un campo “P1_MONTO” es igual a 100, en el caso de la directiva if esto no lo podemos hacer.
Para que se comprenda mejor, es importante mencionar que en el caso de las directivas if, podemos utilizar modificadores del if, pero lo único que cambian, es la manera de valuación del valor del campo o la columna.
En la tabla de la imagen anterior (puede ampliarla si hace clic sobre la imagen), puede ver los modificadores de valuación usados por la directiva if, así como el efecto que tienen en el proceso de valuación.
Como ya habrá notado, la directiva if, básicamente evalúa el valor del campo o columna para saber si:
- existe y es verdadero
- existe
- no existe o es falso
- no existe
- no es falso
- existe y es falso
Para que quede aún más claro, podemos observar la siguiente tabla (clic en la imagen para ampliar).
Como puede observar en la tabla anterior, en donde se compara la ejecución de la directiva if, con respecto al if que ejecutaría PL/SQL, la directiva if, cuando realiza la evaluación del valor, simplemente verifica una de dos cosas:
Cuando se evalúa si la condición es verdadera:
- que el campo o columna existan
- que el valor del campo o la columna no sea nulo y que además tenga un valor diferente de ‘F’, ‘N’ o ‘0’
Si estas condiciones se cumplen, la directiva va a retornar un valor “verdadero”.
Cuando se evalúa si la condición es falsa:
- que el valor sea nulo
- que el valor sea uno de los siguientes: ‘F’, ‘N’, ‘0’
En resumen, si el valor no es nulo, ni ‘F’, ‘N’ o ‘0’, la condición se evalúa como “verdadera”.
Aclarado lo anterior, veamos la sintaxis general de la directiva if.
|
1 |
{if [!][?|=]NAME/} TEXTO_PLANTILLA_TRUE{elseif [!][?|=]NAME2/} TEXTO_PLANTILLA_ELSE_TRUE{else/} TEXTO_PLANTILLA_FALSE{endif/} |
Analicemos un poco esta sintaxis.
NAME corresponde al nombre de un campo, una columna o un atributo de componente de plantilla.
i el valor de NAME es verdadero entonces el texto TEXTO_PLANTILLA_TRUE se despliega.
Si se incluye elseif, y el valor de NAME2 es verdadero entonces el texto TEXTO_PLANTILLA_ELSE_TRUE se despliega.
Si el valor de NAME es falso, entonces el tecto TEXTO_PLANTILLA_FALSE se despliega.
Si se utiliza el modificador “!” delante de NAME (o NAME2), entonces la lógica es negada (valuamos si el valor es falso).
Si únicamente queremos verificar si un valor es nulo, agregamos el modificador “?” delante de NAME (o NAME2).
Si utilizamos el modificador “=” delante de NAME (o NAME2), se verifica si NAME no está vació y tiene un valor ‘F’, ‘N’ o ‘0’
Enfoquémonos ahora en un ejemplo.
Vamos a crear un reporte de tarjetas con la siguiente consulta:
|
1 |
SELECT empno, ename, job, deptno, salary, status, performance, CASE WHEN salary > 4000 THEN 'Y' END high_salary, CASE WHEN performance = 'HIGH' THEN 'Y' END perf_high, CASE WHEN performance = 'MEDIUM' THEN 'Y' END perf_mediumFROM demo_employees |
Básicamente, retorna los registros de los empleados en la tabla demo_employees y tres columnas adicionales “hig_salary, perf_high y perf_medium” que retornan indicadores para salarios altos (cuando son superiores a 4000) y desempeño alto o medio dependiendo del valor de la columna performance.
En un reporte de tarjetas estándar, sin hacer muchos cambios y simplemente formateando el cuerpo de la tarjeta para que muestre “Salario: $999,990”, el reporte final luciría como lo muestra la siguiente imagen.
Tal y como indique, la única cosa diferente que hice, aparte de asignar las diferentes secciones de la tarjeta, fue modificar la sección cuerpo para utilizar Formato Avanzado, tal y como se muestra en la siguiente imagen.
Ahora vamos a aplicar la directiva de condicionamiento if en el formato avanzado del cuerpo de la tarjeta y vamos a cambiar su contenido por el siguiente:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
<div class="demo-card"> {if HIGH_SALARY/} <span class="status-success"> Salario Alto </span> {else/} <span class="status-warning"> Salario Normal </span> {endif/} Salario: $&SALARY. {if PERF_HIGH/} ⭐ Alto desempeño {elseif PERF_MEDIUM/} ⚡ Desempeño medio {else/} ⚠ Requiere seguimiento {endif/} </div> |
El resultado luego de aplicar las dos directivas de plantilla if se los muestra en la imagen a continuación.
Dentro del código HMTL que proporciono arriba, se pueden observar claramente las dos directivas de plantilla if que se aplican y que como resultado, muestra una etiqueta en color específico dependiendo del monto del salario y, en la parte de abajo de la tarjeta , muestra un icono con un mensaje específico dependiendo del desempeño asignado a cada empleado.
Directiva case
Usamos las directivas case para mostrar contenido en función del valor de un elemento, columna de reporte o atributo de directiva de plantilla.
Es una manera sencilla, limpia y efectiva a tener que usar múltiples directivas if.
En el caso de las diectivas case, funcionan de manera similar a como lo haría un case en PL/SQL.
la sintaxis general de la directiva es:
|
1 2 3 4 5 6 7 8 |
{case NAME/} {when STRING1/} TEMPLATE_TEXT1 {when STRING2/} TEMPLATE_TEXT2 {otherwise/} TEMPLATE_TEXT {endcase/} |
Entonces, las directivas case en la práctica lucirían algo similar al siguiente código.
|
1 2 3 4 5 6 7 8 |
{case ESTADO/} {when 1/} 'Activo' {when 2/} 'Suspendido' {otherwise/} 'Bloqueado' {endcase/} |
Llegó la hora de poner en acción la directiva case, veamos un ejemplo en donde vamos a aplicar este tipo de directiva.
Para implementar las directivas de plantilla case, vamos a a crear un reporte interactivo para el que vamos a utilizar la siguiente consulta:
|
1 2 3 4 5 |
select ename, job, status, salary from demo_employees |
Si ejecutamos la página recién creada, vamos a obtener un reporte similar al siguiente.
Para aplicar directivas de plantilla, en este caso lo vamos a hacer en una columna específica, en mi caso la columna “status”, en donde dependiendo del valor del estado, vamos a mostrar una de tres cosas:
- un botón con clases estándar de APEX
- un botón simple
- un icono seguido de una etiqueta
Vamos a ir a la columna Status del reporte en el diseñador de páginas y en el atributo Expresión HTML de la sección Formato de Columna vamos a agregar el siguiente código HTML acompañado de la directiva case:
|
1 2 3 4 5 6 7 8 |
{case STATUS/} {when P/} <button type="button" class="t-Button t-Button--icon t-Button--iconLeft"><span aria-hidden="true" class="t-Icon t-Icon--left fa fa-user-check"></span>Contratar</button> {when A/} <button>Inactivar</button> {when I/} <span aria-hidden="true" class="fa fa-exclamation-triangle-o"> Despedido</span> {endcase/} |
En la imagen siguiente se muestra donde debe incluirse el código.
Y el resultado final, lo puedes apreciar en la siguiente imagen.
Directiva loop
Las directivas loop las utilizamos para repetir texto por cada campo en un elemento multi valor o columna, que se encuentra delimitado por un separador.
El separador por defecto es el caracter “:”, pero puede contener más de un caracter, en cuyo caso, se maneja como una expresión regular.
Esta directiva utiliza dos cadenas de sustitución:
- APEX$ITEM: que hace referencia al valor del campo actual dentro de la lista.
- APEX$I: que es el índice en base 1 del elemento actual en la lista.
La sintaxis general de la directiva loop es:
|
1 2 3 |
{loop ["SEP"] NAME/} TEMPLATE_TEXT {endloop/} |
Donde:
- NAME es un campo o una columna que tiene múltiples valores separados por un caracter específico.
- SEP es el caracter (0 caracteres) utilizado como separador
Vamos a realizar un ejemplo de aplicación de la directiva loop, en donde vamos a crear un reporte de tipo tarjetas, para el que vamos a utilizar la siguiente consulta:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
select EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM, DEPTNO, PROFILE_IMAGE, MIMETYPE, FILENAME, IMAGE_LAST_UPDATE, TAGS from EBA_DEMO_CARD_EMP |
En esta consulta, específicamente en la columna TAGS, podemos tener diferentes etiquetas para cada uno de los empleados, que tienen que ver con las habilidades que cada uno posee y que están separadas por “,”.
Al generar el reporte y ejecutar tal cual, vamos a obtener unas tarjetas sencillas, similares a las que muestra la siguiente imagen.
Como puede observar en la parte inferior de las tarjetas, aparece una lista de habilidades como una cadena de texto.
Queremos mostrar cada una de esas habilidades como un tag encerrado en un rectángulo con las esquinas redondeadas y con un color de fondo, para que se noten mejor y tengan una mejor apariencia.
Para lograrlo, vamos a ir a los atributos de la tarjeta y específicamente en los atributos del Cuerpo, vamos a habilitar el Formato avanzado y en en atributo Expresión HTML, vamos a agregar el siguiente código que incluye tanto directivas como HTML y que se muestra en la imagen a continuación del código de la directiva.
|
1 2 3 4 5 6 7 |
{if TAGS/} <ul class="a-tags"> {loop "," TAGS/} <li class="a-tag">&APEX$ITEM.</li> {endloop/} </ul> {endif/} |
Adicionalmente, a nivel de la página, en los atributos de CSS, específicamente en el atributo “En Línea”, vamos a agregar el siguiente código CSS, que es el que le dará formato a los elementos del loop:
|
1 2 3 4 5 6 7 8 9 10 11 |
.a-tags { list-style: none; } .a-tag { background-color: #3455eb; color: #fff; border-radius: 5px; padding: 5px; margin: 3px; display: inline; } |
El resultado está a la vista en la imagen de abajo.
Si usted es observador, además se habrá dado cuenta de que en este ejemplo, no solo estamos utilizando la directiva loop, sino que la estamos incorporando dentro de una directiva if, lo cual muestra la versatilidad en el uso de las mismas.
Directivas with & apply
Las últimas directivas que vamos a trabajar, son las directivas with y apply. Estas trabajan de manera conjunta y se complementan.
Normalmente son utilizadas para el manejo de directivas de plantilla reutilizables, lo que significa que son plantillas que definimos en los componentes compartidos de nuestras aplicaciones y las podemos llamar en diferentes componentes de estas.
Las vamos a encontrar en Componentes Compartidos – Interfaz de usuario – Plantillas.
Las identificamos porque su tipo es “Componente de plantilla”, además de que su nombre incluye el sufijo “[plugin]”, tal y como puede observar en la siguiente imagen (recuerde que la puede ampliar haciendo clic en ella).
Las directivas with y apply se utilizan para ejecutar plantillas de directivas reutilizables y funcionan en conjunto como ya se mencionó anteriormente.
La directiva with se encarga de asignar valores a los marcadores de posición del componente de plantilla que se utiliza y se específica en la directiva apply.
Además, es necesario que se cumplan ciertos requerimientos:
- que with asigne los valores de los marcadores de posición que usa apply,
- que los componentes de plugin sean renderizados en el lado del servidor.
Cuando ingresamos a la definición de una de estas plantillas, podemos observar varias cosas, las cuales puede empezar a ver en la imagen que comparto arriba.
En primer lugar, a la plantilla se le asigna un nombre interno, el cual en todo caso va a empezar con el prefijo “THEME$”, a este prefijo se le agrega el nombre que le hemos asignado a la plantilla.
Este nombre interno, es el que utilizamos en la directiva apply para hacer el llamado a la plantilla, de modo que si por ejemplo, tenemos una plantilla a la que le pusimos el nombre “AVATAR”, el nombre interno de la plantilla es “THEME$AVATAR”, y este es el nombre que utilizaremos para usar la plantilla desde la directiva apply.
También podemos observar en la parte inferior de la imagen, que podemos definir diferentes maneras de utilizar la plantilla, es el caso de la plantilla AVATAR, esta definida para usar una sola vez o varias veces si se utiliza dentro de un reporte.
La imagen de arriba, muestra otra de las secciones de la definición de la plantilla, en este caso, los códigos HTML y directivas que conforman la plantilla.
En el caso de la plantilla AVATAR, incluye código para el caso de utilizar de manera parcial (una sola vez), así como para la fila y el cuerpo de un reporte.
Estas plantillas también pueden incluir código tanto para un grupo como para un contenedor de reporte, que en este caso no es así.
Existen muchas más cosas que podemos definir para la plantilla, pero para el alcance de este artículo, solo me voy a referir a uno más, y es el que muestra la siguiente imagen.
Esta última imagen, muestra la definición de “Atributos personalizados”, los cuales corresponden a los marcadores de posición que debemos referenciar en la directiva with, cuando hacemos un llamado a la plantilla.
Y se preguntarán ¿cómo se hace esto?
Primero veamos la sintaxis general de las directivas wuth y apply.
|
1 2 3 4 |
{with/} PLACEHOLDER1:=EXPRESSION1 PLACEHOLDER2:=EXPRESSION2 {apply TEMPLATE_INTERNAL_NAME/} |
Si hacemos un barrido detallado de la sintaxis tenemos que:
- PLACEHOLDER1 y PLACEHOLDER2, hacen referencia a los marcadores de posición urilizados por la plantilla en apply.
- EXPRESSION1 y EXPRESSION2, contienen los vaolres asignados respectivamente a PLACEHOLDER1 y PLACEHOLDER2.
- TEMPLATE_INTERNAL_NAME, corresponde al nombre interno de la plantilla reutilizable
Es importante hacer notar que pueden incluirse en la directiva with, tantos PLACEHOLDER como atributos personales tenga definida la plantilla.
Pero ahora veamos un ejemplo que contemple el llamado a la plantilla AVATAR con la que hemos venido tratando este tema de las directivas with y apply.
|
1 2 3 4 5 |
{with/} TYPE:=IMAGE IMAGE:=&IMAGE_URL. ALT:={if DESCRIPTION/}&DESCRIPTION.{else/}No description.{endif/} {apply THEME$AVATAR/} |
En el ejemplo, estamos utilizando los marcadores de posición TYPE, IMAGE y ALT, que corresponden a los identificadores estáticos de los atributos personalizados de la plantilla AVATAR para estos marcadores y que respectivamemte definen, el tipo de objeto, URL al objeto y texto alterno del objeto, porque en este caso estamos hablando de una imagen.
Si se fija con detenimiento, puede ver que en el caso del marcador de posición ALT, estamos usando una directiva de plantilla condicional, por medio de la cual, si el campo/columna DESCRIPTION tiene un valor definido y este valor no es ni ‘F’, ‘N’ o ‘0’, muestra su contenido y si es nulo, entonces muestra el texto “No description.”
En este tema no voy a incluir un ejemplo de ejecución, ya que este tema y estas directivas dan para un nuevo artículo que pronto espero poder compartirles.
Sustituciones integradas para directivas de plantilla
Existen algunas cadenas de sustitución específicas, que son usadas por las directivas de plantilla, las cuales como en el caso de la directiva loop, podemos utilizar o referenciar, las principales son:
- APEX$ITEM
- APEX$I
- APEX%DOM_ID
APEX$ITEM especifica el valor del campo actual en la lista. Si tenemos un campo o columna de valores separados por un caracter específico, como por ejemplo: “Manzana, Uva, Banano, Mango”, APEX$ITEM tendrá uno de esos cuatro valores en un momento determinado del procesamiento de la directiva loop.
APEX$I es un índice base 1 (aumenta de 1 en 1) del elemento actual de la lista, que define en cual de los valores de la lista de valores del campo o columna se encuentra en un momento determinado el ciclo de la directiva loop. Si seguimos con el ejemplo anterior, esta cadena contendrá un valor entre 1 y 4 dependiendo del ciclo de iteración que se encuentre ejecutando la directiva loop. Teniendo esto en cuenta, antes de iniciar el ciclo tendrá un valor de 1 e irá aumentando conforme se ejecute el ciclo de la directiva.
APEX%DOM_ID genera un DOM_ID aleatorio único para la ejecución actual del fragmento de directiva de plantilla. Si estamos generando de manera dinámica HTML, esta cadena genera y asigna un id único y aleatorio al elemento HTML en que lo utilizamos, como en el código HTML que les dejo a continuación
|
1 2 |
{with/} <h1 id="#APEX$DOM_ID#_heading">#HEADING#</h1><someelement aria-labelledby="#APEX$DOM_ID#_heading"> |
En este caso en particular, estamos utilizando la cadena para asignar un ID estático al elemento H1.
Puede encontrar más información sobre el tema dentro de la aplicación del Tema Universal de APEX, así como en el siguiente enlace oficial:
