Parte sesta: altri plug-in

Questa sezione del manuale documenta gli altri tipi di plug-in che possono venire aggiunti alla vostra copia di Sar-At e spiega come gestirli.

Il manager di plug-in

Il manager di plug-in viene richiamato scegliendo la voce Plug-in dal menu Sito; permette di abilitare e disabilitare i plug-in installati, sito per sito. È utilizzabile solo da root e dal responsabile del sito: tutti gli altri amministratori non vi hanno accesso.

Quando richiamiamo il manager dei plug-in appare una schermata divisa in quattro pannelli (con quattro linguette). Ogni pannello mostra uno tra i quattro tipi di plug-in: quelli per showPage già presentati nel precedente capitolo, quelli per showTwig, editAdd, validate descritti nel seguito di questo capitolo.

Quando richiamiamo il manager dei plug-in per la prima volta, tutti i plug-in incorporati di Sar-At sono abilitati (e non possono venire disabilitati); tutti gli altri sono disabilitati e inutilizzabili, ma potete abilitarlo con un clic. Appare un plug-in per riga; per i plug-in incorporati c'è anche un link al manuale.

Plug-in per showPage

I plug-in per le pagine mastro classiche si installano in sarat/plugin.

La colonna Cache indica se il plug-in è compatibile con la cache di Sar-At per l'accelerazione delle pagine. Per esempio, search_site7 non lo è, perché viene usato per creare un motore di ricerca ed evidentemente la pagina con i risultati della ricerca non è identica per tutti i visitatori (non tutti i visitatori cercano sempre esattamente la stessa cosa).

I plug-in non incorporati, appena installati, appaiono con la cache disabilitata per prudenza: chiedete all'autore del plug-in se esso sia compatibile con la cache. Se del caso, cliccate la spia rossa: essa diventa verde (cliccandola di nuovo torna rosso). Per abilitare un plug-in, spuntate la casella di controllo a destra e premete il pulsante Registra.

Se una riga appare in viola, significa che quel plug-in era stato precedentemente usato ma è ora indisponibile (è stato disinstallato dal server). Questo non è un problema, purché le vostre pagine mastro non cerchino di farne uso… Cliccate la spia viola per far sì che Sar-At perda la memoria del vecchio plug-in e cancelli la riga incriminata.

Plug-in per Twig

I plug-in per Twig si installano in sarat/Twig/Extension.

Il plug.in Debug (descritto sul sito Twig) è automaticamente abilitato quando Sar-At percepisce che dall'altra parte del browser si trova un amministratore che ha digitato username e password valide. Disabilitato altrimenti.

Tag definiti da Sar-At in Twig

Chi è abituato a scrivere pagine mastro classiche sa di poter usare in ciascuna pagina alcuni tag come sarel_username per visualizzare il nome utente dei visitatori registrati. Per Twig abbiamo realizzato una soluzione analoga ma più moderna e in linea con le caratteristiche di quel linguaggio.

Introduciamo cioè l'oggetto saratuser, che prende il posto della coppia sarel_userlogged e sarel_username ma aggiunge ulteriori informazioni

Parametri URL in Twig

Chi è abituato a scrivere pagine mastro classiche sa di poter usare in ciascuna pagina un tag omonimo dei parametri passati per URL. Per esempio se viene chiamato showPage.php?template=x&masterPage=x.html&gelato=fragola allora nella pagina mastro x.html il tag {gelato} verrà rimpiazzato da showPage con la parola "fragola". Per Twig abbiamo realizzato una soluzione analoga ma più moderna e in linea con le caratteristiche di quel linguaggio.

Abbiamo scelto di inserire i valori della URL in un vettore chiamato _GET (o in alternativa, per le pagine richiamate con un form method='post', nel vettore _POST). Quindi se venisse chiamata questa URL:

showTwig.php?template=x&id=1&masterPage=y.twig.html&gelato=fragola

avremmo che {{ _GET.gelato }} vale "fragola".

Plug-in per editAdd

I plug-in per editAdd si installano in sarat/editadd.

Sono i plug-in che lavorano dentro editAddPage, quella schermata dove un amministratore inserisce una nuova pagina web compilando un modulo, e ne modificano l'aspetto. Per abilitarne uno dovete selezionare il suo tipo base. Per esempio, un plug-in che consente di digitare soltanto numeri interi dispari ha per tipo base il numero intero. Spuntate poi la casella di controllo all'estrema destra e premete il pulsante Registra.

Plug-in per validate

I plug-in per editAdd si installano in sarat/validate.

Sono i plug-in che lavorano dentro le sezioni modulo e verificano che i dati inseriti dal visitatore siano accettabili. Vengono usati anche da editAddPage, quella schermata dove un amministratore inserisce una nuova pagina web compilando un modulo, ma senza modificarne l'aspetto e solamente dopo che l'inserimento dei dati è terminato. Per esempio potremmo avere un plug-in che verifica quale numero intero sia stato digitato dal compilatore e lo rifiuta se non è dispari.

Per abilitare un plug-in di questo tipo selezionate dal menu il suo tipo di dati base (nel caso dell'esempio, numero intero), poi spuntate la casella sulla destra e premete il pulsante Registra.

Un plug-in di validazione una volta installato nel Sar-At, appare automaticamente nel menu Validazione in fase di creazione di un campo (nella linguetta Struttura). La validazione viene eseguita sia quando un amministratore aggiunge una nuova pagina usando il back-office Sar-At, sia quando un visitatore compila un nuovo record in una sezione modulo.

Se il plug-in di validazione giudica inaccettabile il dato inserito dal proprietario del sito (o da un redattore), esso risponde con il messaggio "Non accettabile come xxx", dove al posto di xxx si trova il nome del plugin. Qui di seguito riportiamo un elenco di plug-in e per ciascuno scriviamo quali controlli esso applica.

Un plug-in di validazione funziona solo per uno specifico tipo di dati - per esempio, un plug-in che verifica che una data sia nel passato non può essere usato su un campo di tipo "numero intero".

I plug-in incorporati di Sar-At sono:

PDF

Applicabile ai file. Accetta solo allegati PDF.

Image

Applicabile ai file. Accetta solo immagini visualizzabili da tutti i browser, quindi JPEG codificate RGB (ma non CYMK), GIF e PNG.

no_http

Applicabile ai testi lunghi. Vieta l'inserimento di link http. È molto utile nei forum, per impedire che i manigoldi inseriscano link ai loro siti truffaldini.

Futura

Applicabile a date. Verifica che la data digitata sia posteriore alla data di oggi.

Passata

Applicabile a date. Verifica che la data digitata sia anteriore alla data di oggi.

Email

Applicabile a testi brevi. Verifica che il testo costituisca un valido indirizzo di posta elettronica (tra l'altro non accetta casella@nomesito.it se su Internet nessuno ha registrato il nomesito.it).

CAP

Applicabile a testi brevi. Verifica che il testo costituisca un valido codice di avviamento postale italiano. Accetta sia il formato interno (per esempio, 20100 per Milano) che il formato europeo (per Milano, .I-20100)

Codice fiscale

Applicabile a testi brevi. Accetta codici fiscali di sedici caratteri. Riconosce e valida con successo anche i rari codici assegnati dall'agenzia delle entrate in caso di omocodia.

Partita IVA

Applicabile a testi brevi. Accetta numeri di partita IVA nel formato italiano (undici cifre).

IBAN

Applicabile a testi brevi. Accetta coordinate bancarie (anche non italiane). Verifica sia la lunghezza che il codice di controllo finale.

IP

Applicabile a testi brevi. Accetta numeri IPv4 come 198.162.0.1.

URL

Applicabile a testi brevi. Accetta indirizzi URL completi http e https.

Password

Applicabile a testi brevi. A volte desideriamo che i nostri visitatori registrati scelgano per sé una password significativa, per impedire che qualche malintenzionato la indovini per tentativi e riesca così ad accedere a sfroso al contenuto riservato del nostro sito, ma è difficile costringerli.

Sar-At introduce la validazione "password". Possiamo abilitarla (o disabilitarla) caso per caso, nella sezione che contiene i dati dei nostri visitatori registrati, cliccando la linguetta Struttura, selezionando il campo Password e cliccando l'ultima voce in fondo, Validazione.

Quando la validazione della password è attiva, Sar-At non accetterà una password troppo corta o troppo semplice (come, per esempio, una sfilza di lettere uguali). Sono richiesti almeno otto caratteri di cui almeno una maiuscola. almeno una minuscola, almeno una cifra e almeno un segno di interpunzione.

Comuni italiani

Applicabile a testi brevi. Accetta soltanto il nome, in forma standard ISTAT, di un comune italiano esistente. I comuni dell'Alto Adige accettano sia la grafia italofona che quella tedesca..

All'interno di Sar-At e nelle pagine mastro sintetiche "a fil di ferro" realizzate da Sar-At per voi appare un sistema ad autocompletamento che suggerisce la dizione corretta dopo che l'utente ha digitato le prime lettere del nome (per esempio "regg" propone Reggio nell'Emilia e Reggio di Calabria).

Nations

Applicabile a testi brevi. Accetta soltanto il nome, in forma anglofona, di una nazione esistente. All'interno di Sar-At e nelle pagine mastro sintetiche "a fil di ferro" realizzate da Sar-At per voi appare un sistema ad autocompletamento che suggerisce la dizione corretta dopo che l'utente ha digitato le prime lettere del nome.

Portion

Applicabile a menu popup (select). Se viene selezionato, il sistema di autocompletamento descritto nel manuale Mantenere il sito funziona anche su testi contenuti al centro del testo.

Per esempio, abbiamo una sezione menu che contiene i valori "ippopotamo", "cavallo", "accendino Zippo". In un campo di tipo menu popup (select) che pesca i dati da questa sezione menu accendiamo la validazione "portion". Ora quando il redattore digita "ippo" gli vengono offerte due scelte: "ippopotamo" e "accendino Zippo". Se la validazione "portion" viene spenta, la seconda opzione non viene offerta.

I plug-in di inserimento

I plug-in di inserimento sono chiamati anche plug-in di editAdd, perché lavorano dentro il componente di Sar-At editAddPage, quella schermata dove un amministratore inserisce una nuova pagina web compilando un modulo.

Sar-At normalmente mostra le informazioni che compongono la vostra pagina in formato testuale, e permette all'amministratore di modificarle sempre in formato testuale. In alcuni casi potrebbe risultare più naturale un'altra forma di inserimento. Per esempio, se state creando il sito web di un colorificio e nella sezione prodotti volete mostrare la tinta di ogni vernice, sarebbe ideale mostrare all'amministratore una tavolozza. Sar-At potrebbe poi convertire ogni colore cliccato nei codici HTML utilizzabili dalla pagina mastro.

Un altro esempio: Sar-At mostra le date in formato internazionale standard (anno-mese-giorno) ma per alcuni scopi è più semplice per l'amministratore confrontarsi con un calendarietto a video. Il plug-in incorporato date ne fornisce uno.

I plug-in di inserimento hanno effetto solo all'interno di editAddPage e non possono venire utilizzati da showForm, quindi non sono utilizzabili dai visitatori del sito, ma solo dagli amministratori.

Plug-in file

Consente di collegare un documento presente sul disco rigido dell'amministratore al database. I documento viene automaticamente caricato sul server e rinominato in modo da evitare conflitti (questa procedura è dettagliata nel manuale "Mantenere il sito").

Quando il documento caricato è un'immagine o comunque un formato internamente riconosciuto da Sar-At, il plug-in ne offre una anteprima.

Sar-At supporta le anteprima per i seguenti tipi di documenti: immagini, PDF, Word Excel e Powerpoint (anche nel formati XML, ovvero docx, xlsx e pptx), RTF e TIFF.

Usando tecnologia AJAX, il plug-in file consente di cancellare il documento sul server, senza ridisegnare la schermata corrente.

Plug-in data

Mostra un calendario perpetuo. Cliccando una data questa viene inserita.

Plug-in ora

Consente di inserire un'ora del giorno (come le 15:30 del pomeriggio) o una durata in ore:minuti:secondi.

Plug-in data e ora

Mostra un calendario perpetuo che include la selezione dell'ora. Cliccando una data questa viene inserita.

Plug-in radiobutton

Mostra una serie di alternative nella forma di pulsanti radio. Funzionalmente equivalente a menu, rispetto al quale però non offre una opzione "Altro…"

Plug-in multiparola

Mostra una serie di alternative e permette di selezionarne nessuna, una o più d'una. Le alternative possono venire raggruppate (per esempio, i piatti di un meno possono venire offerti ma divisi tra primi, secondi e dessert).

Plug-in checkbox

Mostra una serie di alternative nella forma di caselle di controllo. Funzionalmente equivalente al multiparola.

Plug-in colore

Permette di cliccare un colore da una tavolozza interattiva. Nel database finisce il codice RGB del colore, per esempio F00 per il rosso e 0F0 per il verde.

L'uso operativo dei plug-in di inserimento incorporati è dettagliato nel manuale "Mantenere il sito".

Sviluppo di plug-in per showPage

Un plug-in per pagine mastro classiche è una funzione PHP che riceve come parametri da Sar-At il nome della sezione corrente, lo id della pagina corrente, la lingua della medesima e opzionalmente altri parametri inviati dal chiamante.

Il plug-in esegue la sua elaborazione e assegna alla globale $t i valori di tutti i segnaposto che esso definisce.

Per esempio, se un ipotetico plug-in chiamato volumesfera venisse chiamato per calcolare il volume di una sfera di raggio dato, così:

{volumesfera@55}

allora la sua realizzazione in linguaggio PHP sarebbe:

  <?php
  function volumesfera ($tabella, $pageId, $languageId, $raggio) {
        global $t;           // Istanza del template
   
        $mioNomeCompleto = "volumesfera@$raggio";
        define ('PIGRECO', 3.1415926);
        $t->set_var($mioNomeCompleto, $raggio*$raggio*$raggio*4/3*PIGRECO);
        }
  ?>

Accesso ai dati dell'utente corrente

Un plug-in, così come altro codice scritto in PHP e che fa affidamento su Sar-At, può ricevere dal sistema informazioni sull'utente che sta guardando la pagina web.

Per verificare se l'utente corrente è registrato come parte di un gruppo (oppure se ha diritto di accedere a una certa sezione).

  $utente = SaratUserLogged($istanza, $id_gruppo=NULL, $sezione=NULL);

Per eseguire il login dell'utente corrente:

  $utente = SaratLogin($istanza, $provider, $id_gruppo, $username=NULL, $password=NULL);

Primo esempio: nel vostro blog volete accettare commenti ma senza costringere i lettori a compilare un modulo di iscrizione. Potete accettare le loro credenziali Facebook o Twitter

Secondo esempio: state realizzando un CRM online per i clienti di una azienda e volete consentire l'accesso a chiunque sia inserito nella base dati dell'azienda, senza doverne ricevere una copia completa e tenerla aggiornata. È sufficiente che il CRM offre una interfaccia standard OpenID per ottenere il risultato senza scrivere una sola riga di codice.

Le funzioni SaratUserLogged e SaratLogin restituiscono un record così composto

La fonte dell'autenticazione vale "Sar-At" per un login tradizionale effettuato dal nostro programma. Per log-in di nuovo tipo avremo come fonte il nome del servizio di autenticazione -- un social network o un server OpenID. Ecco i valori possibili predefiniti e preconfigurati