Presentazione

Per ulteriori informazioni o chiarimenti, puoi scrivere a marco@dreadsoft.org.

In questo pacchetto troverai tutti i file e script necessari ad un funzionamento di base di I-DREN. Ci teniamo fin da subito a specificare che I-DREN è un progetto aperto, sia come utilizzo (chiunque può accedere al database) che come modifiche che si possono apportare alle funzioni. Nonostante ciò, tutto è stato progettato per garantire la massima sicurezza per i siti che ospitano i database. Ti ricordiamo che la cosa più importante per il funzionamento del network è che il tuo database rispetti almeno le specifiche di base.

In questo archivio troverai i seguenti file:

index.php questo intende essere un file dimostrativo, anche se funzionante. Serve per mostrare come si può far funzionare il sistema, sia per leggere che per inserire nuovi eventi.

common.php contiene le funzioni di gestione dell'archivio legate alla lettura e interpretazione dei database.

add.php contiene la funzione per l'inserimento di nuovi eventi

idren.css tramite questo file è possibile cambiare l'aspetto delle pagine.

Di seguito troverai informazioni dettagliate su ognuno dei file e sul contenuto. Per dettagli ancora maggiori, puoi ispezionare il codice sorgente, che è stato ampiamente commentato.

common.php

Probabilmente è il file più importante di tutti. Contiene le funzioni necessarie alla lettura, interpretazione e integrazione dei database.

Le costanti

Variare le costanti ti permette di controllare alcuni degli aspetti del funzionamento. Nel caso fosse necessario, puoi cambiarle e il sistema cambierà con loro.

IDREN_LOCAL_DB: indica il percorso relativo al file che contiene il database locale. Il nome predefinito è "dblocale.txt", ma puoi specificare un nome qualsiasi.

IDREN_SITES_LIST: è l'URL dell'elenco centrale dei siti, e, almeno per il momento non deve essere modificato.

IDREN_ADMIN_EMAIL: puoi ricevere un avviso tramite e-mail ogni volta che viene aggiunto un evento.

analyze($txt)

$txt è il contenuto di un database, caricato da una delle funzioni che vedremo in seguito. La funzione analyze esamina il contenuto del parametro $txt e restituisce un array multidimensionale associativo con la seguente struttura:

[<data del primo evento>_<id del primo evento>]

[nome] => <nome del primo evento>
[data] => <data dell'evento>
[_ID_] => <codice del primo evento>
[....]

[<data del secondo evento>_<id del secondo evento>]

[dove] => <luogo del secondo evento>
[data] => <data del secondo evento>
[_ID_] => <codice del secondo evento>
[....]

una volta terminati caricamento e analisi, gli elementi vengono ordinati automaticamente per data.

load_local_db()

Legge il database locale, chiama la funzione analyze e restituisce l'array con gli eventi. In realtà questa è una funzione ormai inutile. E' stata conservata perché può essere utile per test locali.

load_remote_db($remote_url)

Come load_local_db(), ma carica un database da un altro sito; l'URL del database è specificata nel parametro $remote_url.

update_local_db ($new_event)

Questa è la funzione che viene usata per aggiornare il database locale. Il parametro $new_event contiene un array associativo con la stessa struttura presentata in analyze. Per maggiori dettagli sulla funzione, puoi guardare il codice del file add.php.

one_love()

carica la lista dei siti
scarica i database da ognuno dei siti della lista
analizza ognuno dei database
restituisce un array unico

from_today($db)

Questa funzione permette di visualizzare solo gli eventi che avvengono "da oggi in poi". Se oggi è il 10 giugno 2005, verranno visualizzati solo gli eventi di oggi e dei prossimi giorni. Si deve passare come parametro un array multidimensionale con gli eventi (generalmente lo stesso risultato della funzione one_love). La funzione restituisce un array multidimensionale "decurtato" degli eventi passati.

add.php

Raccoglie semplicemente i parametri del form, poi chiama la funzione update_local_db, che si occupa di scrivere i dati secondo le specifiche.

index.php

La pagina proposta nel pacchetto è solo uno spunto su come organizzare le cose. Una volta recuperato il risultato della funzione one_love i dati possono presentati in qualsiasi modo. Semplicemente, la tabella era il modo più ovvio.

In teoria, se vuoi, puoi cambiare anche il contenuto del form. Tieni presente, però, che data, nome, _ID_ e dove sono campi indispensabili.

idren.css

Se non vuoi perdere tempo ad analizzare il codice, o devi semplicemente cambiare i colori, Iin questo file troverai tutte le regole di stile necessarie.

Funzionamento del database

Il database degli eventi è un file di testo con una struttura abbastanza semplice. Ogni evento inizia con una stringa

#EVENTO:

Di seguito a questa stringa, si trovano una o più righe che contengono i vari delimitatori di campo. Ogni identificatore di campo è composto da # seguito da 4 caratteri, seguiti a loro volta dai due punti.

ATTENZIONE L'ordine nel quale vengono proposti i delimitatori di campo è indifferente, ma è fondamentale che i dati relativi ad un campo vengano messi sulla stessa riga del delimitatore. Inoltre, tieni presente che maiuscole e minuscole vanno rispettate (per dirla all'inglese, il database è case-sensitive).

#data: la data dell'evento, nel formato AAAAMMGG

#_id_: codice identificativo dell'evento. Può essere una qualsiasi sequenza di numeri e lettere. Nella versione distribuita viene ottenuto chiamando semplicemente la funzione time(). Il codice univoco è importante per impedire che due eventi che avvengono nello stesso giorno si sovrappongano.

#nome:, #dove:; e #link: si spiegano da soli, sono il nome e luogo dell'evento e il link per ulteriori informazioni.

#desc: la descrizione deve essere salvata su una sola riga. Se vuoi, puoi ottenere i ritorni di linea inserendo il tag <BR> nel testo. Tutto quello che non è nella stessa riga del delimitatore non viene preso in considerazione.

A titolo informativo, sappi che puoi "estendere" i dati contenuti in un database con nuovi campi. Il nome dei nuovi campi deve essere comunque composto da #XXXX: dove XXXX è una sequenza qualsiasi di quattro numeri e/o lettere. Questi dati verranno caricati ugualmente dalla funzione one_love, come chiavi dell'array associativo. Tieni presente che questi dati saranno comunque visibili a tutti gli utenti della rete I-DREN.

Altri dettagli sul formato utilizzato

I-DREN non si appoggia ad un database tipo MySQL perché non tutti i siti possono contare su un database. Condividere il database come semplice file di testo, inoltre, garantisce una sicurezza maggiore, visto che si tratta di un file "inerte" che non ha accesso a funzioni di scrittura.

Sicuramente il formato XML avrebbe permesso di memorizzare i dati in maniera più flessibile, ma anche in questo caso, non tutti i siti supportano le librerie necessarie al parsing e all'interpretazione dei file XML.

Inoltre, queste specifiche, rendono un database estremamente compatto in fase di scaricamento e soprattutto facile da modificare, mantenere, riparare, anche con il Notepad di Windows.