Appendice A. Riferimento
Questa sezione riporta un completo elenco dei tag riconosciuti da Sar-At. Se non altrimenti indicato, tutti i tag funzionano con showPage, showForm e showErr (rispettivamente usati per gestire le pagine ordinarie, i moduli e le pagine d'errore).
Tutti i tag di Sar-At sono inclusi tra parentesi graffe e scritti interamente in maiuscolo.
Campi del record corrente
Se nel database abbiamo definito una sezione chiamata "automobili" in cui ogni record contiene i campi "marca", "modello" e "cilindrata", allora scrivere nella pagina mastro {marca} provoca l'apparizione della marca del modello attualmente selezionato.
Pseudo-campi predefiniti
Oltre ai campi della sezione esistono alcune scritture che Sar-At risolve in ogni sezione. Sono: {HEAD} (valida intestazione per la pagina, comprese keyword, description, alfabeto, lingua, generator e titolo), {template} (nome della sezione corrente), {sarel_username} (identificatore univoco per i visitatori registrati e loggati), {search} (valore dell'omonimo parametro nella URL, se presente), {id_field} (valore dell'omonimo parametro nella URL, se presente), {sarat_adminname} (identificatore univoco per igli amministratori registrati e loggati)
INCLUDE
Descritto compiutamente nel paragrafo "Inclusione di frammenti HTML" del capitolo 6, "Funzioni avanzate". In sintesi: legge un file esterno, che tipicamente (ma non necessariamente) contiene un frammento di pagina HTML, e lo include nel punto in cui viene trovata l'istruzione INCLUDE stessa. Utilizzato per isolare in un unico punto un brano ripetuto in molte pagine mastro del sito. Il brano può contenere a sua volta istruzioni Sar-At (ma la istruzione INCLUDE viene sempre eseguita per prima, quindi un INCLUDE non può a sua volta contenere altri INCLUDE).
Gli INCLUDE possono venire localizzati. Per esempio, una pagina mastro chiamata pippo.html.it che contiene la riga {INCLUDE pluto.ihtml} finirà per includere automaticamente il file pluto.ihtml.it se questo esiste; pluto.ihtml in caso opposto).
Esempio:
{INCLUDE testata.ihtml}
BEGIN..END
Ne abbiamo parlato nel capitolo sulle Viste. In sintesi: tutto il codice HTML che si trova tra {BEGIN etichetta_vista} e {END etichetta_vista} viene ripetuto da Sar-At tante volte quanti sono i record selezionati dalla vista. Per esempio {BEGIN tutti_i_tenori}{nome} {cognome}<br />{END tutti_i_tenori} fa apparire nella pagina web qualcosa come
Aristide Palazzi<br />
Ruggero Leone<br />
NAVIGATE…END
Ne abbiamo parlato nel capitolo sulle Viste. Funziona come BEGIN..END visto sopra, ma dividendo i risultati in sottopagine. Proseguendo l'esempio visto sopra, potremmo decidere di mostrare i cantanti lirici di timbro tenorile a due per volta.
IF per i campi della pagina
Immaginate di voler pubblicare sul vostro sito web una sezione catalogo, che ospiterà le schede dei prodotti della vostra azienda. Disgraziatamente, voi non disponete delle fotografie promozionali di alcuni prodotti, ma volete certamente utilizzare le foto di cui disponete. Come creare una pagina mastro che si adatta a questa variabilità? Una possibilità sta nel creare più pagine mastro distinte (vedere "varianti" in questo manuale), ma c'è una soluzione più semplice.
Preparate le foto dei prodotti di cui disponete, e inseritele nella base dati Sar-At. Quando create la pagina mastro, lascerete uno spazio per la immagine. In HTML avremo una riga tipo questa:
<img src ='{foto}' width='100' height='200' />
Potete ritoccare la pagina mastro in modo che lo spazio dell'immagine venga rimossa quando l'immagina manca in base dati, così:
{IF foto}
<img src ='{foto}' width='100' height='200' />
{ENDIF foto}
Quando Sar-At crea la pagina web di un prodotto, rimuoverà tutto lo HTML contenuto nel blocco IF se la informazione indicata ("foto", nel caso dell'esempio) è nulla oppure zero. È anche possibile creare un blocco "altrimenti", così:
{IF foto}
<img src ='{foto}' width='100' height='200' />
{ELSE foto}
<img src ='logoSocieta.gif' width='100' height='200' />
{ENDIF foto}
In questo ultimo esempio, la foto verrà sostituita da una immagine fissa quando una foto non è disponibile.
IF campo = valore
È possibile testare il valore di un campo. Per esempio possiamo scrivere {IF timbro = tenore}. Usate spazi bianchi attorno al segno di uguale. I test per valore minore o maggiore non sono per ora supportati.
IF fuori dalle viste
Il costrutto IF-ELSE-ENDIF può venire utilizzato in congiunzione con il nome di un campo, come nell'esempio qui sopra, o con il nome di una vista. Quando viene usato con una vista, il ramo IF verrà inserito nella pagina web se la vista seleziona almeno un record e il ramo ELSE se la vista non seleziona alcun record.
Per esempio, vediamo come creare un semplice motore di ricerca interno al nostro sito, che seleziona tutte le pagine di una sezione il cui titolo contiene una parola scelta dal visitatore.
- Creiamo una nuova Vista. Le diamo un nome a piacere e per etichetta scegliamo "motore_ricerca". Impostiamo la Vista perché selezioni in soli record il cui titolo contiene un valore scelto dal visitatore, che la pagina HTML passerà nel parametro search.
- Creiamo la interfaccia utente del motore di ricerca usando lo HTML. Ecco una proposta minimalista:
<form action="showPage.php" method="post">
<input type="hidden" name="template" value="articoli" />
<input type="hidden" name="masterPage" value="trova.html" />
<input type="text" name="search" size="30" />
<input type="submit" name="Trova" />
</form>
{IF motore_ricerca}
<p>Elenco dei prodotti il cui nome contiene la parola {search}:</p>
{BEGIN motore_ricerca}
<p>{title}</p>
{END motore_ricerca}
{ELSE motore_ricerca}
<p>Spiacente, nessun prodotto contiene la parola {search} nel nome.</p>
{ENDIF motore_ricerca}
Se vogliamo inserire un link a ciascuna pagina trovata, la prima parte del nostro esempio diventa:
{IF motore_ricerca}
<p>Elenco dei prodotti il cui nome contiene la parola {search}:</p>
{BEGIN motore_ricerca}
<p><a href='showPage.php?template=prodotti&id={id}'>{title}</a></p>
{END motore_ricerca}
{ELSE motore_ricerca}
eccetera.
Se vogliamo preparare una pagina che cerca la parola digitata dal visitatore in più sezioni del sito possiamo ottenete il risultato creando (al punto "1" di questo paragrafo) più viste. Ogni vista lavorerà su una sezione distinta: per esempio avremo una vista "motore_ricerca1" che opera sulla sezione "prodotti", una vista "motore_ricerca2" che lavora sulla sezione "risposte" e una vista "motore_ricerca3" che lavora sulla sezione "recall".
Al punto 3, nella pagina che mostra i risultati della ricerca, concateneremo le Viste.
{IF motore_ricerca1}
<p>Elenco dei prodotti il cui nome contiene la parola {search}:</p>
{BEGIN motore_ricerca1}
<p><a href='showPage.php?template=prodotti&id={id}'>{title}</a></p>
{END motore_ricerca1}
{ENDIF motore_ricerca1}
{IF motore_ricerca2}
<p>Elenco delle risposte il cui titolo contiene la parola {search}:</p>
{BEGIN motore_ricerca2}
<p><a href='showPage.php?template=risposte&id={id}'>{title}</a></p>
{END motore_ricerca2}
{ENDIF motore_ricerca2}
{IF motore_ricerca3}
<p>Elenco dei recall il cui nome contiene la parola {search}:</p>
{BEGIN motore_ricerca3}
<p><a href='showPage.php?template= recall&id={id}'>{title}</a></p>
{END motore_ricerca3}
{ENDIF motore_ricerca3}
IF dentro alle viste
L'istruzione IF può anche venire usata dentro alle Viste, e in questo caso fa riferimento ai campi dei record ripescati dalla Vista. Per esempio, se stiamo guardando via showPage una pagina web della sezione film, dunque relativa a un DVD, e se vi usiamo una Vista per ripescare i dati sugli interpreti, possiamo scrivere:
Titolo del disco: {title}
{BEGIN vista_che_trova_interpreti}
{IF sesso}Attrice{ELSE sesso}Attore{ENDIF sesso} {nome} {cognome}<br />
{END vista_che_trova_interpreti}
LOCATION
Seguito da un indirizzo http, viene utilizzato per inviare il visitatore ad un'altra pagina. Per esempio, un tipico codice piazzato nelle pagine web che impaginano il risultato di una ricerca è:
<h1>Risultato della ricerca</h1>
{IF ricerca_sul_sito}
[…mostra risultati…]
{ELSE ricerca_sul_sito}
Spiacente, non abbiam trovato nulla
{ENDIF ricerca_sul_sito}
Se si desidera portare il visitatore che ha chiesto una ricerca senza successo ad una pagina completamente richiesta è possibile modificare il brano come segue:
<h1>Risultato della ricerca</h1>
{IF ricerca_sul_sito}
[…mostra risultati…]
{ELSE ricerca_sul_sito}
{LOCATION mappa-del-sito.html}
{ENDIF ricerca_sul_sito}
Costrutti condizionali sui moduli
Quattro istruzioni sono definite esclusivamente dentro showForm, il motore dei moduli. Sono presentate nel capitolo sui moduli di questo stesso manuale.
ONERR..ENDERR
Lo HTML contenuto tra ONERR e ENDERR viene lasciato se c'è un errore di compilazione relativo al campo citato, altrimenti rimosso. Esempio;
{ONERR codice_fiscale}Codice fiscale assente o non valido!{ENDERR codice_fiscale}
CHECKBOX
Genera una casella di controllo (checkbox) selezionata se il campo indicato ha valore "on". Esempio:
{CHECKBOX consenso_legge_privacy}
Se state usando Sar-At versione 7.5 o superiore esiste una versione più potente di questo tag, che è indicata per i checkbox multipli (esempio: come si compone il vostro pasto ideale? Seguono checkbox per antipasti, primi, secondi, contorni, dolce e frutta)
La sintassi è analoga a quella di SELECTEDIF, ma riflette il fatto che stiamo trattando una serie di valori:
{CHECKBOX nomecampo[] valore}
Quindi avremo per esempio:
<label>{CHECKBOX pietanza[] primi} Primi piatti</label>
<label>{CHECKBOX pietanza[] secondi} Secondi piatti</label>
<label>{CHECKBOX pietanza[] contorni} Contorni</label>
CHECKBOX può venire usato all'interno di una Vista. Per esempio avremmo:
{BEGIN tutte_pietanze}
<label>{CHECKBOX pietanza [] {stringa}} {title}</label><br />{END tutte_pietanze }
Le pagine mastro automatiche generate da Sar-At per le sezioni modulo contengono una struttura altamente ottimizzata come quest'ultima, generata automaticamente, a fronte dei campi di tipo "caselle di spunta" inserite nel modulo. Consigliamo dunque di generare i moduli in Sar-At e poi incollare lo HTML risultante dentro un impaginato.
RADIOBUTTON
Genera un pulsante radio selezionato se il campo menzionato al secondo parametro ha valore uguale al terzo parametro. Esempio:
{RADIOBUTTON personaggio_disney Pippo}
SELECTEDIF
Genera l'attributo XHTML selected se il campo indicato come secondo parametro ha valore uguale al terzo parametro. Esempio:
<select name='personaggio'>
<option {SELECTEDIF personaggio Pippo}>Pippo</option>
[…]
PHP
Dentro una pagina mastro è possibile inserire codice in linguaggio PHP. Il brano di codice deve venire prefisso da <?php e terminato con ?>
Non è sufficiente la notazione abbreviata <?, neppure se il server è configurato per accettarla normalmente.
Sar-At non considera la presenza di codice PHP nella pagina mastro come limitativa dell'uso di cache, quindi il codice non viene eseguito quando della pagina viene spedita al visitatore la copia archiviata.
Il codice PHP viene eseguito da Sar-At e non direttamente da Apache. Il risultato degli echo viene visualizzato nel punto in cui si trova il codice PHP.
Variabili predefinite per le Viste
Sono dettagliate nel capitolo sulle Viste. Includono i parametri passati nella URL e i valori dei campi del record corrente.