Forse creare una APP To-Do List in non sarà un lavoro particolarmente entusiasmante (forse), considerando soprattutto il fatto che ne esistono davvero tante.

Tuttavia, ho pensato che sviluppare una APP in questo tipo potesse essere un buon esercizio da fare, utile soprattutto per apprendere alcune specifiche funzionalità di Oracle APEX molto interessanti.

Se non sei completamente disorientato dall’idea di creare l’ennesima app To-Do List e vuoi imparare qualche trucco, questo tutorial è quello che fa per te.

Vedremo come usare un Classic Report e come puoi personalizzarlo con un Template HTML, inserendo delle funzionalità che non sono previste nei template standard.

A questo link puoi trovare una applicazione di demo che ho creato appositamente per questo tutorial.

Prima di iniziare

In questo tutorial dovrai scrivere un po’ di codice PL/SQL – trattandosi di Oracle APEX penserai che è qualcosa di abbastanza scontato, vero?

Inoltre utilizzeremo un Classic Report che però andremo a personalizzare utilizzando un template HTML, creato appositamente per questa applicazione.

Per quanto riguarda il database, l’unico oggetto che dovrai creare è una tabella in cui verranno salvati i task.

Qui sotto puoi trovare lo scripts da usare.

CREATE TABLE  "XX02_TASKS" 
   (	"ID" NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER  NOCYCLE  NOKEEP  NOSCALE  NOT NULL ENABLE, 
	"CREATION_DATE" DATE, 
	"CREATED_BY" VARCHAR2(4000 CHAR), 
	"NAME" VARCHAR2(500 CHAR), 
	"DESCRIPTION" VARCHAR2(4000 CHAR), 
	"NOTES" CLOB, 
	"STATUS" VARCHAR2(250 CHAR), 
	"DUE_DATE" DATE, 
	"IS_IMPORTANT" VARCHAR2(1 CHAR), 
	"REPEAT" VARCHAR2(1 CHAR), 
	"FREQUENCY_VALUE" NUMBER, 
	"FREQUENCY_UOM" VARCHAR2(250 CHAR), 
	"TAGS" VARCHAR2(4000 CHAR), 
	"OWNER" VARCHAR2(4000 CHAR), 
	"FREQUENCY" VARCHAR2(500), 
	 CONSTRAINT "XX02_TASKS_IS_IMPORTANT_CC" CHECK (is_important in ('Y','N')) ENABLE, 
	 CONSTRAINT "XX02_TASKS_ID_PK" PRIMARY KEY ("ID")
  USING INDEX  ENABLE
   )
/
CREATE OR REPLACE EDITIONABLE TRIGGER  "XX02_TASKS_BIU" 
    before insert or update  
    on xx02_tasks 
    for each row 
begin 
    if inserting then 
            :new.created_by := coalesce(sys_context('APEX$SESSION','APP_USER'),user); 
    end if; 
end xx02_tasks_biu; 
/
ALTER TRIGGER  "XX02_TASKS_BIU" ENABLE
/

Come funziona l’applicazione To-Do List

L’applicazione To-Do List che costruiremo è fatta da 2 pagine: una Home Page (realizzata usando dei Reports) e una Form.

L’Home Page dell’applicazione è divisa in due sezioni principali: Open Task (nella parte alta) e Completed Task (nella parte bassa).

In Open Task puoi vedere elenco di tutte le attività da completare.

Per ciascun task viene mostrato un titolo, una descrizione e la data di scadenza.

Alcuni task potrebbero essere configurati come ricorrenti e lo puoi vedere grazie all’icona visualizzata vicino alla data di scadenza del task.

Da questa schermata è possibile chiudere il task cliccando sul pulsante Completa Task.

Quando un task viene chiuso l’applicazione sposta automaticamente il task nella sezione Completed Task.

Cliccando sul bottone mostra/nascondi è possibile nascondere la regione Completed Task.

Cliccando sul bottone Aggiungi ai Preferiti il task viene spostato in alto nella lista.

Per poter vedere ed aggiornare i dettagli del task devi cliccare sulla riga del task: viene aperta una pagina (modale) attraverso la quale puoi modificare gli attributi del task.

Usando i pulsanti nella toolbar puoi salvare le informazioni, approvare o eliminare il task.

Se un task è segnato come ricorrente, alla sua chiusura verrà automaticamente creato un nuovo task con una data di scadenza stabilita dalla frequenza.

PARTE 1: crea una applicazione di tipo Report + Form

Per creare la nostra To-Do List APP partiremo da una semplice applicazione di tipo Report with Form usando la procedura guidata di Oracle APEX.

• Accedi all’App Builder di APEX e crea una nuova applicazione.
• Clicca su Create Page

• Seleziona il tipo Form e clicca Next.

• Seleziona il tipo pagina Report with Form e clicca Next.

• Inserisci i seguenti parametri
  • Report Type: Classic Report
  • Report Page Name: To-Do List Home Page
  • Form Page Name: Open Task
  • Form Page Mode: Modal Dialog

• Seleziona la tabella del database che l’applicazione utilizzerà per salvare le informazioni.

• Specifica la colonna ID come Primary Key

• Clicca su Create per completare la procedura guidata.
• Esegui la preview dell’applicazione.

Seppur ancora ad uno stato embrionale, la nostra applicazione è già funzionante: puoi aggiornare i record della tabella XX02_TASKS, puoi creare dei nuovi task piuttosto che eliminarli.

Tuttavia, non esiste ancora nessuna forma di validazione dei dati ed il layout è decisamente molto poco appetibile.

Tra poco ti mostrerò come configurare la pagina principale dell’applicazione e successivamente la form di dettaglio del task.

PARTE 2: configura l’Home Page

Quando un utente si collega all’applicazione deve vedere prima di tutto i task che devono essere completati.

Nella nostra applicazione un task può avere 2 stati:

• NEW: task da completare
• COMPLETE: task completato

Quindi, la prima cosa da fare consiste nel creare due regioni di tipo Classic Report: Open Task e Completed Task.

Un Report lo abbiamo già creato, usando la procedura guidata, pertanto basta crearne un altro.

• Dall’APP Builder apri la definizione della pagina di tipo Classic Report che hai creato.
• Seleziona il report.
• Premi il pulsante destro e seleziona Duplicate.
• Per comodità rinomina i due report

• Vai alla proprietà Source di ciascun report.
• Cambia il tipo a SQL Query ed aggiungi una condizione nella clausola WHERE per filtrare i dati
  • Open Task: STATUS = ‘NEW’
  • Completed Task: STATUS = ‘COMPLETED’

• Avendo creato il secondo report come copia del primo, dovresti avere 2 pulsati CREATE.
• Elimina uno dei due e sposta quello rimanente dentro una nuova regione di tipo Static Content creata che chiamerai Toolbar.

Arrivati a questo punto dovresti avere una pagina con due report in formato tabellare che mostrano rispettivamente i task aperti e quelli completati.

Benché funzionali, in report tabellari in questo caso non sono la scelta più bella.

Per questo motivo vedremo come possiamo utilizzare in modo furbo il Classic Report che, a dispetto del nome forse poco accattivante, è un componente molto versatile.

PARTE 3: configura il Classic Report

Quello che ti spiegherò adesso andrà fatto per entrambi i due report: Open Task e Completed Task.

• Seleziona il report Open Task
• Clicca su Attributes > Appearance > Template e seleziona il template Media List

• Clicca su Template Options e seleziona la Show Badges

• Esegui la preview dell’applicazione. Come puoi vedere l’aspetto del report è cambiato.
• Tuttavia, non sta mostrando i campi estratti dalla query. Le stringhe che vedi sono dei placeholders che sono stati definiti nel template HTML che abbiamo selezionato (Media List)

• Per visualizzare le informazioni devi modificare la query del report aggiungendo le seguenti colonne
  • LIST_TITLE: titolo principale del record
  • LIST_TEXT: descrizione del record
  • LIST_BADGE: formattato posizionato in alto a destra del record
  • ICON_CLASS: icona del record
  • LINK: link della pagina da aprire se si clicca sul record. Nel nostro caso sarà la pagina di dettaglio che abbiamo creato prima.

• Il risultato finale è quello che vedi sotto: decisamente molto più bello, non credi?

C’è un modo facile per sapere quali sono i tag da usare per configurare un Classic Report?

La risposta è si.

• Seleziona il Report
• Vai in Attributes > Appearance
• Clicca su Template > Go to Classic Report Template

• Clicca su Edit Component

• Nella sezione Row Templates puoi trovare il template HTML che viene utilizzato per formattare la singola riga del report.
• All’interno della sua definizione del template dovresti riconoscere i TAG (ES: #LIST_TITLE#) che abbiamo usato prima per visualizzare le informazioni nel report.

PARTE 4: crea un Template HTML personalizzato

Lavorando ancora un po’ sulle proprietà di grafiche della pagina dovresti ottenere un risultato più o meno simile alla foto seguente.

Ottimo lavoro, sei a buon punto!

Volendo, potresti anche fermarti anche qui perché hai già tutto quello che serve.

Nella sezione in alto puoi consultare tutte le attività da completare con la relativa data di scadenza mentre nella sezione in basso possono essere visualizzati i task completati, racchiusi in una regione sempre di tipo Classic Report di tipo Collapsible.

Inoltre, è interessante notare come per fare tutto questo abbiamo scritto davvero pochissimo codice SQL (quello necessario a filtrare i record nelle due viste).

Per rendere questa APP più immediata da usare, ho pensato di creare qualche funzionalità avanzata.

Per spiegare cosa intendo partiamo dalla considerazione che in questo momento l’unico modo che c’è per aggiornare lo stato di un task consiste nel cliccare sulla riga, aprire la Form Detail e cambiare lo stato del record.

Rispetto ad altre APP che fanno lo stesso lavoro, questa soluzione non è molto bella soprattutto perché è poco immediata.

Ho pensato di creare un pulsante a livello di riga che aggiorna lo stato del task direttamente dalla pagina principale, senza dover aprire la Form Detail.

Purtroppo, il template che abbiamo usato (Media List) non supporta questa possibilità e tra quelli disponibili non ho trovato nulla di utile. Quello di cui ho bisogno è una template Media List personalizzato.

Vediamo come fare.

• Dall’ App Builder, clicca su Shared Components > Templates
• Qui puoi vedere tutti i template che sono stati automaticamente installati all’interno dell’applicazione.
• Clicca su Classic Report > Media List

• Cliccando su Edit Component puoi modificare direttamente questo template.
• In alternativa puoi crearne uno nuovo come copia (personalmente preferisco questo approccio).
• Clicca con il pulsante destro del mouse e seleziona Copy.

• Chiama il nuovo template Task List e premi Copy.

• Seleziona il template che hai creato

• Nella pagina di configurazione del template vai alla sezione Row Template, dove dovresti trovare 2 sub-template che vengono applicati in funzione della presenza del tag #LINK#

• Inserisci nel campo Row Template 1 il codice HTML seguente, una versione modificata del Media List

<li class="t-MediaList-item #LIST_CLASS#">
   <button id="action-button-1" type="button" title="#ACTION_TITLE#" aria-label="#ACTION_TITLE#" class="#ACTION_NAME# t-Button t-Button--noLabel t-Button--icon t-Button--hot t-Button--large t-Button--link" task-id="#ID#"><span id="action-button-icon-1" aria-hidden="true" class="t-Icon #ACTION_ICON_CLASS#"></span></button>
   <a href="#LINK#" class="t-MediaList-itemWrap #LINK_CLASS#" #LINK_ATTR#>
      <div class="t-MediaList-body">
         <h3 class="t-MediaList-title">#LIST_TITLE#</h3>
         <p class="t-MediaList-desc">#LIST_TEXT#</p>
		 
      </div>
      <div class="t-MediaList-badgeWrap">
        <span class="t-MediaList-badge #ICON_BADGE#">#LIST_BADGE#</span></span>
      </div>
   </a>
<button id="action-button-2" type="button" title="#ACTION_TITLE2#" aria-label="#ACTION_TITLE2#" class="#ACTION_NAME2# t-Button t-Button--noLabel t-Button--icon t-Button--hot t-Button--large t-Button--link" task-id="#ID#"><span id="action-button-icon-2" aria-hidden="true" class="t-Icon #ACTION_ICON_CLASS2#"></span></button>
</li>

• Il template che inserisce a sinistra e a destra della riga 2 pulsanti che, se premuti dall’utente, possono scatenare una Azione Dinamica (Dynamic Action).
• Questi sono i tag custom che ho aggiunto al template:
  • ACTION_TITLE (ACTION_TITLE2): titolo del pulsante
  • ACTION_NAME (ACTION_NAME2): nome dell’azione, servirà per eseguire l’azione dinamica
  • ID: id del task
  • ACTION_ICON_CLASS (ACTION_ICON_CLASS2): icona da visualizzare

• Clicca sul report Open Task e modifica la query aggiungendo i nuovi tag

• Seleziona la colonna ID e verifica che sia di tipo Plain Text

• Se esegui la preview dell’APP dovresti ottenere un risultato simile a questo dove dovresti vedere dei pulsanti.

In questo momento i pulsanti, se cliccati ,non eseguono nessuna azione.

Implementare il codice per aggiornare lo stato del record.

PARTE 5: implementa le Dynamic Action

Nel template custom che abbiamo configurato poco fa ho inserito un pulsante.

Alcune suoi attributi HTML come class, title, label sono dinamici.

<button id="action-button-1" type="button" title="#ACTION_TITLE#" aria-label="#ACTION_TITLE#" class="#ACTION_NAME# t-Button t-Button--noLabel t-Button--icon t-Button--hot t-Button--large t-Button--link" task-id="#ID#"><span id="action-button-icon-1" aria-hidden="true" class="t-Icon #ACTION_ICON_CLASS#"></span></button>

Focalizziamoci sulla proprietà class che, valorizzata dinamicamente dalla query SQL, può assumere 2 valori:

• completeTask
• uncompleteTask

Useremo l’attributo class di questo pulsante per richiamare rispettivamente 2 Dynamic Action, la prima che aggiorna lo stato del task a COMPLETE e la seconda, invece, a NEW.

L’attributo HTML task-id, invece, sarà valorizzato con l’ID del task (o del record) da processare. Pe recuperare a runtime l’id del record dal quale ho scatenato l’azione dinamica useremo un semplicissimo codice JavaScript.

• Dall’App Builder, clicca su Dynamic Action > Click

• Crea una nuova Azione Dinamica con queste proprietà
  • Name: completeTask
  • Event: Click
  • Selection Type: jQuery Selector
  • jQuery Selector: .completeTask (deve essere uguale al valore della proprietà class del pulsante che deve essere intercettato)

• Nella sezione Advanced imposta la proprietà Event Scope su Dynamic

• Aggiungi una nuova nuova Action di tipo Set Value
  • Action: Set Value
  • Set Type: JavaScript Expression
  • JavaScript Expression: this.triggeringElement.getAttribute(‘task-id’);
  • Selection Type: Items(s)
  • Item(s): PX_SELECTED_TASK

• PX_SELECTED_TASK è Item di tipo Hidden che ho creato a livello di pagina e che uso come campo di appoggio per salvare l’ID del task su cui ho cliccato.
  • Imposta al proprietà Value Protected di questo Item a false.

• Aggiungi una nuova Action stavolta di tipo Execute Server-Side Code
  • Action: Execute Server-Side Code
  • Language: PL/SQL
  • PL/SQL Code: begin update xx02_tasks set status = ‘COMPLETE’ where id = :p9_selected_task; commit; end;
  • Items to Submit: PX_SELECTED_TASK

• Aggiungi una terza Action per gestire il Refresh automatico delle due regioni (Open Tasks e Completed Tasks).

• Questa dovrebbe essere la situazione finale.

• Esegui la preview dell’APP e premi sul bottone.

• Il record viene aggiornato nel database e viene “spostato” nella tabella dei task completati dove ci sarà il bottone per riportare un eventuale task completato nello stato “da completare”.

• Usando sempre lo stesso metodo ho creato in totale 4 Dynamic Action per gestire le quattro azioni previste
  • completeTask: completa il task (update xx02_tasks set status = ‘COMPLETE’ where id = :pX_selected_task;)
  • uncompleteTask: scompleta il task (update xx02_tasks set status = ‘NEW’ where id = :pX_selected_task;)
  • setImportant: aggiunge il task ai preferiti (update xx02_tasks set is_important = ‘Y’ where id = :pX_selected_task;)
  • setNotImportant: rimuove il task dai preferiti (update xx02_tasks set is_important = ‘N’ where id = :pX_selected_task;)

PARTE 6: configura la Form

Completata l’home page della nostra APP possiamo concentrarci sulla la form che serve per inserire un nuovo task piuttosto che per aggiornare le informazioni di un task esistente.

• Apri la definizione dalla form che è stata creata con la procedura guidata e configura i campi in questo modo:

• Configura la LOV del campo PX_FREQUENCY con i seguenti valori

• Seleziona il campo PX_REPEAT della form

• Crea una Dynamic Action con queste proprietà
  • When > Event: Change
  • When >Selection Type: Item(s)
  • When >Item(s): PX_REPEAT
  • Client-Side Condition > Type: Item: Value
  • Client-Side Condition > Item: Value
  • Client-Side Condition > Value: Y

Per modificare lo stato del task ho creato 2 pulsanti, ciascuno dei quali esegue una Dynamic Action che aggiorna lo stato del task nel database.

• SET_COMPLETE
• SET_NOT_COMPLETE

• Seleziona il bottone SET_COMPLETE
• Crea una Dynamic Action
  • Event: Click
  • Selection Type: Button
  • Button: SET_COMPLETE

• Aggiungi una Action di tipo Execute Server-side Code che esegue il seguente codice PL/SQL: begin update xx02_tasks set status = ‘COMPLETE’ where id = :pX_id; end;
• Aggiungi una Action di tipo Close Dialog.

• Seleziona il pulsante SET_UNCOMPLETE e configura una nuova Dynamic Action identica alla precedente con l’unica differenza che lo script da lanciare per aggiornare i dati sarà questo: begin update xx02_tasks set status = ‘NEW’ where id = :pX_id; end;

L’ultima cosa che dobbiamo fare per completare la configurazione è far sì che il pulsante SET_COMPLETE venga mostrato solo se lo stato del task è NEW.

Viceversa, il pulsante SET_UNCOMPLETE deve essere mostrato se lo stato del task è COMPLETED.

• Seleziona il bottone SET_COMPLETE vai alla sezione Server-side Condition
• Imposta le seguenti proprietà
  • Type: Expression
  • Language: PL/SQL
  • PL/SQL Expression:
    • Pulsante SET_COMPLETE= :PX_STATUS = ‘NEW’
    • Pulsante SET_NOT_COMPLETE= :PX_STATUS = ‘COMPLETE’

Alla chiusura della form modale la pagina principale deve aggiornarsi automaticamente.

• Seleziona il report Open Task nell’Home Page

• Aggiungi una nuova azione dinamica Close Dialog – Open Task configurata in questo modo:
  • Event: Dialog Closed
  • Selection Type: Region
  • Region: Open Task
• Un azione dinamica di questo tipo scatta tutte le volte che viene chiusa una finestra modale che è stata aperta dalla regione Open Task

• Aggiungi 2 Action:
  • Refresh della regione Open Task
  • Refresh della regione Completed Task

In Conclusione

In questo tutorial abbiamo imparato diverse cose, tutte molto interessanti.

Abbiamo esplorato l’enorme versatilità del Classic Report che non si limita a visualizzare i dati in formato tabellare (come un Interactive Report o una Interactive Grid) ma permette rappresentazioni dei dati anche molto creative.

Abbiamo capito come modificare un template per adattarlo alle nostre esigenze ed abbiamo imparato come richiamare una Dynamic Action da un report APEX.

Potrai usare questa APP sia come applicazione stand-alone sia integrandola all’interno di una applicazione APEX già esistente.

Fammi sapere nei commenti se questo tutorial ti è piaciuto e se c’è qualche argomento che vorresti approfondire!

Un abbraccio

Daniele