How To

Creare un template di base per Joomla!

Traduzione dell'articolo Creating a basic Joomla! template scritto da AAVV, licenza JEDL.

Indice

Introduzione

Lo scopo di questa guida è fare da introduzione alla creazione di template per Joomla!. Spiega i files essenziali ed il codice necessario per creare un template di base. Il codice è presentato in modo che possa essere copiato e incollato con solo la necessità di minime modifiche.

Impostazione della struttura delle cartelle

Per creare un template elementare, crea una nuova cartella dentro alla cartella "templates". Dai un nome a questa nuova cartella che sia uguale al nome del tuo nuovo template, esempio "mionuovotemplate".

Usando un editor di testi (oppure un editor specifico come NetBeans) crea i files "index.pxp" e "templateDetails.xml".

Per mantenere le cose in ordine, crea due nuove cartelle chiamate "images" e "css". Dentro la cartella "css" crea un file chiamato "style.css".

Anche se, all'inizio, andrebbe bene mettere tutto il tuo codice CSS direttamente nel tuo file "index.php", molti sviluppatori Web preceriscono mettere il loro codice CSS in un file separato, che può essere richiamato da diverse pagine usando il tag HTML "<link ...".

Questa è la configurazione pratica più elementare.

Profilo della struttura dei files e delle cartelle:

    • mionuovotemplate/
    • css/
    • style.css
    • images/
    • index.php
    • templateDetails.xml

 

Creare un file templateDetails.xml di base

Il file templateDetails.xml è essenziale. Senza quello, il tuo template non sarà riconosciuto da Joomla!. Il file contiene "metadati" vitali che descrivono il template.

Vediamo un esempio:

This email address is being protected from spambots. You need JavaScript enabled to view it.

Quindi, come puoi vedere, abbiamo un insieme di informazioni in mezzo ai tags di markup (quei "cosi" fatti <così>). Il miglior modo di iniziare è fare un copia e incolla di questo esempio nel tuo file "templateDetails.xml" e modificare le parti rilevanti (tipo <name> e <author> ).

Il tag <files> dovrebbe contenere tutti i files necessari al tuo template ed è possibile che tu ancora non conosca l'elenco completo, ma non ti preoccupare, puoi aggiornare "templateDetails.xml" in seguito.

Lascia le <position> così come sono, quelle sono impostazioni abbastanza usuali, più avanti potrai facilmente commutare ad altre impostazioni.

Creare un file index.php di base

Il file "index.php" diventa la base di ogni pagina che Joomla! crea. Essenzialmente devi fare una pagina (come qualsiasi altra pagina HTML), ma metterci del codice PHP nei punti in cui vuoi che ci siano i contenuti del tuo sito. Qui c'è il codice ridotto all'osso che puoi copiare e incollare. Partiamo dall'inizio:

 <?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >

La prima riga ferma i cattivi che cercano di vedere il tuo codice per fare cose antipatiche. La seconda dice al browser (ed ai motori di ricerca) che tipo di pagina sia questa. La terza riga dice in che lingua è il sito.

Ed ora l'intestazione "vera":

 <head>
<jdoc:include type="head" />
<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/mionuovotemplate/css/style.css" type="text/css" />
</head>

La prima linea fa in modo che Joomla! metta le corrette intestazioni. Questo include il titolo della pagina, alcune "meta-informazioni", i riferimenti al foglio di stile CSS di sistema (non il tuo, NdT) e al codice JavaScript. La seconda linea crea un collegamento al tuo foglio di stile. Devi cambiarlo in modo che riporti il nome di file che hai scelto prima (se prima lo avevi cambiato rispetto all'esempio, NdT).

Veniamo al corpo della pagina:

 <body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>

Incredibilmente questo basterà! Sì, è un layout molto semplice, ma funzionerà. Tutto il resto sarà fatto da Joomla!. Nota: devi assicurarti che il tuo menù sia impostato per far andare il rispettivo modulo in posizione "top".

Per finire, l'ultimo pezzettino:

 </html>

L'intero codice:

 <?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/mynewtemplate/css/style.css" type="text/css" />
</head>
<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>
</html>

Pacchettizzare il template per l'installazione

Una cartella con molti files isolati non è un modo conveniente di distribuire un template. Quindi il passo finale è fare un pacchetto. Questo sarebbe un archivio compresso della cartella e di tutti i files contenuti. Il pacchetto può essere in formato ZIP (con estensione .zip), oppure in formato TAR-gzip (con estensione .tar.gz), o ancora in formato TAR-bzip2 (con estensione .tar.bz2).

Se il tuo template è in nella cartella mionuovotemplate/ allora per creare il pacchetto puoi spostarti in quella cartella ed usare comandi tipo:

 tar cvvzf ../mionuovotemplate.tar.gz *

oppure (Windows)

 zip -a -r ..\mionuovotemplate.zip *.*

Nota per gli sviluppatori di template che usano Mac OS X: la voce "comprimi" nel menù di Finder produce un formato ZIP utilizzabile, ma con un problema. Memorizza i files in formato AppleDouble, aggiungendo files extra con nomi che iniziano per "._". Quindi aggiunge anche un file chiamato "._templateDetails.xml, che Joomla 1.5.x può a volte interpretare male. Il sintomo è un errore di interpretazione, "XML Parsing Error at 1:1. Error 4: Empty document". Il modo di aggirare il problema è comprimere da linea di comando ed impostare la variabile d'ambiente della shell "COPYFILE_DISABLE" a "true" prima di usare "compress" o "tar" (altro modo di aggirare il problema è non usare Mac OS X alla faccia della sua presunta semplicità d'uso, NdT). Vedere l'articolo AppleDouble (in inglese) per ulteriori informazioni.

Conclusioni

Dovresti ora aver creato un template che funziona. Esteticamente non sarà un gran che per ora. La miglior cosa da fare adesso è iniziare a sperimentare con i layout.

(In realtà dopo aver provato la procedura qui descritta ho notato che manca un suggerimento fondamentale, senza il quale il template non funziona. Nel file index.php suggerito si fa giustamente riferimento ai files template_thumbnain.png, images/background.png e css/style.css. Prima di pacchettizzare il template è necessario creare quei files, altrimenti Joomla! non riuscirà ad installare il template. Il file template_thumbnail.png deve essere un'immagine che serva come anteprima del template quando il mouse passa sopra al nome del template nella Gestione Template di Joomla!. Il file images/background.png deve esserci in quanto lo si cita nei files esistenti, ma in realtà non viene utilizzato se non direttamente da voi nel CSS quando eventualmente vorrete usarlo. Il file style.css sarà quello che userete per personalizzare il template: ai fini del funzionamento dello stesso basta che esista, anche vuoto va bene.