Come immagino tu sappia, il PL-SQL è sicuramente uno dei componenti fondamentali nelle applicazioni sviluppate in Oracle APEX.

Grazie al PL-SQL puoi sviluppare la logica di back end della tua applicazione e puoi richiamarlo, ad esempio, nelle Dynamic Actions, nei Page Processes e addirittura all’interno del componente PL-SQL Dynamic Content per creare delle pagine con contenuto dinamico.

A questo punto è normale chiedersi in che modo è possibile mostrare in una applicazione APEX dei messaggi (di errore, informativi o di conferma) generati da un programma PL-SQL.

In questo articolo desidero spiegarti alcuni metodi e trucchi per visualizzare i messaggi in APEX usando il PL-SQL.

Metodo 1: apex_application.g_print_success_message

Puoi usare questo metodo quando vuoi stampare un messaggio generato da una procedura PL-SQL richiamata da un Page Process.

• Apri la definizione della Pagina
• Crea un Page Button di nome PRINT_MESSAGE

• Vai alla sezione Processing e crea un nuovo Process

• Configura il Process nel seguente modo
  • Type: Execute Code
  • Language: PL/SQL
  • PL/SQL Code: inserisci il seguente codice dove andrai a valorizzare la variabile di sistema apex_application.g_print_success_message con il messaggio che vuoi mostrare. Puoi usare anche del codice HTML

begin 
    apex_application.g_print_success_message := '<span style="color: white;">This is a Message.</span>';
end;

• Esegui la Preview e premi il bottone PRINT_MESSAGE

• Questo è il risultato:

Metodo 2: APEX_ERROR

La seconda opzione che hai (e che eventualmente puoi usare in modo combinato insieme al metodo precedente) è tramite l’api APEX_ERROR.

Anche in questo caso puoi usare questo metodo quando vuoi stampare un messaggio generato da una procedura PL-SQL richiamata da un Page Process.

• Apri la definizione della Pagina
• Crea un Page Button di nome PRINT_MESSAGE
• Vai alla sezione Processing e crea un Process
• Configura il Process nel seguente modo
  • Type: Execute Code
  • Language: PL/SQL
  • PL/SQL Code: inserisci il codice PL/SQL

begin 
    apex_error.add_error(
      p_message => 'This is an error message'
    , p_display_location => apex_error.c_inline_in_notification
    );
end;

• Esegui la Preview e premi il bottone PRINT_MESSAGE
• Questo è il risultato

• La cosa interessante di questo metodo è che puoi concatenare più messaggi, cosa molto utile quando vuoi applicare delle validazioni complessive. Inserisci il seguente script

begin 
    apex_error.add_error(
      p_message => 'This is the first error message'
    , p_display_location => apex_error.c_inline_in_notification
    );
    apex_error.add_error(
      p_message => 'This is the second error message'
    , p_display_location => apex_error.c_inline_in_notification
    );
    apex_error.add_error(
      p_message => 'This is the third error message'
    , p_display_location => apex_error.c_inline_in_notification
    );
end;

• Esegui la Preview. Dovresti ottenere questo risultato:

Come dicevo prima, potresti usare in modo combinato la variabile apex_application.g_print_success_message per mostrare un messaggio in caso di esito positivo e invece l’api APEX_ERROR in caso di errore.

Supponiamo a tal proposito che tu abbia sviluppato una funzione PL/SQL (ma potrebbe essere anche una procedura) che restituisce un codice di uscita.

In funzione del codice di uscita puoi decidere se stampare un messaggio di conferma oppure uno di errore.

declare
	l_exit_code number;
begin 
        l_exit_code := my_function(....); /* here goes the code */
	
	if l_exit_code = 1 then
		apex_application.g_print_success_message := 'This is a successful message';
	elsif l_exit_code = 2 then
		apex_error.add_error(
		  p_message => 'Error: Custom error 1 occurred.'
		, p_display_location => apex_error.c_inline_in_notification
		);
	elsif l_exit_code = 3 then
		apex_error.add_error(
		  p_message => 'Error: Custom error 2 occurred.'
		, p_display_location => apex_error.c_inline_in_notification
		);
	else
		apex_error.add_error(
		p_message => 'Error: Unknown error occurred.'
		, p_display_location => apex_error.c_inline_in_notification
		);
	end if;
	
end;

Metodo 3: Proprietà Error Message

Il terzo metodo che voglio mostrarti si basa sull’uso delle proprietà Success Message e Error Message di un Process.

Vediamo come fare.

• Apri la definizione della Pagina
• Crea un Page Button che userai per lanciare la procedura PL-SQL
• Aggiungi 2 Page Item di tipo Hidden
  • Name: PX_HIDDEN_KO_MESSAGE, PX_HIDDEN_OK_MESSAGE
  • Type: Hidden
  • Protected Value: False

• Ho poi creato un Page Item, di nome PX_VALUE che utilizzerò per mostrarti come implementare i messaggi in questo modo:
  • Se il numero scritto all’interno del Page Item PX_VALUE è maggiore di 10 allora deve essere stampato un messaggio di errore
  • Se il numero scritto all’interno del Page Item PX_VALUE è minore o uguale a 10 allora deve essere stampato un messaggio di conferma

• Vai in Processing
• Configura un Process nel seguente modo
  • Type: Execute Code
  • Language: PL/SQL
  • PL/SQL Code: inserisci il codice PL/SQL

declare
    e_error exception;
begin
    if :p28_value > 10 then
        apex_util.set_session_state('P28_HIDDEN_KO_MESSAGE', 'Value must be less than 10!');
        apex_util.set_session_state('P28_HIDDEN_OK_MESSAGE', NULL);
        raise e_error;
    else
        apex_util.set_session_state('P28_HIDDEN_KO_MESSAGE', null);
        apex_util.set_session_state('P28_HIDDEN_OK_MESSAGE', 'Value is correct');
    end if;
end;

Come puoi notare, nel blocco PL-SQL, i due Page Item vengono valorizzati in funzione dell’esito della procedura. Laddove deve essere lanciato un messaggio di errore devi usare l’istruzione raise e_error che in PL-SQL.

Per maggiori dettagli sulle eccezioni PL-SQL leggi questo tutorial.

• Seleziona il Page Process e vai alla proprietà Success Message
• Inserisci il riferimento al Page Item dove andiamo a salvare il messaggio di conferma.
  • Error Message: &PX_HIDDEN_OK_MESSAGE. (attenzione al carattere ‘.’)

• Seleziona il Page Process e vai alla proprietà Error Message
• Inserisci il riferimento al Page Item dove andiamo a salvare il messaggio di errore.
  • Error Message: &PX_HIDDEN_KO_MESSAGE. (attenzione al carattere ‘.’)
  • Display Location: On Error Page

• Esegui la Preview.
• Caso 1: PX_VALUE < 10

Metodo 4: Alert JavaScript

Tutti i metodi che abbiamo visto fino a questo momento possono essere utilizzati nei Page Process.

Tuttavia, in APEX è possibile definire delle Dynamic Action: vediamo come possiamo mostrare dei messaggi restituiti da una procedura PL-SQL.

• Apri la definizione della Pagina
• Crea un Page Button che userai per lanciare la Dynamic Action
• Aggiungi un Page Item di tipo Hidden
  • Name: PX_HIDDEN_MESSAGE
  • Type: Hidden
  • Protected Value: False
• Come nell’esempio precedente, crea un Page Item che userai per testare questa funzionalità:
  • Se il numero scritto all’interno del Page Item è maggiore di 10 allora deve essere stampato un messaggio di errore
  • Se il numero scritto all’interno del Page Item è minore o uguale a 10 allora deve essere stampato un messaggio di conferma

• Crea una Dynamic Action con 2 Action: la prima di tipo Execute Server-Side Code e la seconda di tipo Execute JavaScript Code.

• Ecco come configurare la Action Execute Server-Side Code
  • Language: PL/SQL
  • Items to Submit: PX_VALUE
  • Items di Return: PX_HIDDEN_MESSAGE
  • PL/SQL Code: inserisci lo script seguente:

declare
    e_error exception;
begin
    if :P28_VALUE_B > 10 then
        :P28_HIDDEN_MESSAGE := 'Value must be less than 10!';
    else
        :P28_HIDDEN_MESSAGE :=  'Value is correct';
    end if;
end;

• Ecco come configurare la seconda Action di tipo Execute JavaScript Code
  • Code: inserisci il seguente codice JavaScript che recupera il valore salvato del Page Item PX_HIDDEN_MESSAGE e lo stampa in un alert

alert(apex.item( "P28_HIDDEN_MESSAGE" ).getValue());

• Esegui la Preview

Metodo 5: Usare la Validation Rules

Un altro modo che hai per validare i campi di una Form è tramite le Validation Rules di cui spiego il funzionamento in questo articolo.

Conclusioni

Bene, direi che adesso hai a disposizione un bel po’ di strumenti che ti aiuteranno ad implementare dei messaggi di validazione belli e funzionali.

Certo, si potrebbero dire tante altre cose ma credo che con queste nozioni non avrai problemi.

Spero che tutte queste informazioni ti siano d’aiuto!

Se l’articolo ti è piaciuto ti invito a condividerlo con i tuoi colleghi e amici.

Un abbraccio!

Daniele