Configuring WB

Luca Fini (lfini@arcetri.astro.it). Settembre 2006

Introduzione Istallazione Configurazione Uso Copyright F.A.Q.

Come definire una nuova bacheca

Nel testo seguente sarà fatto rifgerimento spesso al termine radice delle bacheche. Si tratta della directory creta in fase di istallazione dove sono stati memorizzati i files ausiliari di WB. Supponiamo ad esempio, che sia stata chiamata: /var/www/http/BillBoards.

Per definire una nuova bacheca deve essere semplicemente creata una directory nalla radice. Il nome della directory coincide con il nome della bacheca. Supponendo di voler creare una bacheca di nome Ultimissime si userà il comando:

> mkdir /var/www/http/BillBoards/Ultimissime

Nota: È possibile usare qualunque nome per le directory, ecctto i nomi che iniziano per '.' e per '_', che sono riservati a scopi speciali.

Occorre poi assicurarsi che il web server abbia i diritti di accesso necessari per leggere, scrivere e creare files nella sottodirectory Ultimissime. È quindi necessario assegnare la proprietà della directory all'opportuno ID, analogamente a quanto fatto per la radice in fase di istallazione. Ad esempio, supponendo che l'ID del server apache sia "cochise":

> chown cochise /var/www/http/BillBoards/Ultimissime

La bacheca è pronta a funzionare, ma è possibile personalizzarla per adattarla all'uso richiesto.

Personalizzazione della bacheca

La personalizzazione si effettua copiando nella directory della bacheca il file di inizializzazione wb.ini disponibile nella radice e modificandolo opportunamente. Il file di inzializzazione contiene la ridefinizione di numerosi comandi usati dal programma WB. Il file wb.ini fornito come esempio contiene spiegazioni dettagliate per ogni comando configurabile, ma alcuni di questi richiedono ulteriori spiegazioni.

index_header, index_item, index_footer, doc_header, doc_footer

Questi comandi contengono la definizione del formato delle linee di indice e dei documenti generati da WB. Ogni comando è costituito da una sequenza di linee ed ogni linea genera una linea di codice HTML.

L'indice dei documenti è una pagina HTML generata con la seguente procedura:

Intestazione generata con a partire dal contenuto del comando index_header.
Per ogni docuemnto registrato un blocco generato a partire dal contenuto dell comando index_item
La pagina termina con il testo generato dal comando index_footer.

La pagina per visualizzare il contenuto di ciascun documento viene invece generata come segue:

Testo generato a partire dal contenuto del comando doc_header.
Testo del documento
Lista di allegati (se ci sono allegati)
Testo generato a partire dal contenuto del comando doc_footer.

Per la generazione del testo ciascun comando viene processato in modo da sostituire il valore corrente di alcune "variabili".

Ad esempio i valori di default dei cinque comandi elencati sopra sono:

index_header = ['<h3>Index for billboard: <i>%(BBOARD)s</i></h3><blockquote><ul>']
index_item   = ['<p><li> %(DATE)s %(EXPIR)s',
                '<br><a href=%(HREF)s>%(TITLE)s</a>']
index_footer = ['</ul></blockquote>']
doc_header   = ['%(DATE)s %(EXPIR)s', '<h3>%(TITLE)s</h3>']
doc_footer   = []

Come si può vedere le linee contengono codice HTML ed alcuni simboli speciali, della forma %(VAR)s, che indicano variabili da sostituire con il loro valore.

Nota: Per scrivere correttamente i comandi di personalizzazione occorre conoscere un po' della sintassi di Python: 1) i commenti iniziano con il carattere "#"; 2) le stringhe di caratteri sono racchiuse fra apici (') o doppi apici ("); il carattere "barra contraria" (\) viene utilizzato per introdurre i caratteri (') o (") nella stringa /ad es: \"); 3) le sequenze di valori sono racchiuse fra parentesi quadre: [ ] e separate da virgole; 4) è possibile andare a capo dopo una virgola.

Nella generazione degli indici dei documenti vengono usate le seguenti variabili:

Tabella 1: Variabili che possono essere usate nei comandi

		Dove è possibile usarla
Nome	Significato	index_header	index_item	index_footer	doc_header	doc_footer	mail_body
AUTHOR	Autore del documento	NO	SI	NO	SI	SI	SI
BBOARD	Nome della bacheca	SI	SI	SI	SI	SI	SI
DATE	Data di creazione	NO	SI	NO	SI	SI	SI
EXPIR	Data di scadenza¹	NO	SI	NO	SI	SI	SI
HREF	Link al documento	NO	SI	NO	SI	SI	SI
N_ITEMS	Numero di documenti	SI	SI	SI	NO	NO	NO
TITLE	Titolo del documento	NO	SI	NO	SI	SI	SI
SEARCH	Campo per specifica di ricerca	SI	NO	SI	NO	NO	NO

1. La data di scadenza è una stringa generata a partire dal comando expir_fmt se una data è stata specificata; e dal comando noexpir_fmt, se non è stata specificata alcuna data di scadenza.

Attenzione: se una variabile viene scritta in modo non corretto, nonsarà visualizzato alcun messaggio di errore e la pagina risulterà vuota.

Provare la correttezza del file di configurazione

La correttezza sintattica può essere provata semplicemente utilizzando Python come nell'esempio seguente:

> python /var/www/http/BillBoards/Ultimissime/wb.ini

Il comando non deve riportare alcun errore (ne altro)

Adesso la bacheca personalizzata è pronta all'uso. billboard.

Ulteriori personalizzazioni

Altre possibili personalizzazioni possono essere effettute modificando altri comandi contenuti nel file wb.ini. I commenti dovrebbero essere sufficienti a comprendere come modificare i comendi. Particolarmente utili possono essere i seguenti:

allowed_users: Lista di ID di utenti autorizzati a modificare la bacheca. L'accesso di tali utenti è comunque protetto da password. Se lalijsta è vuota, chiunque abbia un ID di utente valido sul sistema e ne conosca la password, potrà apportare modifiche.
delete_expired: Specifica se i documenti scaduti (o rimossi) devono essere semplicemente cancellati o trasferiti in una sottodirectory di nome deleted.
language: Specifica la lingua da usare per la bacheca. Il valore è il nome del file di vocabolario. Attualmente sono disponibili i files italiano.voc e english.voc. Se il linguaggio di vostro interesse non è disponible potete crearlo voi stessi partire da uno dei files esistenti (si tratta di una mezz'ora di lavoro).
mail_to: Lista di indirizzi e-mail a cui inviare le notifiche dei cambiamenti avvenuti nella bacheca.
mail_new: Sequenza di linee usate per generare il messaggio da inviare per e-mail, quando viene aggiunto un documetno alla bacheca. Le stringhe possono contenere variabili (vedere tabella 1).
mail_update: Sequenza di linee usate per generare il messaggio da inviare per e-mail, quando viene modificato un documento della bacheca. Le stringhe possono contenere variabili (vedere tabella 1).
sort_order: Parole chiave che specificano l'ordine con cui compaiono le linee nella lista dei documenti. La stringa è una cobinazione delle seguenti parole:
date expir ascending descending
Le parole sono separate da spazi e possono comparire in qualunque ordine. Se si utyilizzano parole contrastanti, il risultato è casuale.

Come definire un nuovo vocabolario

Per poter supportare diverse lingue, tutti i messaggi sono contenuti i file vocabolario contenuti nella radice. Attualmente sono disponibili i file: english.voc, italiano.voc. Utilizzando uno di essi come esempio potreste creare il supporto per una nuova lingua (se lo fate, siete pregati di inviarmi il file per aggiungerlo a quelli disponibili).

I vocabolari disponibili ed il loro contenuto, possono essere visualizzati utilizzando una URL speciale, come nell'esempio:

http://indirizzo.sito.web/cgi-bin/wb.py?.voc

Traduzione dei file di aiuto

La distribuzione corrente contiene files di aiuto in Italiano ed Inglese. I files sono contenuti nelle directory: _doc_it and _doc_uk rispettivamente.

Per aggiungere versioni in altre lingue è possibile creare una nuova directory (ad esempio _doc_fr per il francese), copiarvi tutti i files contenuti in una delle directory citate e provvedere a tradurli. (anche in questo caso, siete pregati di inviarmi i file per includerli nella distribuzione).

Il nome della directory di help deve poi essere specificato nel file wb.ini.