Oracle APEX: visualizzare un pulsante in ogni riga di un Interactive Report

Oracle APEX offre diversi strumenti che consentono di creare rapidamente report accattivanti e di facile lettura che presentano i dati nel modo più adatto alle esigenze degli utenti.

Probabilmente uno dei modi più comuni è il classico report in formato tabellare che puoi costruire usando un Classic Report, un Interactive Report o una Interactive Grid.

Ciascuno di questi componenti ha i propri vantaggi e grazie alla loro configurabilità consentono di ottenere risultati notevoli con pochissimo sforzo.

Tuttavia, devi sapere che ci sono alcuni piccoli trucchetti, non proprio immediati, ma che si rivelano utilissimi in moltissime situazioni.

Uno di questi, forse quello più scontato ma pure sempre molto gettonato, consiste nel mostrare uno o più pulsanti per ogni riga di un Interactive Report (in realtà la stessa funzionalità può essere replicata anche in una Interactive Grid).

In questo tutorial di spiegherò come fare.

Prima di Iniziare

Quello che vedi sotto è un Interactive Report standard, creato usando il wizard di Oracle APEX

Quello che vogliamo fare è aggiungere 2 colonne aggiuntive ciascuna delle quali avrà un bottone:

• Visualizza Dettagli: aprirà la Form Page che mostra i dettagli del record.
• Elimina Record: per cancellare il record dal database, quindi un bottone che esegue uno script PL-SQL.

Prima di continuare volevo farti notare che l’Interactive Report ha già una colonna con un link che consente di aprire la Form Page di dettaglio.

Il “problema” sta nel fatto che purtroppo è possibile configurare solo un link (vedi print-screen sotto).

Se hai bisogno di creare più link ad altre pagine devi necessariamente creare dei pulsanti custom aggiuntivi usando la procedura che ti spiegherò in questo tutorial.

Come aggiungere un bottone che apre un link

Questo è probabilmente il metodo più veloce per creare un link custom tra il record dell’Interactive Report ed una qualsiasi altra pagina della tua applicazione.

• Accedi all’APP Builder e seleziona l’Interactive Report

• Vai in Source > SQL Query e modifica la query aggiungendo un valore dummy: non è importante il tipo di dato restituito. Personalmente uso sempre una stringa che descrive l’azione.

• Premi Salva, nella struttura dell’Interactive Report dovresti vedere la colonna aggiuntiva. Seleziona la nuova colonna dummy che è di tipo Plain Text.

• Vai nelle proprietà della colonna e modifica il tipo da Plain Text a Link

• Vai alla sezione Link e configura il Target, ossia la pagina di destinazione

• Inserisci eventuali parametri che devono essere passati alla Target Page

• Vai alla proprietà Link > Link Attributes ed inserisci la seguente stringa

class="t-Button t-Button--simple t-Button--hot t-Button--stretch"

• Esegui la preview per vedere il risultato

• Come puoi notare, il testo mostrato all’interno del bottone corrisponde al valore restituito dalla query.
• Puoi modificarlo inserendo un valore statico nel campo Link Text.

Come aggiungere un bottone che esegue una Dynamic Action

Quello che desideriamo fare è estendere l’Interactive Report aggiungendo una colonna con un pulsante custom che esegue una azione sul database.

Se l’utente preme Elimina Riga, l’applicazione eseguirà una operazione di DELETE.

A tal proposito utilizzeremo la seguente procedura PL-SQL, dove p_record_id è l’ID del record da cancellare mentre p_return_code e p_return_message sono due parametri in output che rappresentano rispettivamente un codice e un messaggio di uscita.

create or replace procedure delete_person (
    p_record_id       in   number,
    p_return_code     out  number,
    p_return_message  out  varchar2
) is
begin
    delete from person
    where id = p_record_id;

    p_return_code := 0;
    p_return_message := 'Record eliminato correttamente';

exception when others then
    p_return_code := 1;
    p_return_message := 'Impossibile eliminare il record';
end;

• Accedi all’APP Builder di Oracle APEX.
• Apri la definizione della Pagina
• Vai alla sezione Processing > Ajax Callback

• Clicca con il pulsante destro del mouse e seleziona Create Process.
• Crea un nuovo Process con queste caratteristiche
  • Name: DELETE_RECORD
  • Type: Execute Code
  • Location: Local Database
  • Language: PL-SQL
  • PL-SQL Code: copia il codice seguente

declare
     lv_error_code  number;
     lv_error_msg   varchar2(4000);
 begin
     /* Questo è il frammento di codice che esegue la procedura PL-SQL */
     for i in 1..apex_application.g_f01.count loop
         delete_person(p_record_id => apex_application.g_f01(i), p_return_code => lv_error_code, p_return_message => lv_error_msg);
     end loop;
     
     /* Questo è il frammento di codice che esegue stampa a video un messaggio */
     apex_json.open_object;
     apex_json.open_array('output');
     apex_json.open_object;
     apex_json.write('lv_error_code', lv_error_code);
     apex_json.write('lv_error_msg', lv_error_msg);
     apex_json.close_object;
     apex_json.close_array; 
     apex_json.close_object; 
end;

• Seleziona il nodo principale della pagina APEX che stai modificando

• Vai alla proprietà Function and Global Variabile Declaration ed inserisci la seguente funzione JavaScript

function deletePerson(person_id) {
    var lSpinner$ = apex.util.showSpinner();
    /* ajax to call the database procedure */
    apex.server.process("DELETE_RECORD", {
        f01: person_id,
        pageItems: "#DELETE_ROW"
    }, {
        success: function(pData) {
            lSpinner$.remove();
            var errorMsg = pData.output[0].lv_error_msg;
            if (pData.output[0].lv_error_code == '0') {
                document.location.reload();
            } else {
                apex.message.clearErrors();
                apex.message.showErrors([{
                    type: "error",
                    location: ["page"],
                    message: errorMsg,
                    unsafe: false
                }]);
            }
        }
    });
}

• Seleziona l’Interactive Report
• Vai alla proprietà Source > SQL Query ed aggiungi una nuova colonna virtuale, chiamata DELETE_ROW

Seleziona la colonna DELETE_ROW

• Configura la colonna DELETE_ROW nel modo seguente:
  • Type: Link
  • Column Heading: Elimina Riga
  • Target Type: URL
  • Target URL: javascript:deletePerson(#ID#);
  • Link Attributes: inserisci la seguente stringa

class="t-Button t-Button–simple t-Button–hot t-Button–stretch"

Come personalizzare l’aspetto del bottone

Come avrai capito, è la stringa che ti ho fatto inserire nel campo Link Attributes a gestire la formattazione del bottone.

Puoi personalizzare il suo aspetto in questo modo.

• Collegati alla pagina Oracle APEX Universal Theme e vai in Reference > Button Builder
• Usando le funzionalità del Builder imposta l’aspetto del bottone come più ti piace

• Quando hai fatto, vai alla sezione Usage Instruction dove troverai le stringhe Link Text e Link Attributes che devi copiare ed incollare nelle rispettive proprietà della Page Item in APEX

• Esegui la Preview per vedere il risultato

Conclusioni

Questa guida sicuramente non è sufficiente per capire ogni singolo aspetto di come configurare un Interactive Report con Oracle APEX, ma se leggi gli approfondimenti che ho fornito qua e là riuscirai a realizzare il tuo progetto e ottenere il successo che desideri.

Nel frattempo ti invito a farmi sapere se hai trovato utile questo tutorial e a seguirmi sui miei profili social di Linkedin e Twitter, dove condivido periodicamente tanti informazioni utili su Oracle APEX e altre piattaforme di sviluppo low-code.

Non mi resta che augurarti un buon lavoro!

Un abbraccio

Daniele