Manuale del Modulo Cal-Zone

Indice

1. Introduzione

2. Caratteristiche

3. Installazione

4. I tag

5. I template

6. I link

7. Lingue diverse

8. Autorizzazioni

9. Una parola conclusiva

Cap.1: Introduzione

Perché mai dovrei trovare il tempo di imparare i segreti Cal-Zone quando esistono in giro programmi di agenda ricchi di possibilità e più facili da usare? Ebbene per quanto sia possibile usare un'altra applicazione di agenda, Cal-Zone offre un grado di personalizzazione che non ha precedenti. Praticamente ogni aspetto della visualizzazione può essere modificato per soddisfare le vostre esigenze grazie a semplici cambiamenti negli opportuni template. Di fatto Cal-Zone non contiene codice html, fatta eccezione per alcuni semplici box a discesa usati nella form, e anche questi possono essere eliminati se lo si desidera. Anche la form di invio è gestita completamente da un template. Questo rende possibile aggiungere codice javascript per funzioni di controllo sui dati inseriti e inviati dalla form. In questo modo è possibile estendere le prestazioni dell'agenda senza cambiare neppure una riga di programma.

Cap. 2: Caratteristiche

* Tutti gli aspetti dell'interfaccia utente sono gestiti da template usando semplici tag (per esempio {DATE}).

* Il primo giorno della settimana può essere uno qualsiasi dei sette giorni (perché non iniziare la settimana dal martedì?).

* Effetti speciali come i popup possono essere aggiunti in un template modificando facilmente il comportamento della vostra agenda.

* L'orario può essere mostrato sia nel formato 12 ore sia 24.

* Una facile amministrazione consente di aggiungere, modificare e cancellare argomenti.

* Si possono mostrare elenchi all'interno di argomenti separati.

* Le viste mensili possono essere mostrate come agenda o liste di eventi o in qualsiasi altro modo possiate immaginare.

* E' possibile aggiungere qualsiasi tipo di immagine per mostrare gli argomenti e altri aspetti.

* Completo supporto dei fogli di stile. Ogni argomento può avere il suo colore e il suo carattere.

* Gli stili possono risiedere in un proprio file o essere inclusi come parte degli stili propri di un tema.

* Gli amministratori possono cambiare template usando semplici menù a tendina.

* I template possono essere cambiati al volo ottenendo effetti interessanti. Offrite ai vostri visitatori la scelta fra la vista in stile agenda oppure lista.

* Nella vista mensile è possibile mostrare qualsiasi numero di settimane (per esempio viste di una o di due settimane).

* Nella vista annuale è possibile mostrare qualsiasi numero di mesi (per esempio viste di due o sei mesi).

* Supporto completo delle autorizzazioni per le funzioni AGGIUNGI, MODIFICA, CANCELLA, MODERA e VISTA GENERALE; gruppi diversi possono avere privilegi differenti.

* Gli utenti con l’autorizzazione MODERATE possono inserire direttamente gli eventi nell'agenda, mentre gli altri passano attraverso una procedura di approvazione.

* Gli eventi possono essere censurati in base alla lista di censura di Envolution.

* Gli eventi possono essere facilmente approvati da chiunque possieda l’autorizzazione ADD o superiore attraverso una semplice interfaccia di amministrazione.

* Template distinti per Anno, Mese, Giorno, Evento, Invio, Messaggi, Intestazioni e Piè di pagina rendono facile la personalizzazione.

* Il numero di template per ogni tipologia di pagina è illimitato e ciascuno può essere richiamato al volo.

* I parametri bgcolor1, bgcolor2, bgcolor3 e bgcolor4 dei vostri temi sono disponibili come tag nei vostri template.

* Sono presenti dei template di default, in modo da poter attivare da subito la vostra agenda.

* Nei template mensili sono incluse viste alternative di tipo hover e a lista.

* Le funzioni Invia, Approva, Modifica e Cancella usano tutte lo stesso form offrendo ai programmatori javascript interessanti possibilità di far uso di funzioni di controllo dei dati prima e dopo l'invio (all'insegna del "fatelo da soli!").

* L'opzione multilingue è supportata.

Cap. 3: Installazione

L' installazione è molto facile grazie alla nuova funzione di inizializzazione del modulo. Seguite questi pochi passi:

* spostate i file di Calzone nella directory modules;

* aprite la sezione Moduli in Amministrazione e rigenerate l'elenco dei moduli;

* il modulo Calzone dovrebbe comparire nell'elenco; cliccate sul link inizializza in modo da approntare il database;

* attivate il modulo;

* aprite in modifica il blocco Menu e inserite una voce Agenda e un link a 'index.php?module=Calzone'.

Siete pronti per aggiungere gli eventi del giorno!

Cap. 4: I tag

L'accesso al database degli eventi avviene attraverso l'uso di tag. I tag hanno una forma del tipo {MONTH}/{DAY}/{YEAR}, che nel caso specifico servirebbero a mostrare una data come '03/09/1959'. Un tag viene rimpiazzato dai dati che richiama al momento della compilazione che avviene subito prima che la pagina venga effettivamente mostrata. Questo è un elenco dei tag disponibili per i vari template:

* Comuni a tutti i template: BGCOLOR1, BGCOLOR2, BGCOLOR3, BGCOLOR4, TEXTCOLOR1, TEXTCOLOR2, ACCESSLEVEL,

DAYLONG1, DAYSHORT1, DAYLONG2, DAYSHORT2, DAYLONG3, DAYLONG4, DAYSHORT4, DAYLONG5, DAYSHORT5,

DAYLONG6, DAYSHORT6, DAYLONG7, DAYSHORT7, DAYLONG, DAYSHORT, MODNAME, MONTH, MONTHSHORT, MONTHLONG,

DAY, YEAR, SUBMITLINK, DAYLINK, MONTHLINK, YEARLINK, ddJUMPMONTH, ,ddJUMPDAY, ddJUMPYEAR, ddVIEW, HEADER,

FOOTER

* Note: ACCESSLEVEL restituisce un numero compreso fra '0' - nessuna autorizzazione - e '8' - autorizzazione di amministratore. In questo modo è sempre possibile valutare le autorizzazioni in possesso del vostro utente. DAYLONG1-7 e DAYSHORT1-7 corrispondono rispettivamente ai nomi estesi e brevi dei giorni della settimana come sono definiti da settaggi correnti. MODNAME restituisce il nome del modulo corrente, che dovrebbe chiamarsi 'Calzone'. La maggior parte di questi tag viene usata nell'intestazione (header) e nel piè di pagina (footer), anche se si possono usare in qualsiasi altro template.

* Eventi visualizzati: SUBJECT, EID, UID, SUBMITTEDBY, APPROVEDBY, AID, SUBMITMONTH, SUBMITMONTHLONG,

SUBMITMONTHSHORT, SUBMITDAY, SUBMITYEAR, SUBMITHOUR, SUBMITAMPM, SUBMITMIN, SUBMITSEC, APPROVEDMONTH,

APPROVEDMONTHLONG, APPROVEDMONTHSHORT, APPROVEDDAY, APPROVEDYEAR, APPROVEDHOUR, APPROVEDAMPM,

APPROVEDMIN, APPROVEDSEC, STARTMONTH, STARTMONTHLONG, STARTMONTHSHORT, STARTDAY, STARTYEAR,

STARTHOUR, STARTAMPM, STARTMIN, ENDMONTH, ENDMONTHLONG, ENDMONTHSHORT, ENDDAY, ENDYEAR, ENDHOUR,

ENDAMPM, ENDMIN, ALLDAYEVENT, REPEATTYPE, BODY, ebBODY, ebSUBJECT, STARTDAYLINK, ENDDAYLINK, EVENTLINK,

TOPICIMAGE, TOPICNAME, TOPICTEXT, EDITLINK, escBODY, escSUBJECT

* Note: Questi eventi non sono disponibili nella vista annuale, ma dovrebbero funzionare correttamente quasi in qualunque altra posizione. ebBODY e ebSUBJECT si usano nelle form, come quella di invio. escBODY e escSUBJECT funzionano come BODY e SUBJECT, ma i caratteri speciali vengono dotati di sequenze di escape per essere usati con javascript.

* Form di invio: SUBJECT, ddOPTION, ddTOPICS, ddREPEAT, ddSTARTMONTH, ddSTARTDAY, ddSTARTYEAR, ddENDMONTH,

ddENDDAY, ddENDYEAR, ddSTARTMIN, ddENDMIN, ddENDAMPM, ddSTARTAMPM, ddSTARTHOUR, ddENDHOUR, ddSTARTHOUR,

ddENDHOUR, BODY, EID, PREVIEW

* Note: La maggior parte di questi tag viene usata nella form di invio per fornire informazioni aggiornate quando si modifica, si fa l'anteprima e si cancella. Il tag PREVIEW dovrebbe essere disposto dove desiderate che l'evento di esempio venga mostrato in anteprima.

* Vista mensile: NEXTLINK, PREVLINK, CURRENTMONTH, CURRENTMONTHSHORT, CURRENTMONTHLONG, CURRENTDAY,

CURRENTYEAR, CURRENTDATELINK, NUMEVENTS, NUMDAYEVENTS

* Note: NEXTLINK e PREVLINK contengono link ai mesi precedente e successivo. CURRENTDATELINK punta alla vista giornaliera del giorno corrente. NUMEVENTS contiene il numero di eventi nel mese corrente, mentre NUMDAYEVENTS mostra il numero di eventi nel giorno del mese corrente.

* Vista annuale: NEXTLINK, PREVLINK, THISYEAR, THISMONTH, THISMONTHSHORT, THISMONTHLONG, MONTHTYPE, DAYTYPE,

CURRENTMONTH, CURRENTMONTHSHORT, CURRENTMONTHLONG, CURRENTDAY, CURRENTYEAR, CURRENTDATELINK,

EVENTCOUNT

* Note: NEXTLINK e PREVLINK contengono link agli anni precedente e successivo. MONTHTYPE restituisce o 'currentmonth' o 'othermonth'. DAYTYPE restituisce 'today' o 'otherday'; questi tag possono essere usati per evidenziare il giorno o il mese correnti. EVENTCOUNT restituisce il numero di eventi nel giorno corrente.

* Vista giornaliera: NEXTLINK, PREVLINK, NUMEVENTS, NUMALLDAYEVENTS, NUMTIMEDEVENTS

* Note: NEXTLINK e PREVLINK contengono link ai giorni precedente e successivo. NUMEVENTS mostra il totale degli eventi del giorno. NUMALLDAYEVENTS mostra il numero dei soli eventi giornalieri. NUMTIMEDEVENTS mostra il numero dei soli eventi temporizzati.

Cap. 5: I template

Il modo più semplice per comprendere il funzionamento dei template di Cal-Zone è modificare uno di quelli di default, in cui ho cercato di incorporare esempi di tutto, da javascript a i fogli di stile. L'implementazione di default non è necessariamente la migliore soluzione possibile. Tenete presente che i template di default non pretendono di essere altro che esempi. Iniziate con i template dell'intestazione (header), del piè di pagina (footer), dell'anteprima (preview), dei messaggi (message) e degli eventi (event) perché sono i più semplici. Vi fornirò alcune osservazioni sugli altri per aiutarvi. Dapprima i template possono sembrare terribilmente complicati, ma ricordate che sebbene vi siano moltissimi tag disponibili, non siete obbligati a usarli tutti. I vostri template possono essere tanto semplici o complessi come più vi piace.

* Header (Intestazione), Footer (Piè di pagina), Event (Evento), Preview (Anteprima), Message (Messaggi): Sono molto semplici. E' sufficiente inserire il codice HTML che serve usando i tag delle aree appropriate. Buona parte di ciò che vi può servire viene mostrato esattamente come è.

* Day (Giorno): In questo template sono definiti 4 blocchi. Probabilmente non li userete tutti insieme, ma chi può dirlo?

* DAYBLOCK: Posiziona i tag di inizio e fine blocco attorno al codice che definisce il template giornaliero; questo verrà ripetuto per ciascuno dei giorni richiesti.

* Timed events: Mostra solo gli eventi temporizzati Posiziona il codice per gli argomenti all'interno del ciclo TIMETOPICBLOCK. Ciascun argomento genererà una chiamata a questo blocco.Il blocco TIMEEVENTLIST ospita il codice destinato a ciascun evento all'interno dell'elenco degli argomenti.

* All Day Events: Mostra solo tutti gli eventi giornalieri. Posiziona il codice per gli argomenti all'interno del ciclo DAYTOPICBLOCKp. Ciascun argomento genererà una chiamata a questo blocco. Il blocco DAYEVENTLIST ospita il codice destinato a ciascun evento all'interno dell'elenco degli argomenti.

* All Events:Questo blocco mostrerà tutti gli eventi assieme. Posiziona il codice per gli argomenti all'interno del ciclo ALLTOPICBLOCK. Ciascun argomento genererà una chiamata a questo blocco. Il blocco ALLEVENTLIST ospita il codice destinato a ciascun evento all'interno dell'elenco degli argomenti.

* Month (Mese):In questo template sono definiti 4 blocchi.

* WEEKBLOCK è dove metti il codice per aprire e chiudere una settimana. In un calendario tipico questo farebbe cominciare solo una nuova riga per la settimana.

* DAYBLOCK è dove piazzi il codice per ciascun giorno singolo.

* TOPICBLOCK è dove va il codice per ciascun gruppo di eventi appartenenti allo stesso argomento.

* EVENTLIST è il codice per ciascun evento singolo nella lista.

* Submit (Invia evento): Il template Submit non è che un normale form. Potete farci quello che volete purché vi assicuriate di impostare tutte le variabili richieste. Anche se non volete usare tutti i campi, per esempio se non volete usare gli argomenti (topics), potete comunque includere un argomento di default per Cal-Zone e modificare gli altri template in modo da non mostrarli. Di seguito ecco le variabili obbligatorie di Submit:

* eid

* subject

* alldayevent

* body

* op2

* month

* day

* year

* tid (topic id)

* alldayevent

* starthour

* startmin

* startampm

* endhour

* endmin

* endampm

* repeat

* endmonth

* endday

* endyear

* option (cosa farne?: invio, anteprima, ecc.)

* Year (Anno): Un template semplice. Ci sono 3 blocchi: MONTHBLOCK, WEEKBLOCK e DAYBLOCK. Ciascuno contiene il codice per creare le relative sezioni. dell'anno. Questa vista richiede un certo tempo per essere generata poiché controlla gli eventi disponibili per ogni giorno dell'anno.

* Init (Inizializzazione): Il template Init è un caso speciale. Non importa quante volte viene chiamato: genererà il suo output solo una volta per pagina. Ciò lo rende ideale per inserire librerie javascript, settare variabili ecc. Questo template viene chiamato ogni volta che viene mostrato un componente Calzone. Se avete la necessità di inserire questo codice come parte dei tag della vostra pagina web Envolution potete chiamare il template Init dall'interno del tema Effettuate una rapida ricerca del tag nel vostro tema e inserite il codice include ("modules/Calzone/init.php") subito prima.

Cap. 6: I Link

Se si sa come chiamare le varie unzioni dell’agenda si possono generare delle viste assai piacevoli. Segue quindi una spiegazione dei link utilizzati. Alcuni parametri sono obbligatori, mentre altri sono opzionali. Iniziamo con i link fondamentali:

* http://yoursite.com/index.php?module=Calzone mostra la vista mensile per il mese corrente;

* view=month|day|year|submit|event seleziona da un elenco di viste che comprende quelle di: mese, giorno, anno, invia evento ed evento;

* num=x è un parametro che mostra x settimane o mesi nelle viste del mese o dell’anno;

* date=mm/dd/yyyy è un parametro che mostra il giorno, mese, o anno correnti a seconda della vista scelta;

* eid=xx assieme a view=submit seleziona la modalità modifica/cancella, purché l’utente possieda le autorizzazioni appropriate, quindi non esaltatevi;

* http://yoursite.com/index.php?module=Calzone&type=admin attiva la modalità di amministrazione, purché l’utente possieda le autorizzazioni appropriate. Vi si può accedere anche dall’interno della pagina di amministrazione del sito.

Ecco alcuni esempi:

* http://yoursite.com/index.php?module=Calzone&view=day mostra la vista giornaliera della data corrente;

* http://yoursite.com/index.php?module=Calzone&view=day&date=03/09/2002 mostra gli eventi nella vista giornaliera del 9 marzo 2002;

* http://yoursite.com/index.php?module=Calzone&view=month&num=2 mostra 2 settimane del mese corrente partendo dalla data corrente;

* http://yoursite.com/index.php?module=Calzone&view=month&num=2&date=03/09/2002 mostra 2 settimane nella vista mensile a partire dalla settimana in cui cada il giorno 9 marzo 2002;

* http://yoursite.com/index.php?module=Calzone&view=year&date=03/09/2010&num=6 mostra la vista annuale a partire dal mese in cui cade la data del 9 marzo 2010 per la durata di 6 mesi;

* http://yoursite.com/index.php?module=Calzone&view=submit&eid=3 caricherà la vista di invio con i dati dell’evento #3; da qui potete modificare o cancellare l’evento.

Cap. 7: Lingue diverse

Nella directory pnlang directory troverete le sotto directory delle lingue supportate. Attualmente vi sono italiano, inglese, francese e tedesco. Cal-Zone userà quella definita per il sito o l’inglese per default. In ciascuna si trova un file chiamato template.php che contiene le espressioni principali. Siete liberi di aggiungere nuove stringhe di testo o di modificare quelle esistenti. I template di dafault usano questo metodo per creare una agenda multilingue. Se questa possibilità non vi interessa potete inserire i testi direttamente dentro i template.

Cap. 8: Autorizzazioni

Ecco una guida rapida all’implementazione delle autorizzazioni in Cal-Zones:

* None: non può accedere all’agenda;

* Overview: non può fare molto (ma chi sa in futuro...);

* Read: può vedere gli eventi, ma non aggiungerli;

* Comment: può inserire eventi, ma essi devono poi essere approvati;

* Moderate: può inserire eventi che vengono automaticamente approvati;

* Edit: può modificare gli eventi, ma non approvarli o cancellarli;

* Add: può approvare e modificare gli eventi, ma non cancellarli;

* Delete: può cancellare oltre che approvare e modificare gli eventi;

* Admin: può fare tutto.

Come potete vedere, ciò vi offre una molteplicità di opzioni circa chi può fare che cosa. Fate esperimenti con settaggi differenti e se scoprite delle configurazioni interessanti fatemelo sapere in modo da poterle condividere con altri utenti. Ecco qua alcune delle mie configurazioni:

* volete un’agenda privata che nessuno dei vostri utenti può vedere:

* Gruppi: All Users

* Componenti: Calzone::

* Istanza: ::

* Livello autorizzazioni: none

Inseritela sopra a tutte le autorizzazioni generiche, ma sotto quelle di Admin;

* volete che gli utenti anonimi possano inserire nuovi eventi, ma che solo gli utenti registrati ricevano un’approvazione automatica:

* Gruppi: Unregistered

* Componenti: Calzone::

* Istanza: ::

* Livello autorizzazioni: Comment

questo settaggio consente l’inserimento di nuovi eventi da parte di utenti non registrati;

* Gruppi: Users

* Componenti: Calzone::

* Istanza: ::

* Livello autorizzazioni: Moderate

questo settaggio consente l’approvazione automatica degli eventi inseriti dagli tenti registrati.

Naturalmente ci sono parecchi modi per ottenere questi risultati, ma almeno adesso avete qualcosa su cui pensare.

Nota: al momento di scrivere il sistema di autorizzazioni di Envolution è ancora in fase di sviluppo. Trovo che in certi caso sia preferibile settare un’autorizzazione a livello di utente che di gruppo. La maggior parte dei settaggi può trovarsi anche nelle autorizzazioni utente. Dopo aver settato un’autorizzazione effettuate test accurati perché un errore può rendere il vostro sito vulnerabile agli attacchi.

Cap. 9: Una parola conclusiva

Questa documentazione non vuole essere definitiva. E’ un documento aperto che continuerà a crescere nel tempo. Se avete qualche buona idea fate un salto su http://hamlinworld.com/ e fatecelo sapere. Daremo rilievo ai siti che usano questa agenda e che condividono template, javascript, trucchi, idee ecc. Il mio sogno è di imbattermi prima o poi nella più fantastica delle agende per poi scoprire che si tratta di Cal-Zone che ha subito un lifting eccezionale. Facciamolo insieme...