La recente versione di Chronoforms v4 RC 2.0, disponibile dal 30.08.2011, ha raggiunto una buona affidabilità sia in termini di prestazioni che di funzionalità implementate. Con questa prima guida si può quindi iniziare ad esaminare le modalità di uso del componente. Non prima di aver fatto una panoramica delle funzionalità inserite in questa nuova versione, che è affiancata da altre due estensioni:
- un modulo, da usare per inserire il form nelle posizioni del template;
- un plugin per inserire un form all'interno di un articolo.
Tutte le estensioni sono scaricabili dal sito dello sviluppatore a questo indirizzo
http://www.chronoengine.com/downloads/chronoforms/141-chronoformsj1.html
A differenza della precedente versione v3 non è previsto l'affiancamento con un altro componente tipo Chronoconnectivity per listare i record delle tabelle, ma, udite, udite, la nuova versione contiene già le funzioni per ottenere lo stesso risultato con il minimo sforzo e quindi di avere presenti nello stesso form i campi di inserimento e gli elenchi dei records inseriti. Una chicca! Ma di questo parleremo in un'altra occasione.
La sintesi delle funzionalità inserite nella versione è la seguente:
Core Actions
Auto Server Side Validation (Auto convalida lato server)
Custom Code (Codice personalizzato)
Custom Server Side Validation (Validazione lato server personalizzata)
Debugger
Email
Event Loop (Evento loop)
Handle Arrays (Gestire array)
Load CSS (Inserire CSS)
Load JS (Inserire JavaScripts)
Redirect User (Reindirizzare l'utente)
Show HTML (Mostra HTML)
Show Stopper
Show Thanks Message (Mostra Messaggio di ringraziamento)
Upload Files (Carica file)
Gateway di pagamento
NOTA: Queste azioni possono richiedere la registrazione a pagamento..
Listener 2CO
2CO mittente
Authorize.net
Listener PayPal
PayPal Pro
PayPal Redirect
Sicurezza
Autenticazione
Controllo Token
Captcha
Verifica Captcha
inserire Captcha
ReCaptcha
Verifica ReCaptcha
inserire ReCaptcha
Utilità
Pagina di conferma
Personalizzare DatePicker
Multi Language
Mostra Form
Invia l'articolo
CURL
Curl
URL di reindirizzamento
Sessione dei dati
passa dati alla sessione
ricevi dati dalla sessione
DB Operations
DB Multi Record Loader (elenca i records)
DB Record Loader (visualizza un record)
DB Salva (salva un record)
Email di verifica
Verifica di risposta e-mail
Verifica del mittente e-mail
Gestione degli utenti Joomla!
Joomla! accesso
Registrazione personalizzata utenti Joomla
Come si può vedere già da questo elenco sommario, le funzionalità sono tante e consentono davvero di compiere un'infinità di azioni sul nostro in sito Joomla. Anche in questo caso, come per la vecchia versione, credo si possa dire che il limite di impiego è dato solo dalla fantasia di chi lo usa.
Ma ora è tempo di passare alla realizzazione del nostro primo form. Il nostro obiettivo sarà semplice, realizzeremo infatti un form, che oltre a normali campi, permetterà di inserire un file allegato, un campo email, di memorizzare i dati inseriti nel database e di inviare messaggi email all'indirizzo inserito nel form ed a quello dell'amministratore.
Preliminarmente, se non lo avremo già fatto, dovremo installare le tre estensioni con la normale procedura di Joomla. Con le estensioni installate inizieremo quindi dal backend di Joomla, entrando direttamente nella gestione dei forms cliccando in Componenti->Chronoforms->Forms Manager. La finestra che si aprirà mostrerà il pannello di gestione dei forms. Il messaggio in rosso che vedremo in alto non dovrà allarmarci, come nella vecchia versione avverte che per rendere i form realizzati liberi dal link al sito della Chronoengine, dovrà essere registrato a pagamento il componente, tuttavia la mancata registrazione non limita le prestazioni dell'estensione. Prendiamo atto di questo, ed ognuno poi potrà fare le sue scelte.
Notiamo subito in alto a destra la barra degli strumenti per la gestione dei forms, come nella seguente figura. Le funzioni dei bottoni sono evidenti.
Nella riga seguente a sinistra noteremo invece queste opzioni, come in figura, di cui, per la gestione dei form, useremo le prime tre. La quarta servirà solo per la registrazione del componente, come detto sopra.
Form Manager riporta sempre alla finestra principale, mentre le altre due sono le modalità di gestione dei forms. Form Wizard è la gestione dei form avanzata e consente di gestire tutte le opzioni. Easy Form Wizard è invece una modalità di gestione semplificata, molto simile a quella della precedente versione v3 per Joomla 1.5. Per creare il nostro form useremo la modalità Form Wizard che consentirà di accedere a tutte le funzioni del componente. Una volta utilizzata questa l'uso della modalità Easy risulterà evidente. Clicchiamo quindi su Forms Wizard. La finestra che si aprirà sarà il nostro pannello di controllo di tutto quello inseriremo nel form. A sinistra il quadro Drag che contiene gli elementi (Elements) e le azioni (actions) disponibili per form, a destra invece il quadro Drop dove potremo trascinare ed inserire nelle opportune posizioni gli elementi e le azioni che vorremo utilizzare.
Avviamo il nostro lavoro inserendo il campo Header di intestazione del form. Nella finestra Drag clicchiamo sull'elemento Header Text e tenendo premuto il tasto sinistro del mouse lo trasciniamo nel riquadro Drop.
Nel quadro Drop clicchiamo ora sulla seconda icona a destra in corrispondenza del campo Header .
Si aprira una nuova finestra di lavoro nella quale, nel campo Code, inseriremo il titolo da dare al form fra i tag h1 dell'HTML per ottenere un risultato identato.
Nella finestra possiamo notare, sopra il campo Code, il link Add/Remove editor che con un click attiverà o disattiverà un editor di testi simile a quello dei contenuti di Joomla. L'editor renderà più facile la realizzazione di form con particolari elaborazioni grafiche. A questo punto possiamo cliccare su pulsante Apply per memorizzare gli inserimenti e poi su bottone X per uscire dalla finesta di configurazione del campo.
A questo punto è bene salvare il lavoro fatto. Ma prima dobbiamo assegnare il nome al form. Per questo nella finestra Drop possiamo premere la tab Form Setting per assegnare il nome al nostro form in costruzione. Vedremo aprirsi questa finestra.
In Form name inseriamo "provaemail" senza caratteri speciali e spazi come indicato nella nota. In Published selezionamo Yes per pubblicare il form. Nell'altro campo Tight Layout lasciamo il settaggio di default "Normal".
Fatto questo possiamo premere il tasto Salva nella barra degli strumenti in alto a destra per salvare il form.
Ora inseriamo un nuovo campo tipo Text Box, che ospiterà il campo Nome. Trasciniamo come già fatto in precedenza un campo di tipo Text Box nell'area Drop, come in figura.
Chicchiamo sull'icona già usata per editare e configurare il campo e vedremo questa finestra pop up.
In Field Name inseriamo "nome" ed in Label Text "Nome" che apparirà nel form come intestazione del campo. Gli altri campi della configurazione credo abbiano un significato abbastanza evidente, sono gli attributi del tag input dell'HTML. Continuiamo la configurazione del campo cliccando sulla tab Other del quadro. Si apre unan nuova finestra Popup con altri campi come in figura.
In Istructions for users inseriamo un promemoria "Inserisci un testo" che apparirà sotto il campo del form . In Tooltip inseriamo invece il messaggio "Devi inserire un testo" che apparirà quando l'utente cliccherà sul bottone a fianco del campo del form. Passiamo ora alla tab Validation per stabilire le caratteristiche del campo che stiamo inserendo.
Vedremo una serie di Checkbox ciascuno corrispondente ad un caratteristica del campo. Nel nostro caso spunteremo Required per rendere obbligatoria la compilazione del campo e AlphaNum per permettere l'inserimento sono di caratteri alfanumerici. Completato l'inserimento potremo ricontrollare i valori inseriti nelle precedenti tab. Se tutto è a posto potremo confermare, premendo come prima, sul tasto Apply e poi sul tasto X per uscire dal popup. Premendo poi sull'icona Salva in alto a destra salveremo il lavoro fatto fino a qui.
Proseguiamo il lavoro inserendo un altro campo Tex Box che ospiterà il nome dell'email. Trasciniamo il Text Box da Drag a Drop e lo posizioniamo dello spazio disponibile. Clicchiamo sull'icona di configurazione del campo e nel popup che si apre inseriamo i nostri valori. In Field Name inseriamo "email", in Label Text inseriamo con molta fantasia ancora una volta "Email". Clicchiamo sulla tab Other ed in Instruction User e Tooltip inseriamo il messaggio "Inserisci un indizzo email valido". Entriamo ora nella tab Validation e selezionamo le checkbox Required ed Email per indicare che il campo sara obbligatorio e dovrà essere un indirizzo email valido. Confermiamo con il tasto Apply e poi sul tasto X per uscire dal popup. Poi click sull'icona Salva in alto a destra per salvare il lavoro.
Inseriamo ora un nuovo campo Text Box che ospiterà un nuovo inserimento dell'email per la sua conferma. Ripetiamo tutti i passaggi del precedente campo. Con la differenza che in Field Name inseriremo "email1", in Labet text "Verifica email", in Instruction User e Tooltip inseriamo "Reinserisci l'email precedente" e selezioneremo il campo come Required ed Email. Anche qui confermiamo il campo con Apply e salviamo il form.
E' il momento di preparare il campo che riceverà il file allegato. In Drag clicchiamo sul campo File Upload e lo trasciniamo nella sua posizione in Drop.
Configuriamo poi il campo con i seguenti valori come da immagini. Field Name "allegato", Label Text "Allegato", Instructions user e Tooltip "Inserisci un file allegato" e spuntiamo l'attributo Required. Al solito poi salviamo il campo ed il form.
L'ultimo inserimento di campi è riservato al tasto di invio del form. Prendiamo quindi Submit Button lo trasciniamo semplicemente da Drag a Drop e non richiede particolari settaggi. Salviamo il lavoro con il tasto Salva. La figura seguente mostra questo semplice passaggio.
La situazione dei campi inseriti risulta ora la seguente.
Per cancellare un campo useremo l'icona con la X rossa mentre per spostare un campo in una posizione diversa potremo cliccare sull'icona con le doppie frecce verdi e trascinare il campo nella nuova posizione.
Il form dal punto di vista formale è pronto, tuttavia esso non contiene ancora gli elementi che consentono di eseguire i compiti che ci siamo prefissati. Per questo dovremo utilizzare alcune Actions messe a disposizione dal componente e collocarle nella giusta posizione. Per avviare questa nuova attività possiamo seguire due strade: cliccare sulla tab Actions nel quadro Drag oppure cliccare sulla tab Events nel quadro Drop. In entrambi i modi arriveremo alla nuova vista del pannello di controllo del form. Sul lato Drag vedremo i gruppi delle actions disponibili sul lato Drop saranno invece mostrate le aree in cui potranno essere collocate le actions. La prima area On Load è destinata alle actions che saranno eseguite al momento del caricamento del form nel frontend di Joomla. La seconda area On Submit invece è destinata a contenere le actions che saranno eseguite dopo l'invio dei dati del form. Questa particolarità da già credo un'idea delle grandi potenzialità che sono contenute in questa nuova versione di Chrononoforms. Potremo infatti collocare nel posto giusto tutta una serie di strumenti già disponibili, come abbiamo visto nell'elenco iniziale, o autocostruiti con le actions Custom Code contenenti scripts HTML, PHP finalizzati a compiere compiti ben definiti.
In questa nostra esercitazione utilizzeremo le seguenti actions: Show html che caricherà i campi del form che abbiamo inserito nella tab General, Custom server side validation che verificherà la corrispondenza dei due campi email del form, DB save che registrerà nel database i valori inseriti nel form, Upload files che gestirà i file allegati al form, Email che invierà le email ai soggetti che configureremo e, per ultima, Show thanks message per mostrare un messaggio di ringraziamento dopo l'invio del form.
Inizieremo trascinando la action Show Html da Drag a Drop nell'area On Load. Fatto questo non c'è necessità di altri settaggi per questa action.
Ora trascineremo la action Custom server side validation nell'area On Submit. Subito dopo aver posizionato l'action cliccheremo sull'icona di configurazione e nel popup che si aprirà inseriremo nel campo Code il seguente script in php che ha la funzione di controllare la corrispondenza delle due email e mostrare i messaggi in caso di errore.
<?php if ( $form->data['email'] != $form->data['email1'] ) { $form->validation_errors['email'] = "Le Email non sono uguali"; $form->validation_errors['email1'] = "Le Email non sono uguali"; return false; } ?>
Nota importante: il recupero dei valori dei campi del form dopo il submit avviene nel seguente modo, in ambiente HTML con l'uso di {nome_campo} in ambiente PHP invece con $form->data['nome_campo']. Questo ci consentirà il pieno uso e controllo dei valori inseriti in qualsiasi linguaggio ed in ogni zona del form.
Nel nostro caso in ambiente PHP con l'uso di questa notazione facciamo il controllo della coincidenza dei campi email ed email1.
Per completare e salvare premiamo come consueto ormai su Apply poi X e poi su Salva.
Per completare la configurazione dell'action di controllo delle email trasferiamo la action Event loop nell'area di colore rosa Onfail. Non sono richiesti settaggi. Risalviamo con la solita procedura tutto il lavoro con la sola differenza che questa volta premeremo il tasto Salva e Chiudi, che ci riporterà in Form manager all'elenco dei form.
E' il momento di preoccuparci del salvataggio dei dati nel database. Dobbiamo quindi preliminarmente creare una tabella dedicata ai dati raccolti dal nostro form. Potevamo farlo anche in precedenza, ma qui legato alla successiva action che inseriremo torna più logico. Per fare questo spuntiamo la casella collocata alla sinistra del nome del form.
Clicchiamo sul bottone Create table nella barra degli strumenti in alto a destra, già mostrata all'inizio della guida, e si aprira la seguente finestra per la creazione della nostra tabella.
Lo strumento è molto potente e ci permermette davvero una gestione molto dettagliata dei campi della tabella. Per default vengono proposti il nome della tabella, generato dal nome del form, i nomi campi e bottoni che abbiamo in inserito nel form oltre ad altri, molto utili, creati automaticamente da chonoform, il cui significato è intuitivo:
cf_id è la chiave primaria della tabella, cf_uid è un campo che contiene un valoro univoco generato in base al tempo del salvataggio, cf_created è il giorno e l'ora della creazione, cf_modified è la data e l'ora dell'ultima modifica del record, cf_idaddress è l'indirizzo IP da cui è stata fatta l'ultima modifica, cf_user_id è il codice dell'utente che ha modificato per ultimo.
Nel nostro caso non sono necessarie modifiche ed accettiamo tutto quello che è proposto, per cui possiamo premere il tasto Save in alto a destra per creare la nostra tabella. Riapriamo il form cliccando sul link Wizard edit subito a destra del nome del nostro form e rientriamo nel pannello di controllo per proseguire il lavoro.
Passimo ora a completare la gestione dell'allegato e per questo trasferiamo da Drag a Drop nell'area On Submit l'action Upload Files. Clicchiamo sulla seconda icona di configurazione per aprire la finestra popoup.
Anche qui settiamo ad Yes il campo Enabled, poi inseriamo nel campo Files la seguente stringa:
allegato:jpg-png-gif-doc-pdf-txt
Essa servirà a dire al componente che siamo gestendo il file il cui nome sarà trovato nel campo allegato, che abbiamo previsto nel form, e che il campo è abilitato a ricevere solo file con estensione uguale a quelle elencate nella stringa.
Possiamo lasciare in bianco il campo Upload Path, che serve per indicare la cartella in cui saranno salvati i file allegati.
Per default i file saranno salvati nella cartella components/com_chronoforms/uploads/FORM_NAME, quindi nel nostro caso FORM_NAME sarà sostituito automaticamente da provaemail.
Se vogliamo utilizzare un'altra cartella la dovremo inserire nel campo con il suo giusto percorso rispetto alla root di Joomla.
Negli altri campi potremo configurare la dimensione massima del file caricabile il Kb, la dimensione minima ed i messaggi di errore che appariranno nel form in caso di non rispetto dei valori inseriti e del tipo di estensione dell'allegato. Salviamo il tutto.
Anche in questo caso per completare la configurazione dell'action di controllo degli allegati trasferiamo la action Event loop nell'area di colore rosa Onfail dell'action Upload Files. Non sono richiesti settaggi. Risalviamo il tutto.
Attenzione l'action Upload Files deve precedere l'action DB Save altrimenti quest'ultima con conoscerà il nome dell'allegato (questo è un aggiornamento della prima versione della guida)
E' ora il turno di inserire in On Submit la action DB Save. Per questo in Drag scorreremo l'elenco delle actions e cliccheremo sul nome della categoria DB operations. In basso saranno mostrate tutte le actions della categoria. Cliccheremo su DB Save e la trascineremo nell'area verde di On Submit. Clicchiamo sull'icona di configurazione (la seconda) della action ed entriamo del popup Basic.
Qui selezionamo Yes nel campo Enabled per abilitare l'action e nel campo Table selezioniamo il nome della tabella che abbiamo appena creato nel database per collegarla al nostro form. Per il momento non sono necessari altri settaggi negli altri campi. Tralasceremo anche i settaggi dell'altra tab Advanced che qui non servono, in quanto dedicati per collegarsi ad altri database sullo stesso server di Joomla o addirittura a database esterni su altri server che permettano il collegamento. Ma, anche se non useremo quest'ultima funzionalità, non possiamo però tralasciare di dire che essa darà, insieme ad altre actions, una potenza eccezionale ai nostri form. Immaginate infatti di interagire in modo semplicissimo con database esterni per operazioni di lettura e salvataggio records ed il resto viene da se.
Fatto questo procediamo con le operazioni, che non ripeto, per il salvataggio del lavoro.
E' il turno dell'action Email che trasferiamo con lo stesso sistema nell'area On Submit della finestra Drop. Apriamo il popup di configurazione che in questo caso prevede 5 tab disponibili.
Nella tab General settiamo a Yes il campo Enabled. In Action label inseriamo un nome Invia email da assegnare all'action per distinguerla da eventuali altre email inserite. In Send As lasciamo il valore HTML. In Attachments fields name inseriamo il nome del campo allegato che abbiamo usato nel form per il campo del file allegato, questo consentirà di ricevere il file come allegato nelle email. In Get Submitter's IP settiamo Yes per poter trasmettere il valore dell'IP anche nell'email. Clicchiamo su Apply e poi sulla tab Template.
In questa tab possiamo impostare il template con cui sarà mostrata l'email. Anche qui abbiamo la possibilità di attivare o no l'editor con il tasto Add/Remove editor. Potremo recuperare i valori dei campi del form inserendo fra parentesi graffe il nome del campo, così {nome_campo} come nella figura. Creiamo quindi il nostro template. Clicchiamo su Apply e passiamo alla tab successiva Static.
In questa tab Static possiamo configurare i campi dell'email. I campi fondamentali ed obbligatori sono: l'email a cui si invia To, l'oggetto dell'email Subject, in nome di chi invia From name e l'indirizzo email di chi invia From email. Neli'esempio ho inserito nomi fantasia che nel form dovranno essere sostituiti da indirizzi reali e funzionanti.
Importante: Ciascuno di questi 4 campi dovrà essere obbligatoriamente configurato almeno una volta qui in Static o nella successiva tab Dynamic. Altrimenti senza uno di questi parametri fondamentali l'email non postrà essere inviata. Se un campo non sarà rienpito in Static dovrà essere previsto in Dynamic e viceversa.
Sono poi disponibili gli altri campi non obbligatori. CC indirizzi per conoscenza, BCC indirizzi per conoscenza nascosta, Reply name nome a cui si risponde replicando all'email, Reply mail indirizzo email a cui si replica. Potranno essere inseriti in ogni campo più indirizzi email separandoli con virgole. Confermiamo con Apply e passiamo alla tab Dynamic.
In questa tab Dynamic possiamo inserire i valori dinamici degli elementi dell'email provenienti dai campi del form oppure elaborati da specifici script inseriti in On Submit. Nel nostro caso inseriremo solo in Dynamic To il nome del campo email per inviare una copia dell'email anche all'indirizzo che l'utente ha inserito nel form. Fatto questo possiamo confermare con Apply e salvare poi il lavoro svolto fino a qui con Salva.
Siamo giunti all'ultimo passaggio. L'inserimento dell'action Show Thanks Message. Essa produrrà un messaggio, normalmente di ringraziamento o di altro tipo, dopo l'invio del form. Trasciniamo quest'ultima in On Submit e poi la editiamo con il solito metodo per configurarla.
Nel campo Code potremo inserire sia HTML che PHP oppure abilitare l'editor per elaborare un po' di più il messaggio. Anche qui i valori dei campi potranno essere recuperati con {nome_campo}. Clicchiamo su Apply poi X e salviamo il form. Il risultato del lavoro sulle action sarà il seguente.
A questo punto possiamo cliccare su Salva e Chiudi in alto a destra per salvare tutto il lavoro ed uscire.
L'ultimo passaggio è cliccare su nome del form provaemail nella finestra Form Manager per inserire l'ultimo settaggio. La finestra che si aprirà mostrerà una serie di campi, cercheremo Form Tag Attachment ed in esso inseriremo i valori enctype="multipart/form-data" per consentire al form di trasmettere l'allegato per email. Salviamo e per l'ultima volta di nuovo tutto il lavoro.
Il corretto funzionamento di tutto potrà essere verificato cliccando sul link Frontend View sulla destra del nome del form in Form Manger.
Si conclude qui questa prima guida sull'uso dell'estensione Chronoform V4 RC2.0 in Joomla 1.7. Abbiamo affrontato metodi semplici ed altri un po' più complessi, e ovviamente non tutti quelli disponibili visti all'inizio. Lo scopo era quello di dare una prima visione di alcune delle risorse disponibili e come muoversi con esse nelle varie aree nell'estensione, per permettere a chi ne ha necessità e voglia di sperimentare in proprio le potenzialità disponibili.
Come per la vecchia versione per Joomla 1.5 è evidente che anche in questo caso siamo di fronte ad un componente che darà al nostro Joomla la possibilità di trovare tante soluzioni ad hoc per le nostre necessità e per far divenire ogni sito una cosa veramente personale e unica.
Auguro a tutti buona lettura e buon lavoro.
Valerio Sichi (vales)
Commenta questo articolo sul forum