Attenzione: questo manuale è disponibile anche in formato Pdf qui MANUALE PER TEMI PHPNUKE-v0.0.1beta.rar

PREMESSA
In questo corso proveremo a spiegare come fare un tema per PHPNuke. Io non mi considero un esperto e quello che leggerete è semplicemente il risultato di esperienze dirette vissute mettendo le mani negli scripts. Appena terminerete il corso sicuramente non sarete “padroni del mestiere” ed avrete ancora molti dubbi, niente paura! Il consiglio è quello di rileggere, provare-senza timore- in locale, ad esercitarvi direttamente sui files e vedrete che tutto diventerà più chiaro giorno dopo giorno.

Scrivere un tema Nuke non è particolarmente difficile ma sicuramente è molto ma molto più difficile descrivere come fare… Ho iniziato la stesura di questi appunti più di un anno fa con l’intento di perfezionarli al massimo prima di rilasciarli alla community ma il tempo è volato e l’obiettivo prefissato era sempre più lontano. Purtroppo il tempo disponibile è poco e per questo motivo ho deciso di rilasciare il lavoro in versione beta auspicando che chi lo leggerà potrà collaborare alla versione definitiva. Saranno gradite segnalazioni di errori di battitura e, ancora di più, segnalazioni di errori concettuali e relative correzioni. Grazie in anticipo a chi vorrà darmi una mano.
Ora basta con le chiacchiere, è tempo di iniziare.

Requisiti
Per applicare il contenuto di questo manuale è indispensabile conoscere il linguaggio Html, conoscere almeno le basi del PHP e il funzionamento del Nuke.

 

PRIMA PARTE: TEMI IN PHP

Come è fatta una pagina PhpNuke
Qualsiasi pagina che vedi in un portale realizzato con PhpNuke è formato dalle seguenti parti:


1. Testata - Dove si trovano il logo, il menu, ecc... del tuo sito
2. Colonne - Che sono sempre tre e contengono: i Blocchi di destra, i Blocchi centrali e i Blocchi di sinistra.
3. Piè di pagina - è l’area dove di solito si trovano informazioni varie ed il copyright.
Schematizzando quanto appena detto ecco la struttura classica di un sito PHPNuke. 
 

Quando avete installato la prima volta PHP-Nuke vi sarete accorti che la struttura è alquanto diversa dal sito Html che probabilmente molti di voi conoscono, anche la struttura delle pagine php è diversa da quella Html. In un file Html tutta la pagina si sviluppa in una sequenza lineare e cioè abbiamo il logo poi il menu, la parte centrale, ecc.... le pagine php non sono organizzate così.
Per molti di noi non è facile creare pagine php proprio perchè siamo abituati a lavorare con editor Wysiwig come FrontPage, Dreamweaver, dove basta inserire immagini, links, testi, ecc... e tutto ciò che vediamo è esattamente ciò che verrà pubblicato: in php, purtroppo, non è così!
Non esistono editor Wysiwig per php e quindi per creare una pagina occorre necessariamente scrivere il codice a mano, anche se, come vedremo nelle pagine successive, riusciremo a manipolare alcune parti dei temi anche con Frontpage o Dreamweaver.
Un’altro importante aspetto del php è il fatto che questo tipo di linguaggio viene eseguito sul server a differenza dell' Html o del JavaScript che sono eseguiti nel browser. Questo significa che quello che viene scritto in un file php viene letto e interpretato sul Server ed il risultato, che poi altro non è che la pagina, inviata al Browser.
Ora, prima di continuare, occorre chiarire alcuni concetti base che troverete più avanti all’interno del codice dei temi. Non vi spaventate se non capite subito il significato di alcuni termini, per quello che vi serviranno sarà sufficiente che ne cogliate il concetto base e a cosa servono.

Variabili
Sono gli elementi più facilmente riconoscibili in quanto iniziano con il simbolo $, per esempio $sitename. Queste variabili sono molto usate in tutti i files del Nuke in quanto permettono di richiamare in modo semplice e rapido nomi, immagini e quant’altro. Per esempio se in uno script trovate la scritta $sitename questa verrà interpretata come il "Nome del Sito", cioè dove si mette questa variabile apparirà il nome del sito. Possiamo trovare, per esempio, $bgcolor2 che verrà interpretata come “lo sfondo dell’area deve avere il colore 2” naturalmente in un altro punto dello script saranno definiti i colori corrispondenti ai vari numeri. Questo aspetto lo vedremo in pratica non appena inizieremo costruire il nostro primo tema che inizierà proprio con la definizione dei colori del sito.

Funzioni
Sono gli elementi che danno la forma al Nuke, la struttura generale viene definita per mezzo delle funzioni. Il contenuto delle Funzioni si inserisce tra due simboli { } . All'inizio della Funzione utilizziamo la parola global e subito dopo aggiungiamo le variabili che verranno usate. In questo modo è come se dicessimo a Nuke "Allora caro Nuke adesso includi queste Variabili”

echo " ";
Tutto ciò che è tra le virgolette viene interpretato dal browser, cioè quello che scrivi all’interno delle virgolette è esattamente quello che si vedrà nella pagina.

Ci sono molte altre cose da dire sul linguaggio php ma, per il momento, limitiamoci ed iniziamo a creare il nostro primo tema, un tema semplice e senza pretese in quanto lo scopo è quello di iniziare a prendere confidenza con le nozioni base. Probabilmente il tema che andremo a realizzare adesso non lo userete mai per il vostro sito ma occorre comunque studiarlo perchè in tal modo acquisiremo molte ed importanti nozioni che saranno utilizzate anche sui temi più complessi e belli graficamente.
 
Struttura di un tema in Php
Come sapete ogni tema è contenuto in una cartella che porta proprio il nome del tema quindi la prima operazione che faremo sarà quella di creare la cartella principale del tema dandole un nome, noi la chiameremo Donkey.

Questa cartella dovrà sempre contenere come minimo le seguenti cartelle e files:
1. Un file theme.php
2. Un file style.css, che metteremo in una cartella chiamata style
3. Una cartella che chiameremo images (con le immagini del tema)
4. Aggiungiamo un file index.html in ogni cartella (si tratta di un file html completamente vuoto)

Preparazione del file theme.php
Nei file in linguaggio php possiamo combinare codice php e html, è quello che faremo anche in questo tutorial nel file theme.php.
Con il vostro editor aprite una nuova pagina e nominatela theme.php
Dovete sapere che qualsiasi file scritto in php deve essere inserito tra un'etichetta di apertura ed una di chiusura: alcuni editor lo fanno automaticamente quando aprite una nuova pagina, se invece usate editor semplici come ad esempio Notepad dovete inserirle manualmente. E' molto semplice in quanto dovete scrivere solo <?php e ?>

Se provate ad aprire un qualsiasi file di Nuke potete constatare che tutti iniziano e finiscono in questo modo. Ora possiamo iniziare ad inserire il contenuto:

Struttura del file theme.php
Abbiamo detto che il file theme.php contiene la struttura del tema, tabelle, header (la parte superiore), l'aspetto con cui si presentano le news, l'aspetto dei blocchi, e il footer (la parte in basso). Ognuna di queste aree viene rappresentata in una funzione, che elenchiamo:

OpenTable() - Qui inseriamo i tags html che serviranno per creare l'inizio di una tabella.
CloseTable() - Qui inseriamo i tags che permetteranno di chiudere la tabella che avevamo creato con opentable().
ThemeHeader() - E' una delle più importanti funzioni in quanto qui vengono inseriti i tags come il body ed altri necessari a definire il resto del layout della pagina.
FormatStory() - Configurazione delle notizie del nostro portale. E’ la parte dove viene inserito solo il testo delle notizie.
ThemeIndex() - Contiene il formato generale delle notizie del nostro portale e cioè: formato del titolo, autore e tutto il contenuto.
ThemeArticle() - Formato della notizia quando clicchiamo su Leggi Tutto.
ThemeSideBox() - Altra importante funzione, da qui viene settato il formato dei blocchi. 

Ora che abbiamo chiarito il significato delle funzioni possiamo introdurre in esse il contenuto.
Spieghiamo come deve essere usato html in un file php. Prima di tutto vi presento una regola fondamentale, quando inserite codice html in un file php, in questo caso nel file theme.php, non potete usare le virgolette " però, direte voi, nel nostro codice html ci sono molte virgolette ed allora? Allora la soluzione è molto semplice: è sufficiente far precedere le virgolette da una barra contraria slash \" ossia dovete rimpiazzare tutte le " con \"
La prima cosa che dobbiamo inserire nel file theme.php sono i colori che vogliamo usare per gli sfondi e per alcune parti del testo. Questo si fa in modo molto semplice utilizzando le variabili come vedete qui sotto. Nel nostro caso vediamo 4 variabili per gli sfondi (quindi 4 colori) e due variabili per i testi. Spero che tutti conosciate il codice colori che vedete utilizzato, per chi non lo sapesse, diciamo semplicemente che si tratta di un codice che permette di chiamare ogni colore con una combinazione di 6 caratteri tra numeri e lettere.

Ora ogni volta che vorremo usare il colore #FFFFFF, sarà sufficiente scrivere nello script $bgcolor1 e così via per tutti gli altri. Questo è molto utile per i programmatori, per esempio se creiamo un modulo, possiamo utilizzare la variabile $bgcolor1 per lo sfondo e in questo modo otterremo che il modulo richiamerà sempre quel colore con qualsiasi tema, cioè il modulo si adatterà automaticamente ai colori di qualsiasi tema.

Ora proseguiamo con le funzioni OpenTable() e CloseTable(),

Il tag echo invia il contenuto compreso tra le " " al browser

invierà al browser la stringa

In pratica scrive i tags html e rimpiazza la variabile $bgcolor2 con il valore di questa. Come vediamo, resta da chiudere il tag <table> quindi per farlo dichiariamo la funzione closetable() 

invierà al browser la stringa

Abbiamo realizzato le tabelle. Come vedete si usano le variabili $bgcolor1, $bgcolor2 per definire i colori. Il codice usato è Html, nella funzione OpenTable ci sono i tag di apertura e nella CloseTable quelli di chiusura. Qui per esempio potete mescolare i colori ed anche definire la distanza di apertura con i tags cellspacing.
Ora proviamo ad unire le due funzioni

Possiamo richiamare questo file da http://tuosito.com/themes/Donkey/theme.php e, se controlliamo il codice generato, vedremo 

E' importante sapere che questa funzione è la più usata quando occorre inserire contenuti in Nuke. Ogni volta che vogliamo aprire una tabella scriviamo Opentable(); e per chiuderla scriviamo Closetable();
Per rendere più chiaro il concetto guarda questo esempio

Se provate a creare un modulo con questo contenuto vedrete la frase Qui inserisci il contenuto all'interno di una tabella. Questo è il modo di usare questa funzione.
Passiamo ora ad analizzare la funzione che gestisce le News e che si chiama FormatStory()

Ora la nostra funzione riceve alcuni parametri

Ossia quando viene invocata le vengono inviati i parametri.
Più avanti vedremo come si inviano i parametri e da dove è invocata la funzione.