Création d'un template de base pour Joomla
From Joomla! Documentation
It has been suggested that this article or section be split into specific version Namespaces. (Discuss). If version split is not obvious, please allow split request to remain for 1 week pending discussions. Proposed since 8 years ago.
Introduction
L'objectif de ce didacticiel est de servir d'introduction à la création de templates pour Joomla. Il permettra de couvrir l'essentiel des fichiers et du code nécessaire à la création d'un template basique. Le code est présenté de façon à pouvoir être copié et collé, sans nécessité de nombreuses modifications.
Configuration d'une structure de répertoire
Afin de créer le plus simple des templates, créez un nouveau dossier dans le dossier templates. Nommez ce dossier d'après votre template, dans notre exemple, mynewtemplate.
À l'aide de votre éditeur de texte préféré, créez les fichiers index.php
et templateDetails.xml
.
En vue d'une bonne organisation, créez 2 nouveaux dossiers nommés images et css. A l'intérieur du dossier css, créez un fichier nommé template.css
.
Bien qu'il soit tout à fait possible, pour commencer, de placer toutes vos CSS directement dans votre fichier index.php, de nombreux développeurs web préfèrent placer leur code CSS dans un fichier séparé, qui peut être lié depuis plusieurs pages, en utilisant la balise link
. Cela peut également permettre de diminuer le temps de chargement de vos pages, le fichier séparé pouvant être mis en cache.
Voici la plus simple des installations. Structure des dossiers et fichiers :
* mynewtemplate/ ** css/ *** template.css ** images/ ** index.php ** templateDetails.xml
Création d'un fichier templateDetails.xml basique
Le fichier templateDetails.xml est indispensable. Sans lui, votre template ne sera pas vu par Joomla. C'est le fichier contenant les métadonnées clés concernant le template.
La syntaxe du fichier varie selon la version de Joomla.
Pour Joomla! , utilisez le code suivant :
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
<install version="1.5" type="template">
<name>mynewtemplate</name>
<creationDate>2008-05-01</creationDate>
<author>John Doe</author>
<authorEmail>john@example.com</authorEmail>
<authorUrl>http://www.example.com</authorUrl>
<copyright>John Doe 2008</copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>My New Template</description>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<folder>images</folder>
<folder>css</folder>
</files>
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>footer</position>
</positions>
</install>
Pour Joomla! et suivants, utilisez la version ci-dessous. Modifiez
version="2.5"
en indiquant la version Joomla! de votre installation.
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="template">
<name>mynewtemplate</name>
<creationDate>2008-05-01</creationDate>
<author>John Doe</author>
<authorEmail>john@example.com</authorEmail>
<authorUrl>http://www.example.com</authorUrl>
<copyright>John Doe 2008</copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>My New Template</description>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<folder>images</folder>
<folder>css</folder>
</files>
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>footer</position>
</positions>
</extension>
Ainsi, comme vous pouvez le voir, nous avons défini un ensemble d'informations entre les balises (les <element>
s). Vous pouvez copier/coller ceci dans votre fichier templateDetails.xml et modifiez certains éléments (tels que <name>
et <author>
).
La partie <files>
doit contenir tous les fichiers que vous utilisez - vous ne connaissez peut être pas encore leurs noms - ne vous en faites pas, vous pourrez le mettre à jour plus tard. L'élément <folder>
peut être utilisé pour indiquer un dossier entier.
Laissez les positions ainsi - ce sont les positions standards, ainsi vous serez en mesure de basculer facilement d'un template standard à un autre.
Création d'une fichier index.php basique
Le fichier index.php
est le noyau de chaque page que Joomla! génère. Pour résumer, vous allez créer une page (comme pour toute page HTML) en plaçant du code PHP où le contenu de votre site doit s'intégrer. Le template fonctionne alors par l'ajout du code Joomla! dans des positions de modules et les sections des composants de votre template. Tous les éléments ajoutés au template apparaîtront sur toutes les pages à moins d'être déjà ajoutés à l'une de ces sections via le CMS Joomla! (ou un code personnalisé).
Cette page présente le code prêt à être copié/collé dans votre propre réalisation.
Début
Un template Joomla! commencera par les lignes suivantes :
<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
La première ligne est un moyen d’empêcher l'accès à votre code par des personnes mal intentionnées.
La seconde ligne est la Déclaration de type de document (DOCTYPE) qui indique aux navigateurs (et aux robots d'indexation) la version HTML de la page. Le doctype utilisé ci-dessus est HTML5, une nouvelle version d'HTML qui est largement compatible tout en contenant de nombreuses nouvelles fonctionnalités. Vous devez être conscient que ce type ne fonctionne pas bien avec Internet Explorer 8 ou ses versions antérieures sans des modifications substantielles de code. Vous devriez étudier cette situation avec vos clients avant d'opter pour un doctype précis. En tout état de cause, il est celui utilisé dans Joomla! .
La troisième ligne commence notre document HTML et indique la langue du site. Un document html est divisé en deux parties, l'entête et le corps. L'entête (head) contient les informations sur le document et le corps (body) va contenir le code du site qui contrôle la mise en page.
L'entête (head)
<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/system/css/general.css" type="text/css" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/css/template.css" type="text/css" />
</head>
La première ligne permet d'indiquer à Joomla! les informations à placer dans l'entête. Cela inclut le titre de la page, les méta-informations ainsi que les JavaScript.
Les autres lignes sont des liens vers deux systèmes de feuilles de style et vers votre propre feuille de style (si celle-ci est nommée template.css
et se situe dans le dossier css
du répertoire de votre template. Donc, si votre template est situé dans http://www.monsite.com/templates/mon_template/
alors les fichiers css iront dans http://www.monsite.com/templates/mon_template/css/
).
Le corps (body)
<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>
Étonnamment, cela est suffisant ! Et oui, c'est une mise en page très basique, mais qui permet de faire le travail. Tout le reste sera effectué par Joomla. Ces lignes, généralement appelées déclarations jdoc, indiquent à Joomla! d'inclure le rendu de certaines parties du système Joomla. Remarque : vous devrez vous assurer que votre menu est défini en position de module top.
Les positions de modules
Ci-dessus, la ligne indiquant name="top"
ajoute une position de module nommée top et permet à Joomla! de placer des modules dans cette section du template. La ligne type="component"
contient tous les articles et le contenu principal (en fait, le composant) et c'est très important. Il se positionne au centre du template.
Remarque : vous pouvez ajouter des lignes pour vos propres modules là où vous le souhaitez dans body, mais il vous faut ajouter une ligne correspondante dans le fichier templateDetails.xml qui se trouve au même endroit que le fichier index.php de votre template.
Fin
Pour terminer :
</html>
Images personnalisées
Si vous souhaitez ajouter des images dans le template, vous pouvez le faire ainsi :
<img src="<?php echo $this->baseurl; ?>/templates/<?php echo $this->template; ?>/images/myimage.png" alt="Custom image" class="customImage" />
Ici, la variable template permet de renseigner le nom de votre template.
CSS personnalisées
Vous pouvez ajouter des CSS personnalisées de cette façon :
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template;?>/css/styles.css" type="text/css" />
Chaque fichier ajouté doit avoir une ligne correspondante dans le fichier templateDetails.xml pour le template, à moins qu'il ne soit situé dans un sous-dossier (qui peut être inclus dans un élément <folder>).
Voici le fichier final :
<?php defined('_JEXEC') or die('Restricted access');?>
<!DOCTYPE html>
<html 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/<?php echo $this->template ?>/css/template.css" type="text/css" />
</head>
<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="footer" />
</body>
</html>
Tester le template
Localisez le template dans le gestionnaire de templates, sélectionnez-le et cliquez sur Défaut pour en faire le template par défaut.
Dans Joomla! 1.5, votre nouveau template apparaîtra immédiatement dans le Gestionnaire de templates, accessible via Extensions -> Gestion des templates.
+ Dans la série Joomla! 2.5 et suivantes, vous devez tout d'abord indiquer à Joomla! que vous avez créé un nouveau template. Cette fonctionnalité est nommée Découvrir les Extensions et vous pouvez la trouver dans Extensions -> Gestion des extensions -> Découvrir (onglet Découvrir). Cliquez sur Découvrir (c'est à dire le bouton Découvrir) pour trouver votre template, puis sélectionnez-le et cliquez sur Installer pour l'installer. Désormais, votre template devrait s'afficher dans le Gestionnaire des templates (Styles), accessible via Extensions -> Gestion des templates.
A noter que vous pouvez créer votre template en dehors de Joomla! et tout simplement l'installer comme n'importe quelle extension.
ASTUCE: Deux procédés permettent d'obtenir un aperçu de votre page d'index, soit en insérant les styles dans l'en-tête de la page d'index ou en la liant à la feuille de styles que vous allez utiliser temporairement. Vous pouvez supprimer ces liens avant d'empaqueter le fichier.
Empaqueter votre template pour l'installation
Un dossier avec plusieurs fichiers dispersés n'est pas une pratique recommandée pour la distribution d'extensions. L'étape finale est de créer un package (NDT : vous trouverez également les mots paquets ou packs). Il s'agit d'une archive compressée contenant la structure des répertoires et tous les fichiers. Le package peut être proposé dans un format ZIP (avec pour extension .zip), au format TAR-gzip (avec pour extension .tar.gz) ou encore au format TAR-bz2 (avec pour extension .tar.bz2).
Si votre template se trouve dans le répertoire mytemplate/, alors vous pouvez, pour créer le package, vous pouvez vous connecter à ce répertoire et utiliser des commandes telles que :
- tar cvvzf ../mytemplate.tar.gz *
- zip -r ..\mytemplate.zip *.*
Remarque aux utilisateurs de Mac OS X
Note aux développeurs de template utilisant le système Mac OS X : le menu "compresser" du menu Finder propose l'utilisation d'un format ZIP mais pour une opération. Il stocke les fichiers au format AppleDouble en ajoutant des fichiers avec des noms commençant par "._". Ainsi, un fichier nommé "._templateDetails.xml" est ajouté que Joomla! a parfois du mal à interpréter. Le résultat sera un message d'erreur "XML Parsing Error at 1:1. Error 4: Empty document". La solution de contournement consiste à compresser à partir de la ligne de commande et de définir une variable d'environnement shell "COPYFILE_DISABLE" avec la valeur "true" avant l'utilisation de "compresser" ou "tar". Pour plus d'informations, consultez l'article AppleDouble.
Pour définir une variable d'environnement sur un Mac, ouvrez une fenêtre de terminal et tapez :
export COPYFILE_DISABLE=true
Puis, dans la même fenêtre de terminal, modifier les répertoires vers l'emplacement de vos fichiers de template et terminée la commande zip. Par exemple, si vos fichiers template se trouvent dans un dossier de votre répertoire personnel myTemplate, il conviendra de faire comme suit :
cd myTemplate zip -r myTemplate.zip *
Conclusion
Vous devriez maintenant avoir créé un template qui fonctionne. Il ne ressemble pas encore à grand chose. La meilleure chose à faire maintenant est de commencer à expérimenter la mise en page.