Una volta definito il nuovo DB sotto ogni aspetto sono partiti i lavori per la progettazione del nuovo applicativo denominato HMSDOCUM utilizzando il già citato BMF3.
HMSDOCUM sarà composto da tre macroaree:
• La prima, denominata Documentale, permetterà al suo interno di operare su Delibere, Determine e Convenzioni;
• La seconda, denominata Gestione CIG, permetterà al suo interno di gestire tutto ciò che riguarda i CIG;
• La terza, denominata Gestione sito, permetterà di modificare tutti gli aspetti relativi al funzionamento del sito.
Questo lavoro di tesi è concentrato principalmente su tre aspetti: le Delibere, la Gestione CIG e la Gestione sito; le parti relative a Determine e Convenzioni verranno invece sviluppate in un secondo momento. Ogni macroarea sarà quindi analizzata separatamente allegando, per ognuna di esse, una mappa concettuale utile a capire il workflow che seguiranno gli utenti in fase di utilizzo reale dell’applicativo; ogni macroarea sarà infatti composta da diversi oggetti astratti, ognuno con la propria impostazione e, se necessario, con la propria customizzazione, andando così a formare un’interfaccia utente che ha lo scopo di rendere il più intuitivo e chiaro possibile lo svolgimento del proprio lavoro da parte del personale amministrativo. Ogni mappa indicherà gli spostamenti che seguiranno diversi eventi come il click su un tasto o su un link ipertestuale o il salvataggio dei dati: ognuno di essi sarà commentato opportunamente in maniera tale da rendere chiaro il flusso previsto.
Ogni oggetto astratto creato sarà quindi salvato nella tabella T_OBJECT del BMF stesso, mentre per le customizzazioni sono stati utilizzati diversi file:
• Un file JavaScript denominato hmsdocum.js, il quale contiene il codice vero e proprio che indica al BMF quali istruzioni eseguire;
• Un file JavaScript denominato customization.js, all’interno del quale sono state dichiarate tutte le customizzazioni create;
• Diversi file HTML contenenti ognuno un template personalizzato utilizzabile dai diversi oggetti astratti; ogni template rappresenta una visualizzazione personalizzata di un oggetto astratto.
In molte customizzazioni vengono utilizzare delle chiamate Ajax: questa è una tecnica di sviluppo software per la realizzazione di applicazioni web interattive che si basa su uno scambio di dati in background fra web browser e server, e che consente l'aggiornamento dinamico di una pagina web senza esplicito caricamento da
parte dell'utente.
39
il comportamento della pagina esistente.14
Avremo modo di vedere in quasi tutte le customizzazioni una chiamata di questo tipo, utilizzata quindi per ricavare dei particolari dati che saranno utilizzati dal BMF.
Dovendo progettare un sistema che permetta di caricare file e, successivamente, di poterli scaricare in modo da consultarli, sono stati implementati due servizi, già presenti nel BMF, relativi a queste funzionalità,. L’upload di un file avverrà all’interno di un oggetto di tipo input form, e richiede l’introduzione di una customizzazione che introdurrà una nuova funzione, chiamata generalmente “loadDati”, e la riscrittura del metodo di salvataggio dei dati, introducendo al suo interno una chiamata Ajax utile ad invocare il metodo di upload fornito dal BMF stesso; verrà inoltre utilizzato un template customizzato per guidare l’azione di
caricamento da parte dell’utente.
Sarà inoltre necessario, in fase di caricamento di un file, compilare automaticamente tre campi: • Un campo relativo al nome del file salvato senza la sua estensione;
• Un campo relativo all’estensione del file salvato;
• Un campo relativo al nome, completo di estensione, del file salvato.
La compilazione automatica di questi campi permetterà successivamente di effettuare il download del file caricato.
I file caricati verranno nominati secondo la seguente regola:
TipoDocumento_NomeDocumento_CodiceProgressivo_Timestamp.estensione
Quindi, se ad esempio devo caricare una Delibera salvata come un file nominato MyDelibera.pdf e sarà il primo documento caricato nel sistema, il file sul server verrà nominato in questo modo:
DEL_MyDelibera_1_TIMESTAMP.pdf
Le tipologie di file previste sono:
• Delibera, denominato come DEL e salvate all’interno di una cartella chiamata DEL; • Allegati, denominati come ALL e salvati in una cartella chiamata ALL;
• Convenzioni, denominate come CNV e salvate in una cartella chiamata CNV.
Questa regola di nomenclatura permetterà, in futuro, di risalire alle diverse tipologie di documenti caricati e alle diverse versioni di essi: non sarà infatti possibile sovrascrivere un documento, pur caricandone una versione aggiornata, ed entrambe le versioni saranno identificabili attraverso il loro codice univoco, ovvero la PK, legato al record salvato nella relativa tabella del DB denominata Documento. Un input form che utilizza il servizio di upload potrà inoltre svolgere tutte le funzionalità classiche di un oggetto astratto di questo tipo, e quindi dovrà essere configurato secondo le regole standard previste dal BMF
e discusse in precedenza.
Vediamo quindi le diverse istruzioni introdotte all’interno della customizzazione introdotta per eseguire l’upload.
Iniziamo con quella relativa al caricamento di un diverso template:
template: CustomTemplates.myInputformItemViewDel
Con questa istruzione si indica quale template dovrà utilizzare l’input form, specificando il nome del file creato in precedenza, scritto in linguaggio HTML; in questo modo verrà indicato al BMF quale aspetto dovrà avere
l’oggetto astratto creato.
La funzione “loadDati” viene richiamata ogni volta in cui l’utente seleziona il file da caricare: le operazioni che svolge, infatti, riguardano la variazione di ciò che viene mostrato all’utente mostrando il nome del file caricato e un’icona che conferma la riuscita dell’operazione; questa piccola modifica è necessaria per rendere chiaro lo svolgimento dell’azione dell’utente. Ecco un esempio di quel che verrà mostrato:
40
Figura 4.1, esempio di modifica della visualizzazione
La funzione “mySave”, che riscrive il metodo di salvataggio standard del BMF, svolgerà le seguenti istruzioni: • Imposta i campi del DB da compilare in automatico, utilizzando il Timestamp;
• Effettuerà la chiamata Ajax utile a richiedere il servizio di upload: $.ajax({ url : Global.serverDomain+Global.cxt+"/ws/config/uploadFile.bmf", type : 'POST', data : formData, cache : false, contentType : false, processData : false,
success : function(data, textStatus, jqXHR) {…}
• Inoltre, prima di completare il salvataggio, effettuerà i controlli di validità: i campi dell’input form dovranno essere compilati correttamente e l’utente dovrà aver selezionato un file da caricare.
Il download, invece, è implementabile configurando correttamente un oggetto di tipo report, senza la necessità
di introdurre una customizzazione.
L’istruzione da utilizzare sarà la seguente: '<a
href="../config/dowloadFile.bmf?name='||CAMPO_NOME_DOCUMENTO||'&nameOri ginal='||CAMPO_NOME_DOCUMENTO||''||CAMPO_ESTENSIONE_DOCUMENTO||'&subdir =NOME_SUBDIRECTORY&contentDisposition=attachment">'||CAMPO_NOME_COMPLET O||'</a>' AS CAMPO_NOME_COMPLETO
In questa istruzione vengono indicati i campi che contengono il nome del documento e la sua estensione, più un terzo campo su cui verrà posto il link per far partire il download. Il terzo campo utilizzato sarà il nome, completo di estensione, del file caricato, e corrisponde a ciò che viene mostrato all’utente: l’utilizzo di questo campo è una scelta progettuale in quanto la sua valorizzazione non è importante ai fini del corretto funzionamento del download. Infine, tramite l’istruzione “subdir” sarà possibile specificare la cartella in cui è stato salvato il file: infatti, come detto in precedenza, le diverse tipologie di documenti verranno salvate in diverse cartelle.
All’interno dell’applicativo web sviluppato saranno presenti delle tipologie di customizzazioni utilizzate molteplici volte, ovviamente adattate ai diversi casi: mostriamo di seguito quelle più utilizzate, mentre verranno analizzate, caso per caso, quelle uniche nei paragrafi relativi alle diverse funzionalità.
Una customizzazione introdotta per diversi oggetti è quella relativa alla personalizzazione del titolo dell’oggetto stesso: quest’indicazione è utile per rendere chiaro all’utente quale operazione sta svolgendo o di
quale elemento sta visualizzando i dati.
Per effettuare questo tipo di personalizzazione si è reso necessario creare degli oggetti Select che, tramite delle QUERY apposite, fornissero una descrizione dell’elemento su cui si sta lavorando; quindi, tramite una chiamata Ajax, si impostano i titoli dei diversi oggetti, utilizzando diverse funzioni per report e input form. Infatti, nel caso dei report, la funzione utilizzata è la seguente:
41 onRender: function(){ var codsel="-99"; $.ajax({ type: "POST", data: [], async: false, dataType: Global.dataType,
contentType: "application/json; charset=utf-8", url: Global.serverDomain+Global.cxt+"/ws/config/paramInSession.bmf", success: function(response){ codStato=Number(response.codsel); } }); $.ajax({ type: "POST", data: {name1:'AA_T_STATO_CODICE',value1:codStato}, dataType: Global.dataType,
contentType: "application/x-www-form-urlencoded; charset=utf-8", url: Global.serverDomain+Global.cxt+"/ws/config/
result.bmf?idObject=S_ST", success: function(response) {
$('#collapsible_data').children('div').children('div').children(' h3').text('Lo stato '+response[0]["DESCR"]+' può essere
aggiornato nei seguenti stati:'); }
}); }
In questo caso abbiamo riscritto la funzione “onRender” di un report in modo da effettuare diverse operazioni: • Inizialmente viene effettuata una chiamata Ajax per risalire a tutti i parametri in sessione, i quali verranno posti all’interno del dato strutturato denominato “response”, da cui verrà estratto l’unico di interesse, ovvero “codsel”;
• Dopodiché viene effettuata un’altra chiamata Ajax per la Select S_ST, passandogli come parametro il codice precedentemente ottenuto, che svolge la seguente QUERY:
SELECT
AA_T_STATO_CODICE AS val,
AA_T_STATO_DESCRIZIONE AS descr FROM AA_T_STATO
WHERE <condizioni>
In questo esempio avremo come risultato la descrizione ed il codice dello stato selezionato, in quanto la condizione “WHERE <condizioni>” utilizza automaticamente il parametro passato dalla chiamata Ajax, ovvero “codStato”, il quale è uguale a “codsel”; la descrizione verrà quindi impostata nel titolo del report andandola a prendere nuovamente dal dato strutturato “response”.
42
Figura 4.2, esempio di report con titolo personalizzato
Verrà quindi mostrato in alto lo stato precedentemente selezionato dall’utente, in questo caso specifico lo stato Bozza.
Per gli input form, invece, si utilizza la seguente funzione: afterLoadRecord: function (){ $('#btn_reset').val('Annulla'); $('#btn_reset').show(); $('#btn_save').hide(); $('#btn_delete').show(); $(inputform_id).children('div').children('div').children('span').hide() ;
var cod = $("#AA_REL_STATO_DOC_CODICE").val(); $.ajax({
type: "POST",
data: {name1:'AA_REL_STATO_DOC_CODICE',value1:cod}, dataType: Global.dataType,
contentType: "application/x-www-form-urlencoded; charset=utf-8", url:
Global.serverDomain+Global.cxt+"/ws/config/result.bmf?idObject=S_ TITLE",
success: function(response) {
$('#inputform_id').children('h4').text('Hai selezionato lo stato '+response[0]["DESCR"]+', clicca su Elimina per confermare oppure Annulla.');
43 $('#AA_T_STATO_CODICE_OUT,label[for ="AA_T_STATO_CODICE_OUT"]').hide(); $('#AA_REL_STATO_DOC_CODICE,label[for ="AA_REL_STATO_DOC_CODICE"]').hide(); } }); return true; }
In questo caso abbiamo riscritto la funzione “afterLoadRecord”: essa entra in atto non appena viene popolato l’input form con dei dati provenienti da un report presente nella stessa pagina. Per far avvenire ciò bisogna scrivere, nella QUERY del report, la seguente istruzione:
'<a href="#loadRecord/idObject=NOME_INPUTFORM&name1=NOME_CAMPO&value1=' ||NOME_CAMPO|| '">Testo mostrato all’utente</a>' AS ALIAS_CAMPO
Questa istruzione crea un link ipertestuale, sul campo specificato, utilizzando la funzione “loadRecord”: quando questo viene cliccato dall’utente verranno caricati i dati selezionati nell’input form specificato attraverso l’istruzione “idObject”; sarà inoltre possibile personalizzare il testo mostrato nella relativa cella.
Tornando alla customizzazione, le operazioni svolte da essa sono le seguenti:
• Inizialmente imposta la visualizzazione dei tasti dell’input form, specificando quali mostrare e quali no e variando l’etichetta del tasto di reset;
• Dopodiché viene nascosto, se presente, l’avviso sui controlli di integrità dei campi;
• Assegniamo quindi alla variabile “cod” il valore caricato nell’input form, che dipende dall’elemento selezionato dall’utente, e rappresenta il codice univoco della relazione molti a molti presente tra l’entità Stato e sé stessa;
• Infine, viene effettuata una chiamata Ajax che utilizza la Select S_TITLE, utilizzando come parametro la variabile “cod”, per trovare la descrizione dello stato selezionato attraverso la seguente QUERY: SELECT
AA_T_STATO_CODICE as key,
AA_T_STATO_DESCRIZIONE as descr FROM AA_T_STATO
WHERE AA_T_STATO_CODICE IN( SELECT
AA_T_STATO_CODICE_OUT FROM AA_REL_STATO_DOC WHERE <condizioni> )
Questa QUERY ne utilizza una seconda annidata che va a trovare il codice dello stato selezionato tramite la condizione che utilizza il parametro della chiamata Ajax; una volta trovato ne viene indicata la descrizione che verrà successivamente impostata all’interno del titolo. Seguono quindi due istruzioni utili per nascondere all’utente i campi dell’input form rimasti visibili.
44
Figura 4.3, esempio di input form con funzionalità personalizzate
Verrà quindi mostrato, nell’intestazione dell’input form, lo stato selezionato dall’utente: in questo caso specifico l’utente ha selezionato lo stato Provvisorio per eliminarlo dalle possibili evoluzioni dello stato Bozza, in quanto non previsto dal workflow delle Delibere. Da questo esempio si possono notare diverse modifiche al funzionamento standard dell’input form: non viene, infatti, soltanto modificato il suo titolo, ma viene modificata la sua visualizzazione in maniera tale da rendere chiara l’operazione svolta all’utente.
Un ulteriore tipologia di customizzazione utilizzata è quella relativa al reindirizzamento automatico delle pagine attraverso il comando “dispatcher”, ad esempio:
location.href =
"#dispatcher/idObject=V_ST_DOC_SEL_BIS&idObject=T_ST_DOC_SEL_BIS&idOb ject=BTN_ST_DOC_SEL&numRecPage=10&page=1"
All’interno del dispatcher dovranno essere specificati gli oggetti che andranno a popolare la nuova pagina richiamata e l’impaginazione che si vuole ottenere per gli oggetti di tipo report.
Un’altra customizzazione, questa volta comune a tutti gli oggetti di tipo input form, è quella relativa alla gestione dell’errore dovuto alla compilazione dei diversi campi. Se infatti un utente compila un campo in maniera errata, ad esempio mettendo delle lettere in un campo numerico oppure non compilando un campo obbligatorio, il salvataggio dei dati non potrà avvenire e verrà avvisato dall’applicativo stesso, il quale evidenzierà i campi non correttamente compilati con un avviso cromatico, ovvero colorandoli di rosso, e con
uno testuale, ovvero spiegandone il motivo.
La customizzazione introdotta permette di eliminare il colore rosso una volta che l’utente edita nuovamente il suddetto campo, ridefinendo quindi l’evento di click da parte dell’utente:
"click.has-error": function(e){
$(e.target).closest(".form-group").removeClass("has-error"); }
45
quando questo avviene il BMF dovrà rimuovere l’avviso cromatico di errore, mentre quello testuale rimarrà visibile. Dalla seguente immagine possiamo notare quindi i diversi avvisi sui vincoli di integrità e la rimozione dell’avviso cromatico:
Figura 4.4, esempio di avvisi sui vincoli di integrità
Notiamo che, a seguito del click dell’utente, il campo “Importo di liquidazione:” ha perso la colorazione rossa ma è rimasto l’avviso testuale che indica come compilarlo correttamente.
Infine, per semplificare la lettura, è utile specificare che per ogni oggetto astratto è stata utilizzata una particolare nomenclatura:
• I menù folder e item saranno denominati come P_NOME; • I report saranno denominati come V_NOME;
• Gli input form saranno denominati come T_NOME; • I filtri saranno denominati come F_NOME;
• I button saranno denominati come BTN_NOME; • I group button saranno denominati come GB_NOME.
Entriamo quindi nel dettaglio delle diverse componenti del nostro applicativo web.