Introducción

En esta ocasión nos adentraremos en la generación de mensajes de notificación y alertas. Esto nos permite ofrecer una visión clara a los usuarios sobre las operaciones que están realizando, ya sea mostrando mensajes de éxito o error que pueden ser generados desde el lado cliente con JavaScript o desde el lado servidor utilizando PL/SQL.

Mensajes desde el lado Servidor con PL/SQL

Mensaje de Éxito

Para los mensajes de éxito del lado servidor podemos usar el siguiente código

BEGIN
    apex_application.g_print_success_message := 'Operación Exitosa!';
END;

Mensajes de Error

Para los mensajes de error contamos con el paquete apex_error y el procedimiento add_error que se utiliza para mostrar un error en una página de errores o en línea como una notificación. Este paquete solo puede llamarse desde una validación o un proceso, lo que nos permite mostrar errores personalizados al usuario en lugar de depender de mensajes técnicos o genéricos.

Ejemplo N° 1: Mostrar un error en la parte superior de la página

Este mensaje se muestra como una notificación de error en la parte superior de la página, en la región reservada para errores (donde suelen aparecer errores de validación).

apex_error.add_error (
    p_message          => 'Ha ocurrido un error al ejecutar el proceso!',
    p_display_location => apex_error.c_inline_in_notification
);

Ejemplo N° 2: Mostrar un error asociado a un campo específico

Este mensaje se mostrará al lado del elemento P5_CUSTOMER_ID (debajo o al costado, según el tema).

apex_error.add_error (
    p_message          => 'El ID del Cliente no es válido!',
    p_display_location => apex_error.c_inline_with_field,
    p_page_item_name   => 'P5_CUSTOMER_ID'
);

Ejemplo N° 3: Mostrar un error asociado a un campo y en la parte superior de la página

Este mensaje se mostrará al lado del elemento P5_CUSTOMER_ID y también como notificación en la parte superior de la página.

apex_error.add_error (
    p_message          => 'El ID del Cliente no es válido!',
    p_display_location => apex_error.c_inline_with_field_and_notif,
    p_page_item_name   => 'P5_CUSTOMER_ID'
);

Mensajes desde el lado Cliente con Javascript

Además de manejar los errores con APEX_ERROR desde el lado servidor (PL/SQL), también podés mostrar mensajes de éxito o error desde el lado cliente usando JavaScript, esto es ideal para procesos que no recargan la página o usan acciones dinámicas.

Lanzar mensaje de éxito

El uso de mensajes de éxito es bastante sencillo, la API cuenta solo con 2 funciones.

//Oculta mensajes de éxito previos
apex.message.hidePageSuccess();

//Muestra un mensaje de éxito 
apex.message.showPageSuccess("Operación realizada con éxito!");

Lanzar mensaje de error

En este caso los mensajes de error pueden ser lanzados de 3 maneras:

• Ubicación a nivel de página (page): Este error nos nuestra el mensaje en la parte superior derecha de la página, al igual que el mensaje de éxito.

• Ubicación a nivel de item (inline): Este error va asociado a un page item, puede ser utilizado para indicar al usuario un error sobre un item en específico.

• Ambas ubicaciones [page, inline]: Como última opción podemos hacer referencia a las 2 ubicaciones mencionadas.

// Limpiar errores previos
apex.message.clearErrors();
// Error con ubicación a nivel de página
apex.message.showErrors([{
    type: "error",
    location: "page",
    message: "Hubo un problema al procesar los datos.",
    unsafe: false
}]);

// Error con ubicación a nivel de item
apex.message.showErrors([{
    type: "error",
    location: "inline",
    pageItem: "P1_ITEM_NAME",
    message: "Valor fuera de rango.",
    unsafe: false
}]);

// Error con ambas ubicaciones
apex.message.showErrors([{
    type: "error",
    location: ["inline","page"],
    pageItem: "P1_ITEM_NAME",
    message: "Valor fuera de rango.",
    unsafe: false
}]);

Una de las funcionalidades útiles es la capacidad de mostrar múltiples errores utilizando apex.message.showErrors, Esto te permite agrupar varios mensajes de error en una sola llamada.

apex.message.showErrors([{
    type: "error",
    location: "page",
    message: "Error 1: Campo requerido.",
    unsafe: false
}, {
    type: "error",
    location: "page",
    message: "Error 2: Por favor, escriba un mensaje.",
    unsafe: false
}]);

Ocultar mensajes automáticamente

Desde la versión 24.1 de APEX contamos con una API nativa que nos permite realizar esta acción ya sea para mensajes de éxito o error especificando el tiempo de duración en milisegundos, este código no requiere ser llamado en cada función, puede ser llamado desde la sección initialization code o en la sección Function and Global Variable de la página.

apex.message.setDismissPreferences( {
    dismissPageSuccess: true,
    dismissPageSuccessDuration: 10000  // 10 segundos
} );

Para versiones anteriores se debe utilizar el siguiente código JavaScript. (Este código requiere ser llamado después de cada generación de mensajes).

setTimeout(() => {
    apex.message.hidePageSuccess(),
    apex.message.clearErrors()
},4000); // 4 segundos

Buenas prácticas

Como verán crear mensajes con JavaScript es bastante sencillo, pero debemos evitar repetir el mismo código en múltiples páginas. Como desarrolladores, debemos tener en cuenta que una modificación o un cambio de versión de APEX podría requerir de varias modificaciones en el código si no gestionamos esto de manera adecuada.

Para evitar este tipo de problemas recomiendo centralizar la lógica de los mensajes, puede ser en funciones reutilizables ubicadas en el Global Page para que sean accesibles desde todas las páginas o como archivos en los Static Application Files, teniendo en cuenta esto a continuación de muestro un ejemplo de como reutilizar el código agregandolo a una función.

Ejemplo de función reutilizable

function mostrarErrorAPEX(mensaje, ubicacion, item) {
    apex.message.clearErrors();

    // Construimos el objeto de error
    var error = {
        type: "error",
        location: ubicacion,
        message: mensaje,
        unsafe: false
    };

    // Si la ubicación incluye 'inline', se necesita un pageItem
    if ((ubicacion === "inline" || 
         (Array.isArray(ubicacion) && ubicacion.includes("inline"))) && item) {
        error.pageItem = item;
    }

    // Mostrar el error
    apex.message.showErrors([error]);

    // Ocultado automático
    apex.message.setDismissPreferences( {
        dismissPageSuccess: true,
        dismissPageSuccessDuration: 5000  // 5 segundos
    } );
}

Ejemplos de uso

//Error a nivel de página
mostrarErrorAPEX("Hubo un problema al procesar los datos.", "page");

//Error a nivel de Item
mostrarErrorAPEX("Valor fuera de rango.", "inline", "P1_ITEM_NAME");

//Error en ambas ubicaciones
mostrarErrorAPEX("Valor fuera de rango.", ["inline", "page"], "P1_ITEM_NAME");

Acceso a la Demo

Gestión de Mensajes con Oracle APEX

Conclusión

No se trata solo de mostrar mensajes, sino de comunicarnos de forma efectiva con el usuario. Como desarrolladores, esa también es una parte clave de nuestro trabajo, ya que no solo mejora la experiencia del usuario, sino que también refleja la calidad del desarrollo que realizamos.

Como siempre, espero que este post sea de tu agrado y por sobre todo te sea de utilidad, si tienes dudas o consultas no dudes en comentarlo.

No olvides seguirme en las redes sociales para enterarte de nuevos post, Saludos!

• Linkedin

• X (Twitter)