UNIVERSITA` DI PISA Laboratorio di Basi di Dati 2004/2005 Documentazione del package GUI v. 1.9 Gruppo qualità interfacce: - Silvia Lollo - Sara Martinucci - Matteo Gabelletti - Nadia Pio - Maurizio Sambati - Giuseppe Zichittella INDICE: 1. Introduzione 2. Creare pagine html con GUI 3. Titoli, messaggi generici e messaggi di errore, testo e link 4. Form e caselle di input varie 5. Tabelle 6. Toolbar 7. Sessioni 8. Altre funzioni (in)utili 1. INTRODUZIONE Il package GUI mette a disposizione un kit di procedure, funzioni e costanti utili alla fase d'implementazione delle interfacce. Questo file descrive l'uso delle singole funzionalità. In particolare GUI permette di creare pagine html contenenti: - titoli della pagina e delle sezioni della stessa - messaggi generici, di errore - form, pulsanti, checkbox, combobox, textbox, textarea, radiobutton, campi nascosti per il passaggio di parametri di giro - controlli specifici per le date - tabelle comprensive di campi normali, d'intestazione e di errore - toolbar di navigazione standard 2. PRIMA DI PASSI NEL MAGICO MONDO DEL PACKAGE GUI (MODGUI)... Prima di compilare il package ed inviarlo al server oracle è bene conoscere le variabili da modificare per personalizzare il modgui e renderlo funzionante. Tutte queste variabili sono (paradossalmente) le costanti definite ad inizio file. Queste sono: - urlServerName: specifica la url del server oracle usato, comprensiva del path per caricare il modulo pls di apache. E` importante ricordarsi di verificare su quale server oracle state lavorando (oracle1, oracle2) e cambiare di conseguenza questa stringa. - userName: specifica il proprio nome utente oracle (NON lo username del CLI) Altre costanti sono presenti in questa sezione del file modgui.sql, non è necessario (anzi, è fortemente sconsigliato) che siano modificate ma in caso di testing è probabile che vogliate farlo. Tutte queste costanti non saranno documentate in questo file, sono comunque presenti dei commenti per gli sviluppatori per ciascuna di esse. 2. CREARE PAGINE HTML CON GUI Le due procedure principali per la creazione delle pagine HTML con il package GUI sono openPage() e closePage(). Come si evince dal nome openPage() dovrebbe essere richiamata prima di tutte le altre funzioni di GUI per la stampa della pagina, questa si occupa infatti di generare l'header html, includere i file javascript necessari e specificare i fogli di stile usati per la visualizzazione nel browser. closePage() viceversa dovrebbe essere usata solo al termine dell'output della pagina. openPage() ha due parametri opzionali importanti: title - specifica il titolo della pagina (nel tag dello header del file html, viene visualizzato dal browser nella barra del programma) javascript2 - specifica un opzionale file javascript personalizzato e secondario alla pagina. Deve essere indicata l'intera url. Entrambi i parametri sono opzionali, è bene inserire il titolo della pagina, è bene ridurre al minimo l'uso del secondo parametro per attenersi agli standard. closePage() non ha parametri. 3. TITOLI, MESSAGGI GENERICI E MESSAGGI DI ERRORE, TESTO E LINK Sono tre le procedure usate per stampare titoli all'interno della pagina e sono le printHX dove X deve essere sostituito con il tipo di titolo (numeri da 1 a 3, in ordine di importanza e grandezza del titolo). Per la stampa del testo semplice sono presenti le due funzioni printPlainText e printText. La differenza sostanziale delle due è che printPlainText inserisce il testo privo ti qualsiasi tipo di tag, mentre printText inserisce il testo in un paragrafo. Per la stampa dei messaggi le procedure sono printMessage e printErrorText. La prima per messaggi di informazio generici, la seconda per messaggi di errore visualizzati in rosso. NOTA: non c'è scritto da nessuna parte nel documento di qualità interfacce che i messaggi di errore visualizzati a inizio pagina devono essere in rosso, solo i nomi dei campi dovrebbero esserlo. Usate printMessage() sempre e comunque in questi casi e cercate di ridurre al minimo l'uso di printErrorText (potreste considerarla utile solo per visualizzare errori critici). Entrambe le funzioni non scrivono niente nel caso in cui il messaggio sia un valore nullo (stringa vuota). Tutte queste funzioni prendono un parametro unico che è la stringa da visualizzare. Utile nella formattazione del testo la procedura printNLine che permette di andare a capo. Un'altra funzione molto utile è la htmlEncode(), questa funzione prende un unico parametro stringa a cui applica alcune trasformazioni rimpiazzando alcuni caratteri speciali html (<,>,&) con i codici appropriati (<, >, &), la stringa trasformata viene restituita e non visualizzata a video. I Link HTML sono inseriti con la procedure printLink(). printLink() prende come parametri: - url: indica il nome della procedura plsql da richiamare (NON CONSENTE DI INSERIRE URL NORMALI) - name: nome del link, ovvero l'etichetta visualizzata nella pagina - newwnd: opzionale, valore booleano, se vero apre una nuova finestra alla pressione del link. 4. FORM E CASELLE DI INPUT VARIE Le caselle di input in un file HTML devono essere contenute in un tag <form> che identifica le form. openForm() e closeForm() si occupano di specificare inizio e fine di un form. La openForm() prende i seguenti parametri: - action: specifica la procedura plsql da richiamare a seguito della pressione di un tasto di submit del form - method: specifica il metodo di passaggio dei parametri alla procedura plsql (può essere 'GET' o 'POST') - other: permette di inserire attributi opzionali al form (es. 'onSubmit="return requestcheck(this)"'). Molti altre funzioni di modgui hanno il parametro form e si usa allo stesso modo. (a meno che non venga specificato altrimenti) closeForm() non ha parametri. other e method sono opzionali. Ad un form è associato il metodo di submit, questo viene invocato solo a seguito della pressione di un pulsante di submit o la chiamata diretta del metodo tramite javascript. Il pulsante di submit viene inserito con la funzione printSubmitButton(). I parametri di questa procedura sono: - label: etichetta visualizzata dal pulsante (es. 'Premi qui!') - name: nome del pulsante, se specificato viene passato un parametro ulteriore alla procedura plsql dell'action del form con questo nome e per valore la label del pulsante a seguito della pressione di questo tasto (se esistono due pulsanti di Submit con name diverso viene passato solo la variabile che indica il tasto premuto, non viene passata l'altra e se viene passata ha NULL come valore). - other Solo label è obbligatorio. Un altro pulsante standard delle form è il pulsante di Reset. Questo consente di riportare lo stato della form al momento del caricamento della pagina, resettando tutti i controlli di input al suo interno. I parametri di reset sono: - label: etichetta visualizzata dal pulsante (es. "Annulla") - other Solo label è obbligatorio. E' possibile inserire anche pulsanti generici nel form con la procedure printButton(). Questi pulsanti non hanno un comportamento definito e deve essere quindi associata loro una funzione javascript all'evento onClick. I parametri di questa procedura sono: - label - name - other identici a quelli di printSubmitButton. Si sconsiglia l'uso di questa procedura a meno che non sia necessario usarla. Di seguito l'elenco delle caselle di input HTML disponibili in modgui e le procedure usate per manipolarli. Sono descritti solo i parametri che si comportano in modo diverso da come ci si aspetta, i parametri obbligatori sono contrassegnati da asterisco. Il parametro name indica in tutti il nome della variabile passata alla procedura plsql richiamata dal submit, il valore della variabile è il contenuto del campo: - textbox: permette di inserire testo printTextBox(name*, length, defval, thesize, other): length: è la lunghezza del campo visualizzato defval: è il valore di default del campo thesize: è la dimensione massima del testo inserito all'interno del campo - password: casella di testo apposta per le password (sono visualizzati gli asterischi invece che la stringa contenuta) printPassword(name*, length) - checkbox: caselle di selezione (vero o falso) printCheckBox(name*, active, value, other): active: specifica se la casella di testo deve essere già spuntata o meno value: valore associato alla variabile passata nel caso in cui la casella sia spuntata prima del submit. Se la casella non è spuntata non viene passata nessuna variabile. - radiobutton: caselle di selezione mutuamente esclusive printRadioButton(name*, value, label, selected, other): un gruppo di radiobutton è costituito da un insieme di radiobutton con lo stesso nome. La variabile passata contiene il valore dell'unico pulsante selezionato ed è specificato dal parametro value. Selected indica se il radiobutton deve essere già selezionato o meno. - select: menù a tendina openSelect(name*, other), closeSelect(), printOption(value*, label*, selected): openSelect() e closeSelect() sono usati per racchiudere le opzioni del menù a tendina, printOption() per specificarle. Ogni opzione ha un valore che è quello associato alla variabile del nome del menù a tendina (specificato in openSelect()) se l'opzione è selezionata. selected permette di indicare se l'opzione è selezionata di default o meno. esiste anche una openLinkedSelect() che ogni volta che cambia valore fa causa la sottoposizione (submit) del form, utile per implementare menù a tendina collegati tipo Sedi, Aree e Gruppi. - textarea: caselle di testo su più righe printTextArea(name*, value, nrows, ncols, other): nrows, ncols: numero di righe e colonne della casella di testo (da visualizzare, non indicano in nessun modo la dimensione massima del campo) value: contenuto di default del campo - hiddenfield: campi nascosti passati tramite submit del form (utili per i parametri di giro che non devono essere visualizzati all'utente) printHiddenField(name*, value) printSession(sessione*): alias di printHiddenField( 'sessione', sessione ). Altri controlli utili per le interfacce (composti dei precedenti): - data: visualizza e permette la modifica di una data. printDateInput(prefix, data, yeardiff, canBeNull, other): genera 3 combobox, una per giorno, mese ed anno per inserire date. Ogni combobox ha per nome il prefisso specificato (default = 'laData') e '_ilGiorno', '_ilMese', '_lAnno'. data: data inizialmente visualizzata dalle combobox yeardiff: massima differenza fra l'anno più piccolo e l'anno massimo visualizzato nella combobox canBeNull: permette di inserire date nulle, altrimenti anche passando null al parametro data viene visualizzata la data attuale other: viene passato alle tre combobox come parametro other - confronti di date: visualizza e permette la modifica di una data e dell'operazione di confronto da adottare. Le operazioni di confronto sono 'maggiore', 'minore', 'uguale', 'diverso', 'qualsiasi', 'trail' (tra il attaccato, non 'prova' :) ). printDateComp(prefix, prefix2, data, comp, data2, yearDiff, canBeNull): genera 1 combobox per la selezione del confronto ('maggiore di', 'minore di', 'uguale a', 'diverso da', 'qualsiasi', 'tra il'), 3 combobox per la prima data (sempre visibili), altre 3 combobox per la seconda data (visibili solo quando si vuole specificare un intervallo). la seconda data dell'intervallo non può mai essere nulla. la prima data e la combobox per il confronto hanno per prefisso del nome il parametro prefix. Il suffisso della combobox del confronto è '_comp'. Le altre usano pre prefisso del nome il parametro prefix2. I suffissi dei parametri delle date sono gli stessi della funzione printDateInput. comp: indica il confronto predefinito data2: indica la seconda data predefinita 5. TABELLE Le tabelle in modgui sono manipolate dalle funzioni openTable(), closeTable() che indicano inizio e fine della tabella. openTable() permette di specificare i seguenti parametri (tutti opzionali): - width: dimensione della tabella html (default: 100%) - border: dimensione del bordo della tabella html (default: 1) - other closeTable() non ha parametri. All'interno di una tabella è possibile inserire righe. Le righe si aprono e chiudono con openTableRow() e closeTableRow() che non prendono parametri. All'interno delle righe si possono inserire 3 tipi di campi: - campi header - campi contenenti dati - campi contenenti messaggi di errori (uguale al precedente ma in rosso). Questi 3 campi si inseriscono rispettivamente con le procedure printTableHead(), printTableData() e printWrongTableData() che accettano tutte un singolo parametro: il testo contenuto nel campo della tabella. Opzionale per tutte il secondo parametro other (con il significato di sempre). Per tutti questi tipi di campo inoltre esistono anche le coppie di procedure open e close che consentono di aprire e chiudere manualmente i campi della tabella: utile per inserire qualcosa di diverso del semplice testo. Queste procedure sono: - openTableHead(), closeTableHead(): per gli header delle tabelle - openTableData(), openWrongTableData(), closeTableData(): per i campi errati o meno delle tabelle. Le procedure di open accettano un parametro opzionale other, mentre le procedure di close non accettano parametri. Le tabelle spesso sono usate per allineare i controlli di input usati nelle form. Per velocizzare alcuni tipi di righe delle tabelle, esiste la printTableEditRow(label*, name*, length, defval, thesize, error) che inserisce una riga in una tabella contenente due campi: uno di tipo dati o di messaggio di errore (a seconda del parametro della variabile booleana error) che visualizza l'etichetta label passata come parametro, ed un secondo campo contenente una casella di testo con i parametri name, length, defval e thesize specificati. 6. TOOLBAR La toolbar è la barra contenente i due tasti standard delle pagine per richiamare la procedura del menù principale e quella di help (NOTA: l'help non è implementato in questo corso, il tasto esiste solo per bellezza, ma non funzionerà). La toolbar non deve essere contenuta in nessun form. La procedura per inserire la toolbar nella pagina (da chiamare normalmente prima della closePage()) è printToolbar(sessione), il cui parametro indica la variabile di sessione. 7. SESSIONI La sessione, come descritto dal documento interfacce, è un parametro di giro passato di procedura in procedura. modgui mette a disposizione due funzioni per la manipolazione delle sessioni: - sessionEncode(idUser): codifica l'id dell'utente per generare la variabile di sessione - getUserId(session): estrae l'id dell'utente dalla variabile di sessione NOTA: nonostante nella versione attuale sessionEncode() non faccia altro che convertire in stringa l'id dell'utente, EVITATE di NON chiamarla... nelle versioni future povrebbe anche applicare alcune trasformazioni. (ci è stato chiesto di crittarlo... a nostro modesto parere è una forma inutile e fuorviante di protezione delle sessioni) 8. ALTRE FUNZIONI (IN)UTILI openCenter() e closeCenter(): permettono di allineare centralmente altri oggetti della pagina.