Come configurare e personalizzare una Lista in Oracle APEX

Quando sei alle prese con la progettazione di una applicazione web ci sono tanti aspetti da tenere in considerazione come il modello dati, le logiche di business ed ovviamente anche la user interface.

Non esiste una componente più importante di una altra: tutte contribuiscono al successo del tuo progetto.

Un modello dati carente si tradurrà nell’incapacità di poter coprire le esigenze di business.

Una user interface poco accurata o, peggio ancora, non intuitiva, non aiuterà gli utenti che si sentiranno frustrati (perché non riescono a capire l’applicazione) ed impiegheranno molto tempo per sentirsi a proprio agio.

Nelle applicazioni moderne l’utilizzo dei dashboard e cruscotti è diventato molto comune perché aiutano l’utente ad organizzare meglio il proprio lavoro e lo guidano visivamente i contenuti di suo interesse.

Ad esempio in un CRM è utile creare delle dashboard che mostrino in modo sintetico le informazioni di interesse come il numero di opportunità vinte oppure i volumi delle vendite.

Allo stesso tempo in una applicazione di Customer Care l’operatore che si collega può vedere in una dashboard quante richieste nuove sono da assegnare, quante invece sono già state prese in carico e così via.

I badges vengono generalmente utilizzati quando vuoi costruire un cruscotto che enfatizzi o metta in evidenza una particolare informazione e sono uno dei migliori metodi per attrarre l’attenzione degli utenti su uno numero specifico come (il numero di task da eseguire, un KPI, ecc,…).

In un recente post abbiamo visto come possiamo creare un cruscotto come quello in figura (e non solo) utilizzando il Classic Report.

Se hai avuto modo di fare una prova avrai notato che questa soluzione ha un limite: non è interattiva.

Sarebbe molto più interessante far si che l’utente possa cliccare su uno qualsiasi di quei box per atterrare su una pagina di dettaglio dalla quale iniziare le proprie attività, non credi?

Prima di Iniziare

Se non è il primo articolo di APPin5Minuti che leggi, immagino saprai che mi piace spiegare i concetti portando sempre qualche esempio concreto da fare insieme, passo dopo passo.

Anche in questo caso, quindi, ho in mente un esercizio molto utile che non solo ti aiuterà a capire come configurare una Badge List in APEX, ma ti potrà essere (spero) di inspirazione per creare applicazioni sempre più belle.

Oggi costruiremo insieme una semplicissima applicazione demo per gestire le richieste di supporto IT con una home page fatta più o meno così:

L’obiettivo è quello di far sì che se l’utente clicca sul box Assigned to Me venga aperta una pagina con l’elenco di tutte le richieste di supporto che ha in carico.

Allo stesso modo, se clicca sul box Overdue dovrebbe aprirsi la stessa pagina di dettaglio ma che mostra, in questo caso, tutte le richieste in carico che sono in ritardo.

Collegandoti a questo link puoi vedere una applicazione di esempio.

Alcuni concetti base sulle Liste APEX

Prima di tutto spendiamo due parole sulle liste.

In Oracle APEX una lista (List) è un oggetto che serve per definire un elenco di collegamenti verso altre pagine della nostra applicazione piuttosto che verso altre APP o URL esterni.

Per capirci meglio, il menù di navigazione di una qualsiasi applicazione sviluppata in Oracle APEX è una Lista APEX.

Ciascuna entry di una lista APEX ha diverse proprietà come, ad esempio, una etichetta, una icona e sicuramente una URL di destinazione.

Vediamo qualche esempio.

• Accedi all’APP Builder di Oracle APEX e apri al definizione della tua APP
• Vai in Shared Components e spostati alla sezione Navigation

Da qui puoi accedere alle varie tipologie di APEX List:

• List: elenco completo di tutte le liste definite nella tua applicazione
• Navigation Menu: la lista che APEX utilizza per costruire il menù di navigazione principale della tua app

• Breadcrumb: liste per costruire i percorsi di navigazione, utili perché aiutano l’utente a capire dove si trova, ovvero in quale sezione del portale è situato.
• Navigation Bar List: la lista che APEX utilizza per costruire il menù nella barra in alto della tua applicazione

• Clicca su List

• Da questa maschera puoi vedere tutte le liste. Clicca sulla lista Desktop Navigation Menù

Dovresti vedere tutte le entries (i links) della tua lista.

Come dicevo poco fa, per ciascuna Entry puoi usare sia link interni (altre pagine della tua applicazione) che esterni (altre applicazione dello stesso workspace piuttosto che URL esterni)

Vediamo brevemente com’è fatta la struttura di una entry generica.

• Clicca sulla Entry Administration

• Sezione Entry: da qui puoi gestire le impostazioni primarie. Ecco quelle principali
  • Parent List Entry: indica se l’entry corrente è primaria o secondaria (in questo secondo caso andari ad indicare l’entry principale)
  • Sequence: ordinamento della entry
  • Image/Class: icona da visualizzare
  • List Entry Label: etichetta principale

• Sezione Target: in questo punto andrai a specificare le proprietà del link piuttosto che eventuali parametri da passare alla pagina di destinazione

• Sezione User Defined Attributes: questa è una sezione molto interessante. Da qui puoi specificare per ciascuna entry i valori degli attributi opzionali che servono per inizializzare correttamente il template HTML.
  • List Template: seleziona il template di riferimento (quello che utilizzare per formattare la lista nella tua applicazione)
  • ID Attribute, Disabled (True/False), …: sono gli attributi aggiuntivi che puoi valorizzare per formattare la lista. Essi dipendono dal template che hai selezionato.
  • Clicca su List Template Attributes per vedere tutti i placeholders previsti dal template selezionato.

• Ecco gli attributi aggiuntivi previsti, ad esempio, dal template Badge List

A conferma di ciò, possiamo dare uno sguardo al template Badge List

• Clicca su Shared Components > Templates
• Cerca il template Badge List e seleziona il template con Type=List

• Clicca su Template Definition per vedere il template HTML all’interno del quale puoi riconoscere i placeholders che abbiamo visto prima: A01, A02, A03 e A04

L’ultima cosa che voglio dire sulle Liste APEX riguarda la tipologia: quella che ti ho mostrato fino a questo momento è un classico esempio di Lista Statica, ovvero di lista dove le varie entries sono predefinite.

Tuttavia APEX permette anche di costruire Liste Dinamiche, ovvero basate su una Query SQL.

In questo tutorial ti spiegherò come lavorare con entrambe creando un piccolo cruscotto da usare in una applicazione di Customer Care.

Step 1: crea una pagina (Interactive Report) con parametri

Ora che conosci i concetti principali di una lista in APEX, procediamo con la definizione del report che utilizzeremo per visualizzare i record.

Come già spiegato, il nostro obiettivo è quello di creare un componente (una lista) che apra la stessa pagina di dettaglio ma mostrando ogni volta record diversi:

• se clicco sul box delle richieste in carico devo vedere l’elenco delle richieste che sono state assegnate a me
• se clicco sul box delle richieste da assegnare devo vedere l’elenco delle richieste non ancora prese in carico
• ecc..

Certo, una soluzione potrebbe essere quella di creare tante pagine diverse quante sono quelle di cui abbiamo bisogno però capirai che non è certamente la strada migliore.

Possiamo fare di meglio.

Creeremo una sola pagina basata su Interactive Report e la configureremo affinché possa essere inizializzata con dei parametri in ingresso che se opportunamente valorizzati serviranno a filtrare i dati.

Qui sotto puoi trovi lo script per creare una tabella di demo con alcuni dati di esempio.

• Copia lo SCRIPT ed eseguilo nel tuo Workspace APEX

-- create tables
create table request (
    id                             number generated by default on null as identity 
                                   constraint request_id_pk primary key,
    title                          varchar2(50 char),
    owner_group                    varchar2(25 char),
    assigned_to                    varchar2(25 char),
    status                         varchar2(15 char),
    creation_date                  date,
    close_date                     date
)
;
-- load data
 
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (1,'PC non funziona','Operations','Daniele Trasarti','In Carico',sysdate - 7,null);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values ( 2,'Reset Password','Operations','Daniele Trasarti','In Carico',sysdate - 6,null);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (3,'Richiesta per un nuovo PC','Operations',null,'Da Assegnare', sysdate - 2,null);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (4,'Problema stampa PDF','Operations','Daniele Trasarti','Completata',sysdate - 2,sysdate - 2);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (5,'Rest Password PC','Operations','Daniele Trasarti','Completata',sysdate - 2,sysdate - 2);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (6,'Impossibile registrare l''ordine','Applications','Daniele Trasarti','In Carico',sysdate - 4,null);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (7,'Abilitazione Applicazione APEX','Applications','Daniele Trasarti','Completata',sysdate - 4,sysdate -3);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (8,'Errore durante il salvataggio dei dati','Applications',null,'Da Assegnare',sysdate - 4,null);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (9,'Non riesco a completare la spedizione della merce','Applications','Daniele Trasarti','In Carico',sysdate - 20,null);
insert into request (id, title, owner_group, assigned_to, status, creation_date, close_date) 
values (10,'Non ricevo le notifiche e-mail','Applications','Daniele Trasarti','In Carico',sysdate - 15,null);
commit;

La prima cosa da fare è creare una semplice report di tipo Interactive Report che useremo per visualizzare i dati.

• Accedi all’APP Builder, apri la definizione della tua applicazione e clicca su Create New Page

select title, 
       owner_group, 
       assigned_to, 
       status, 
       creation_date, 
       close_date, 
       (case when close_date is null and trunc(sysdate) - trunc(creation_Date) >= 15 then 'In Ritardo'
             when close_date is null and trunc(sysdate) - trunc(creation_Date) >= 5 then 'A Rischio'
        end
        ) status     
 from request

• Seleziona il Page Type Report e clicca Next

• Seleziona il Report Type Interactive Report e clicca Next

• Dai un nome al Report e clicca Next

• Se lo desideri puoi creare una voce di menù per questo report. Io ho deciso, per questo momento, di non creare nulla. Clicca Next.

• Copia la seguente query SQL che useremo per creare il report

select title, 
       owner_group, 
       assigned_to, 
       status, 
       creation_date, 
       close_date, 
       (case when close_date is null and trunc(sysdate) - trunc(creation_Date) >= 15 then 'In Ritardo'
             when close_date is null and trunc(sysdate) - trunc(creation_Date) >= 5 then 'A Rischio'
        end
        ) request_status     
 from request

• Seleziona come Origine Dati il tipo SQL Query. Inserisci la query che ti ho fornito e clicca Next

• La creazione del report dovrebbe essere completa e dovresti atterrare nella schermata dove puoi modificare la struttura della pagina

• Esegui la Preview per vedere l’elenco di tutte le richieste di supporto con alcune informazioni come:
  • chi è l’assegnatario (c’è quasi sempre il mio nome, purtroppo per me.. eh eh)
  • lo stato della richiesta (Da Assegnare, In Carico, Completata)
  • le date di apertura chiusura
  • uno stato che indica se la richiesta è in ritardo (Request Status = In Ritardo) oppure lo sta per diventare (Request Status = A Rischio)

Completiamo la configurazione della pagina creando tre Page Items che utilizzeremo per filtrare i dati restituiti dall’Interactive Report.

Seleziona il Report e crea 3 Page Items

• PX_STATUS di tipo Text Field
• PX_ASSIGNED_TO di tipo Text Field
• PX_REQUEST_STATUS di tipo Text Field

• Seleziona il Report e vai alle proprietà della Region

• Sostituisci la query del report con quella seguente (ricordati di cambiare il nome dei parametri con quelli della tua pagina che nel mio caso si chiamano P27_STATUS, P27_ASSIGNED_TO e P27_REQUEST_STATUS)

select title, owner_group,  assigned_to,  status,  creation_date, request_status from
    (select title, owner_group,  assigned_to,  status,  creation_date, 
        close_date, 
        (case when close_date is null and trunc(sysdate) - trunc(creation_Date) >= 15 then 'In Ritardo'
                when close_date is null and trunc(sysdate) - trunc(creation_Date) >= 5 then 'A Rischio'
            end
            ) request_status     
    from request)
where  (assigned_to = :p27_assigned_to or :p27_assigned_to is null)
  and  (status = :p27_status or :p27_status is null)
  and  (request_status = :p27_request_status or :p27_request_status is null)

• Seleziona la proprietà Page Items to Submit ed aggiungi i tre Page Items che hai creato

• Esegui la Preview della pagina: puoi vedere i parametri che useremo per filtrare i record

Per aiutare l’operatore ad organizzare meglio il lavoro creeremo un piccolo cruscotto nell’ Home Page che focalizzi la sua attenzione su tre specifiche tipologie di situazioni.

• Le richieste che devono ancora essere prese In Carico: per estrarre questi record possiamo interrogare la pagina con questi parametri:
  • Status = Da Assegnare
  • Assigned To = valore blank o null
  • Request Status = valore blank o null

• Le richieste In Carico all’operatore
  • Status = In Carico
  • Assigned To = Daniele Trasarti
  • Request Status = valore blank o null

• Le Richieste In Carico all’operatore e che purtroppo sono in ritardo In Ritardo rispetto ad uno SLA
  • Status = In Carico
  • Assigned To = Daniele Trasarti
  • Request Status = valore blank o null

Quello che dovremo fare e far si che dall’home page della nostra applicazione si possano creare dei link che aprano la pagina di destinazione passando i parametri indicati.

Ora possiamo procedere alla configurazione della badge list.

Step 2: configura una lista statica

• Accedi all’APP Builder e vai in Shared Components > Navigation > List
• Clicca Create per creare una nuova Lista APEX

• Seleziona l’opzione From Scratch e clicca Next

• Dai un nome alla lista (ad esempio io l’ho chiamata Static Navigation Request List), seleziona il tipo Static e clicca Next.

• Specifica le Entries. In questo caso ne prevedo tre (ma ne puoi aggiungere altre anche successivamente)
  • Da Assegnare
  • In Carico
  • In Ritardo

• Per ciascuna delle entries devi poi indicare qual è la pagina o l’URL target. Nel nostro caso è sempre la stessa pagina.
• Clicca sull’elenco valori Target Page ID or Custom URL, cerca la pagina di destinazione che hai creato nel paragrafo precedente e selezionala.

• Ripeti la stessa operazione per tutte le Entries e clicca Next
• Lascia i parametri successivi di default e premi Create List

La lista è stata creata. Adesso dovremo completare la sua configurazione per far si che funzioni come ci aspettiamo.

• Da Shared Components > List, cerca la lista che abbiamo creato e clicca sul nome per vederne i dettagli

• Dovresti vedere le sue Entries. Clicca sulla prima (Da Assegnare).

• Vai alla sezione Entry e scegli l’icona che preferisci

• Vai alla sezione Target e completa la sua configurazione in questo modo:
  • Clear Cache: inserisci il Page ID della pagina di destinazione (che nel mio caso è la pagina 27)
  • Set these items: PX_STATUS
  • With these Values: Da Assegnare

• Ripeti la stessa operazione anche per le Entries mancati.
• Ad esempio, questa è la configurazione della seconda Entry (Richieste In Carico)
  • Set these items: PX_STATUS, PX_ASSIGNED_TO
  • With these Values: In Carico, Daniele Trasarti

• Questa, infine, la configurazione dell’ultima Entry (Richieste In Ritardo)
  • Set these items: P27_STATUS,P27_ASSIGNED_TO,P27_REQUEST_STATUS
  • With these Values: In Carico,Daniele Trasarti,In Ritardo

Ora che la lista è pronta possiamo finalmente utilizzarla.

Step 3: configura la lista nell’home page dell’applicazione

• Accedi all’APP Builder di APEX e crea una nuova pagina vuota (Blank Page)
• Crea una nuova Region di tipo List di nome Demo List Region

• Seleziona la regione Demo List Region che abbiamo creato e configura le sue proprietà
  • Type: List
  • List: seleziona la lista che abbiamo configurato pochi minuti fa

• Esegui la Preview per vedere il risultato che dovrebbe essere più o meno questo

Se clicchi su uno qualsiasi dei link assegnati dovrebbe aprirsi la pagina di destinazione (Requests Report) con i parametri automaticamente valorizzati.

Ad esempio, se clicco sul link In Carico ottengo questo risultato:

Ce l’hai fatta? Bene!

In effetti fino a questo momento abbiamo visto un bel po’ di cose: abbiamo imparato cos’è una lista, come configurarla e come utilizzarla nella nostra applicazione.

Inoltre abbiamo anche imparato come possiamo passare dei parametri alla pagina di destinazione inserita nella entry della Lista.

Tuttavia avevamo un obiettivo ben preciso, ovvero quello di creare un bel cruscotto, visivamente più accattivante di un semplice elenco di link.

Step 4: personalizza la lista statica

• Seleziona la Region List

• Vai alle proprietà e clicca su Attributes

• Seleziona il template che preferisci (ad esempio Badge List).
• Clicca su Template Options.

• Seleziona le opzioni che desideri

• Se esegui la Preview dovresti vedere questo:

Un’altra cosa che possiamo fare per personalizzare ulteriormente la visualizzazione di questa lista è modificarne gli user attributes.

Come aggiungere un contatore

• Vai in Shared Components > List e seleziona la Lista
• Seleziona la prima Entry e vai nella sezione User Attributes

Da questo punto possiamo personalizzare puntualmente ciascuna entry della lista specificando, ad esempio, se mostrare una stringa nel box e decidendo il colore dello sfondo.

Puoi inserire sia dei valori statici ma anche dei valori dinamici.

• In corrispondenza dell’attributo Value inserisci la stringa &P_NUOVE_RICHIESTE.

La stringa &P_NUOVE_RICHIESTE. che ho inserito è un placeholder che fa riferimento ad un Application Item che si chiama P_NUOVE_RICHIESTE e che ho precedentemente creato in Shared Components > Application Items

Per inizializzare l’Application Item P_NUOVE_RICHIESTE:

• apri la definizione della Pagina che contiene la lista e clicca su Computation

• Crea un nuovo modulo di calcolo con queste caratteristiche
  • Item Name: P_NUOVE_RICHIESTE
  • Point: Before Header
  • Type: SQL Query
  • SQL Query: inserisci la query riportata nella figura sotto

Come modificare il colore

• Sempre nella sezione User Attributes della specifica List Entry, vai alla proprietà Link Classes

• Inserisci il modificatore CSS della Color Palette: ad esempio u-color-9

Per gestire e modificare la Palette di colori dell’applicazione:

• Apri il Theme Roller in modalità Preview
• Vai alla sezione Palette: in questo punto puoi definire e gestire la palette di colori della tua app. Ciascun colore della Palette è identificato da un numero (da 1 a 15) e potrai richiamare il colore usando la relativa classe CSS
  • Color 1: u-color-1
  • Color 2: u-color-2
  • Color 3: u-color-3
  • ecc…

A questo link puoi trovare tutte le classi CSS standard previste per modificare il colore di riempimento del bottone, il colore dello sfondo, del bordo e del testo senza dover scrivere codice CSS custom.

Dopo aver ripetuto per ciascuna elemento della lista le medesime operazioni (definendo ovviamente specifici Application Items) siamo riusciti ad ottenere il risultato seguente.

Come configurare una Lista Dinamica

Quello che abbiamo fatto fino a questo momento è stato creare e personalizzare una Lista Statica.

Tuttavia, in APEX è possibile definire anche delle Liste Dinamiche che vengono inizializzate a partire da una Query SQL.

In questo caso, la query dovrà contenere tutti gli attributi necessari affinché APEX sia in grado di inizializzare correttamente la Lista.

Accedendo a questo link puoi vedere quale deve essere la query corretta per inizializzare una lista di tipo dinamico.

SELECT level, labelValue label, 
       [targetValue]            target, 
       [is_current]             is_current_list_entry,
       [imageValue]             image, 
       [imageAttributeValue]    image_attribute,
       [imageAltValue]          image_alt_attribute,
       [attribute1]             attribute1,
       [attribute2]             attribute2,
       [attribute3]             attribute3,
       [attribute4]             attribute4,
       [attribute5]             attribute5,
       [attribute6]             attribute6,
       [attribute7]             attribute7,
       [attribute8]             attribute8,
       [attribute9]             attribute9,
       [attribute10]            attribute10
FROM ...
WHERE ...
ORDER BY ...

Riconosciamo, ad esempio, la colonna dove inserire l’URL di destinazione. In questo caso, ovviamente, dovrai costruire l’URL dinamicamente inserendo tutti i parametri previsti (per maggiori informazioni su come fare clicca qui)

Se poi decidi di utilizzare il template badge alcune colonne (image, image_attribute e image_alt_attribute) possono tranquillamente essere trascurate.

Ecco una query funzionante nel caso tu voglia usare sempre il template Badge List

select null as lvl,
       'Etichetta Nr. 1' as label,
       '#' as target,
       null as attribute1,
       null as attribute2,
       null as attribute3,
       null as attribute4,
       42 as attribute5,
       'custom-list-class' as attribute6,
       'custom-a-tag-attr' as attribute7
from dual

• La prima colonna nella query deve essere il livello, che dei sempre inserire ma puoi valorizzare come null (altrimenti potresti ottenere uno spiacevole ORA-06502: PL/SQL: errore numerico o valore: errore di conversione da carattere a numero)
• La seconda colonna consente di definire l’etichetta del badge. Questa colonna è obbligatoria. Utilizzare NULL se non si desidera visualizzare un’etichetta.
• La successiva colonna obbligatoria è l’URL target.
• Gli attributi da 1 a 4 non vengono utilizzati
• La colonna attribute5 corrisponde al placeholder #A01#
• La colonna attribute6 corrisponde al placeholder #A04#
• La colonna attribute7 corrisponde al placeholder #A03#

Creiamo una Lista Dinamica

• Accedi all’APP Builder e vai in Shared Components > Navigation > List
• Clicca Create per creare una nuova Lista APEX

• Seleziona l’opzione From Scratch e clicca Next
• Stavolta seleziona l’opzione Dynamic ed inserisci la seguente query di esempio

select  null as lvl,
       'Etichetta della Lista' as label,
       '#' as target,
       null as attribute1,
       null as attribute2,
       null as attribute3,
       null as attribute4,
       '42' as attribute5,
       'u-color-14'  as attribute6,
       null as attribute7
from dual
union all
select  null as lvl,
       'Una Seconda Etichetta ' as label,
       '#'as target,
       null as attribute1,
       null as attribute2,
       null as attribute3,
       null as attribute4,
       'Valore del Badge' as attribute5,
       null as attribute6,
       null as attribute7
from dual

• Una volta creata la Lista Dinamica puoi inserirla nella pagina APEX esattamente come ti ho spiegato per la Lista Statica

• Ricordati ti impostare anche in questo caso il template Badge List

Questo è il risultato finale

Conclusioni

Bene, direi che è tutto per il momento. Ora dovresti avere tutte le conoscenze di base di cui hai bisogno per costruire e personalizzare a dovere le liste.

Se non lo hai fatto, ti invito ad iscriverti alla pagina ufficiale di APPin5Minuti e di seguirmi sul Linkedin e Twitter.

Condivi con i tuoi amici e colleghi questo articolo per supportare questo progetto. Mi faresti davvero molto felice!

Un abbraccio

Daniele