Migration d'un template de Joomla! 1.5 vers 3.x
From Joomla! Documentation
Lorsque vous envisagez une mise à niveau manuelle d'un template 1.5, plusieurs éléments sont à prendre en considération.
Tout d'abord, quelles sont les compétences nécessaires ? Pour apporter des modifications à un template, vous devez maitriser, au minimum, les bases de PHP, HTML, XML, CSS et si possible un peu de Javascript. Si vous ne possédez pas les connaissances de base en ces domaines, une grande partie de ce que vous allez chercher à accomplir va vous sembler incompréhensible, par conséquent il vous faut soit améliorer vos connaissances soit faire appel à un professionnel.
Deuxièmement, dans la mesure où votre template doit être modifié, déterminez les changements en matière de design et les améliorations souhaitées lors de la planification de la migration. Est-ce que vos modifications tireront profit du nouveau framework Bootstrap disponible dans Joomla! 3 ? Ou est-ce que vous souhaitez une copie conforme de l'actuel site. Alors que certains des changements obligatoires constituent des nouveautés Joomla! (ce qui signifie que votre template ne sera pas chargé), d'autres sont des améliorations et votre template se chargera mais risque de ne pas s'afficher comme vous le souhaiteriez.
Dans ce document, nous présenterons l'exemple le plus simple et suggérerons une version miroir du template 1.5 actuel. Pour des templates plus complexes ou des améliorations majeures, vous devriez peut-être faire un peu de recherche ou embaucher quelqu'un ayant plus d'expérience en matière de templates.
Examen des notions de base sur les templates
Certaines choses n'ont pas changé. Maîtriser les notions de base d'un template Joomla! reste nécessaire : la structure du dossier répertoire est un de ces éléments. A la racine, vous avez besoin au minimum des deux fichiers : index.php et templateDetails.xml (attention à la casse !). La plupart des templates possède au moins deux dossiers : un dossier images pour contenir tous les éléments graphiques utilisés par votre template et un dossier pour vos styles CSS. Des templates plus avancés peuvent contenir des dossiers nommés par exemple : html pour la personnalisation des composants et modules, un dossier language pour les substitutions de langue, javascript pour les routines javascript personnalisées.
Assurez-vous que si le dossier est listé dans le fichier XML, celui-ci existe bien dans le template que vous chargez sur Joomla. Si vous déclarez un fichier dans le xml alors il doit exister ou votre template ne se chargera pas.
Un exemple d'amélioration dans les versions supérieures à 1.5 est l'abandon de l'exigence que tous les noms de fichiers des sous-dossiers soient listés. Pour les templates Joomla! 3, vous listez tout simplement le nom du dossier.
Pour plus d'informations sur les bases d'un template, consultez ce lien: Créer un template Joomla! basique
Modifications du fichier XML
Les modifications à apporter au fichier templateDetails.xml (Fichier de manifeste du template)
Le fichier de manifeste du template fournit les informations dont Joomla! a besoin pour installer votre template. Le fichier manifeste XML a été presque complètement modifié depuis la version 1.5 alors assurez-vous de bien étudier et vous familiariser avec les bases et les modifications. Votre template ne chargera pas si ce fichier n'est pas exact.
Type de balise du document référence & balise Install/Extension
La balise d'installation XML est désormais une balise “extension”. En outre, toute référence dans la balise DOCTYPE ou numéros de version doit se référer à la version 3.0.
Les anciennes lignes ressemblaient à quelque chose comme ceci :
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://dev.joomla.org/xml/1.5/template-install.dtd">
<install version="1.5" type="template">Cela ressemble désormais à cela :
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">
<extension version="3.1" type="template" client="site">Balises de dossier et fichier
Cette règle a toujours été et reste d'actualité : si vous répertoriez le Filename (nom du fichier) ou Folder (dossier) dans le XML, il doit exister dans le template chargé. Cela n'a pas changé dans Joomla! 3. Ce qui a changé est que la version 1.5 exigeait que tous les noms de fichier d'un dossier soient répertoriés. Désormais, vous pouvez faire référence uniquement au nom du dossier. Par exemple, précédemment dans la version 1.5, vos noms de fichiers xml étaient répertoriés individuellement comme suit :
<images>
<filename>images/arrow.png</filename>
<filename>images/arrow2.png</filename>
<filename>images/arrow3.png</filename>
<filename>images/author.gif</filename>
</images>Pour un template Joomla! 3, cette déclaration suffit :
<folder>images</folder>Balises de module
Dans la version 1.5, les positions de modules étaient définies dans le template. Cela n'a pas changé. Elles ont toujours besoin d'être listées.
Paramètres
Les paramètres sont une fonction optionnelle des templates qui permettent à l'auteur du template d'offrir des options pour styliser le template depuis l'administration de Joomla. Dans les templates pour Joomla! 1.5, les paramètres étaient répertoriés dans le fichier "parameters.ini" à la racine. Ce fichier a été supprimé et les paramètres sont désormais contenus dans le fichier XML.
Voici un exemple du contenu d'un fichier parameters.ini :
colorVariation=blue
backgroundVariation=blueAfin de définir les paramètres dans Joomla! 3, il vous faut ajouter ces lignes au fichier XML :
<config>
<fields name="params">
<fieldset name="advanced">
<field name="colorVariation" class="" type="color" default="#08C"
label="TPL PROTOSTAR COLOR LABEL"
description="TPL PROTOSTAR COLOR DESC" />
<field name="backgroundVariation" class="" type="color" default="#F4F6F7"
label="TPL PROTOSTAR BACKGROUND COLOR LABEL"
description="TPL PROTOSTAR BACKGROUND COLOR DESC" />
</fieldset>
</fields>
</config>Pour des paramètres plus complexes de balises XML, vous pouvez vous référer à une documentation plus complexe. Notez également que le fichier index.php, qui fait référence aux variables de paramètres, devra également être modifié.
Consultez ces liens pour plus d'informations sur :
Fichier index.php
Que faut-il modifier dans le fichier index.php ?
Les fichiers index.php sont aussi variés que les concepteurs et programmeurs qui les ont écrits. L'index.php d'un template pour Joomla! 3 est la compilation des nombreuses versions qui l'ont précédé, dont 1.5, 1.6, 1.7,2.5, etc. Ce fichier de template est un peu comme le "système sanguin" apportant la vie à votre peau, et il a accès à chaque pièce disponible du framework Joomla! et peut utiliser ces pièces pour manipuler l'apparence qu'aura votre site pour vos utilisateurs. Ceci a toujours été le cas et le reste. Les concepteurs et programmeurs de template ont tiré profit de ce fait dans les versions précédentes et continueront ; de ce fait, ce fichier a besoin d'une recherche et d'une planification attentives.
Les modifications apportées au framework pour Joomla! 3 peuvent provoquer des problèmes avec certains templates plus anciens et le rendu peut produire des erreurs. D'autres templates peuvent ne pas se référer du tout à la même partie du framework et fonctionner parfaitement avec peu de changement. Par exemple, un template 1.5 qui accède à la valeur de la variable "frontpage" pour déterminer s'ils sont ou non sur la page d'accueil. Cela ne fonctionne pas avec Joomla! 3. (Voir tableau ci-dessous pour le code) Si un template fait référence ou non à une modification d'élément, cela constituera le facteur déterminant du nombre d'erreurs que vous rencontrerez lorsque vous essayerez d'implémenter votre template mis à jour.
Soyez prêt à réaliser quelques changements en suivant les "meilleures pratiques". Bien que votre index.php peut tout à fait fonctionner, il a besoin d'être sécurisé et de s'exécuter correctement. Considérez que toutes les pages produites et visibles utilisent le fichier index.php de manière à vous assurer d'utiliser les méthodes recommandées pour le framework Joomla! et la construction de blocs de templates. Une étude approfondie des fichiers index.php, présents dans le template Protostar ou le template Beez qui sont inclus avec le pack d'installation Joomla! 3, peut fournir des exemples et bonnes pratiques pour des templates plus complexes.
Lignes directrices
Voici quelques lignes directrices pour le fichier index.php de votre template pour Joomla! 3 :
1. Encore une fois, certaines choses n'ont pas changées : tous les index.php des templates doivent commencer par cette déclaration :
<?php defined( '_JEXEC' ) or die;?>C'était vrai pour Joomla! 1.5 et cela le reste pour Joomla! 3.
2. Pour Joomla! 3, le DOCTYPE recommandé (déclaration de type de document) doit être HTML5, celui-ci étant utilisé sur tout Joomla! 3. Voici un exemple :
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">3. Pour utiliser le framework Joomla! 3 :
Dans 1.5, l'accès au framework se faisait par la variable $mainframe. Quelque chose comme ceci :
<?php require_once (‘includes/../framework.php' );
$mainframe =& JFactory::getApplication('site'); ?>- remplacez-le par ceci :
<?php $app = Jfactory::getApplication();?>4. Pour récupérer le code d'en-tête, il suffit d'utiliser cette instruction, directement en dessous de votre balise d'en-tête et de le faire suivre de vos feuilles de style. Cela n'a pas changé avec Joomla! 3, cependant, il est toujours bon de le répéter:
<jdoc:include type="head" />5. Pour récupérer le nom du site dans la version 1.5, vous deviez voir ceci :
<?php echo $mainframe->getCfg('sitename');?>Pour Joomla! 3, utilisez ce code :
<?php $app->getCfg('sitename');?>6. Codes d'erreurs et messages :
Une meilleure méthodologie pour la récupération des codes d'erreur a été mise en place pour Joomla! 3. Lorsque vous voyez dans votre template 1.5 ceci :
<?php $this->error->code; ?>- remplacez-le par la convention pour Joomla! 3 :
<?php $this->error->getCode(); ?>Pour les messages d'erreur, ceci est une déclaration standard pour 1.5 :
<?php $this->error->message; ?>- remplacez-le par la convention pour Joomla! 3 :
<?php $this->error->getMessage(); ?>7. Pour accéder aux paramètres du template et afin de remplacer le code qui ressemble à ceci :
<?php $color = $this->params->get('colorVariation'); ?>- il est recommandé d'utiliser cette méthodologie :
<?php $app = Jfactory::getApplication();
$template = $app->getTemplate(true);
$params = $template->params;
$color = $params->get('colorVariation'); ?>Ceci fonctionne tout aussi bien que, par exemple :
<?php $app = Jfactory::getApplication();
$params = $app->getParams();
$color = $params->get('colorVariation'); ?>8. L'accès aux classes Global Document Object dans le fichier template index.php est généralement codé de cette façon :
<?php $doc = Jfactory::getDocument(); ?>Cette déclaration est identique dans Joomla! 3. Cependant, il est important de noter que cette déclaration n'est pas nécessaire pour accéder aux pages des classes qui dépendent ou non du programmeur originel. Par exemple, ce code :
<?php $doc =& JFactory::getDocument();
echo 'Current title is: ' . $doc->getTitle(); ?>est l'équivalent de ce code :
<?php echo 'Current title is: ' . $this->getTitle(); ?>
En résumé
Le tableau ci-dessous est un guide de référence rapide présentant les différences entre les codes pour les templates pour Joomla! 1.5 et ceux pour Joomla! 3.x dans le fichier index.php.
| Description | Pour un template 1.5 (index.php) vous trouverez | Code recommandé pour un template J3.x (index.php) |
|---|---|---|
| Première ligne | <?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
|
Aucun changement |
| DOCTYPE | <?php echo '<?xml version="1.0" encoding="utf-8"?'.'>'; ?><!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; ?>" dir="<?php echo $this->direction; ?>" > |
<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>"> |
| Accès au framework Joomla! | $app = JFactory::getApplication(); OR
require_once (‘includes/../framework.php' );
$mainframe =& JFactory::getApplication('site');
|
Aucun changement mais doit ressembler à ceci :
$app = JFactory::getApplication(); |
Récupérer les en-têtes HTML de Joomla! |
<jdoc:include type="head" /> |
Aucun changement |
Récupérer le nom du site |
$mainframe->getCfg('sitename');
|
$app->get('sitename');
|
| Récupérer les codes d'erreur | $this->error->code |
$this->error->getCode(); |
| Récupération des messages d'erreur | $this->error->message |
$this->error->getMessage(); |
| Récupération des messages système | $this->getBuffer('message')
|
<jdoc:include type="message" /> |
| Langue active | $this->language; |
$doc->language; |
| Vue | JRequest::getVar( 'view' ) |
$app->input->getCmd('view');
|
| Tâche | JRequest::getVar( 'task' ) |
$app->input->getCmd('task');
|
| Mise en page | JRequest::getVar( 'layout' ) |
$app->input->getString('layout', 'default');
|
| ID | JRequest::getVar( 'id' ) |
Avec l'alias :$app->input->getString('id');
Uniquement l'ID :$app->input->getInt('id');
|
| Détection de la page d'accueil | <?php if(JRequest::getVar( 'view' ) == 'frontpage') ?> |
<?php $menu = $app->getMenu(); if($menu->getActive() == $menu->getDefault()) ?> |
| Contenu principal | <jdoc:include type="component" /> |
Aucun changement |
| Modules et positions | <jdoc:include type="modules" name="right" style="xhtml" /> |
Aucun changement |
| Récupération de l'URL de Base | $url = clone(JURI::getInstance()); echo $this->baseurl; JURI::root()*; |
JURI::base(); $this->baseurl; |
| Accès aux classes des pages de documents | $doc = JFactory::getDocument(); |
Aucun changement
Cependant, l'utilisation de "$this->" est équivalente. |
| Accès aux paramètres du template | echo $this->params->get('colorVariation');
|
Aucun changement |
Les styles Bootstrap et Joomla! 3
Pour intégrer les nouveaux styles Bootstrap ( 2.3.2 ) dans votre template mis à jour, vous devez ajouter ces trois lignes tout en haut de votre index.php en remplacement du bloc de ligne php.
<?php defined( '_JEXEC' ) or die;
JHtml::_('bootstrap.framework');
JHtml::_('bootstrap.loadCss', true, $this->direction); ?>Après ces déclarations, vous pouvez ajouter les classes Bootstrap (2.3.2 ) à chaque fois que vous en avez besoin et ainsi profiter dans Joomla! 3 des avantages offerts par le framework Bootstrap.
Piqure de rappel...
Il existe différentes pratiques de codage et la réussite de la transformation de votre template 1.5 en un template convenant pour Joomla! 3 dépend de la complexité entre l'ancien et le nouveau design et du code d'origine. Votre template peut avoir été préalablement converti depuis Joomla 1.0 ! Votre meilleure stratégie est de rechercher la documentation disponible et vous familiariser avec les templates de Joomla! 3, Protostar et Beez. Les techniques de codage et la structuration de ces deux templates ont été examinés avec attention par la communauté et les développeurs bénévoles de Joomla, - de véritables experts sur la façon de rendre votre template le plus sur et le plus fiable possible.