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

Il menù di navigazione di una qualsiasi applicazione sviluppata in Oracle APEX è una Lista APEX.

Ciascuna singola voce di menù (chiamata List Entry) è caratterizzata da alcune proprietà specifiche come una etichetta, una icona e ovviamente l’URL di destinazione.

Oracle APEX supporta due tipologie di lista.

Quella più comune è la Lista Statica che, come suggerisce il nome, non può essere modificata dinamicamente.

Una Lista Dinamica, d’altro canto, è basata su una query SQL ed è molto utile quando la sua struttura dipende ad esempio dal valore di un Page Item o da un parametro di sessione.

In questo articolo desidero spiegarti come configurare una Lista Dinamica in Oracle APEX.

Come creare 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

• Dai un nome alla lista, seleziona il tipo lista Dynamic e clicca Next.

• Inserisci la query per inizializzare la Lista APEX e clicca Next

• Clicca Create per completare la configurazione della lista

La cosa veramente importante che devi tenere a mente quando vuoi creare una lista dinamica è la struttura della query SQL.

Infatti, affinché APEX sia in grado di inizializzare correttamente la lista, deve contenere nella sua definizione specifiche colonne.

Il rischio è che la lista non funzioni a dovere oppure che la pagina APEX che poi dovrà utilizzarla vada in errore.

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)

Non è detto che tutte le colonne debbano necessariamente restituire un valore e, in particolar modo per quanto riguarda gli User Defined Attributes (attribute1,…, attribute10) devono essere inizializzati in funzione del template utilizzato.

Ad esempio, questa è una query che puoi usare per fare una prima prova

select null as lvl,
       'Etichetta Nr. 1' as label,
       '#' as target,
       null as attribute1,
       null as attribute2,
       null as attribute3,
       null as attribute4,
       null as attribute5,
       null as attribute6,
       null as attribute7,
       null as attribute8,
       null as attribute9,
       null as attribute10
from dual
union all
select null as lvl,
       'Etichetta Nr. 2' as label,
       '#' as target,
       null as attribute1,
       null as attribute2,
       null as attribute3,
       null as attribute4,
       null as attribute5,
       null as attribute6,
       null as attribute7,
       null as attribute8,
       null as attribute9,
       null as attribute10
from dual

Ecco le cose più importanti da tenere a mente:

• 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 e deve sempre essere presente. 
• La successiva colonna obbligatoria è l’URL target, anch’essa è obbligatoria.
• I valori da attribute1 ad attribute10 sono chiamati user defined attributes e servono a personalizzare l’aspetto della lista. Non devono necessariamente essere tutti inizializzati e dipendono dal template utilizzato

Alcuni esempi di Liste Dinamiche

Ora che hai acquisito i concetti base delle liste dinamiche, facciamo qualche esempio concreto.

A tal proposito qui sotto puoi trovare uno script SQL che puoi usare per creare una tabella custom che utilizzeremo per fare questo esercizio.

-- create tables
create table list_entries (
    id                             number generated by default on null as identity 
                                   constraint list_entries_id_pk primary key,
    label                          varchar2(30 char),
    order_num                      number,
    url                            varchar2(4000 char),
    parent                         number
                                   constraint list_entries_parent_fk
                                   references list_entries on delete cascade
);

Puoi scaricare un data set di esempio da questo link.

Esempio 1: lista semplice

Il primo esempio che implementeremo è una lista semplice.

• Crea una nuova Lista Dinamica utilizzando la seguente Query SQL

SELECT null lvl, 
       label, 
       '#' target
FROM  list_entries  
ORDER BY label

• Accedi all’APP Builder di Oracle APEX
• Crea una Region di tipo List

• Vai alle proprietà della Region List ed imposta la lista che abbiamo creato

• Esegui la Preview per vedere il risultato

Esempio 2: lista filtrata

In questo esempio costruiamo una lista che può essere filtrata usando un Page Item.

• Dall’APP Builder apri la definizione della pagina e crea un nuovo Page Item di tipo Text Item con queste proprietà

• Crea una nuova Lista Dinamica usando questa Query SQL

SELECT null lvl, 
       label, 
       '#' target
FROM  list_entries  
WHERE INSTR(trim(upper(label)), :P25_LIST_ENTRY) > 0
ORDER BY label

• Configura una nuova region di tipo List.
• Per comodità puoi inglobare il Page Item che hai creato dentro alla Region List

• Configura una nuova Dynamic Action

• Queste sono le proprietà della Dynamic Action

• Esegui la Preview per vedere il risultato

Esempio 3: lista gerarchica

Con un po’ di sforzo è possibile creare delle liste gerarchiche, utilissime se vuoi costruire del menù di navigazione dinamici.

• Crea una nuova Lista Dinamica usando questa Query SQL

select level, 
       label, 
       '#' target
from list_entries
start with parent is null
connect by prior id = parent
order siblings by label

• Configura una nuova region di tipo List.

• Seleziona la Region List e vai in Attributes
• Seleziona il template Menu Bar

• Questo è il risultato finale