Written by How do you comfort a JavaScript bug ? You console it.
Comment réconforter un bug JavaScript ? On le console.
How do you comfort a JavaScript bug ? You console it.
Comment réconforter un bug JavaScript ? On le console.
Environnement de travail
Avant de parler de JavaScript, il est nécessaire d’adapter son environnement de développement à ce langage.
Sur Firefox, l’outil de debug de base est Firebug. La console (d’où la vanne) permet de détecter immédiatement les erreurs JS.
Il existe de nombreux tutos sur Firebug. Notamment celui d’Alsacréations, qui aborde les 3 fonctions principales de l’outil, inspection HTML, déboggage CSS et déboggage JavaScript.
Il existe aussi une version pour Chrome.
L’autre extension indispensable sur Firefox est Phoenix. A l’aide de cet outil, on peut voir d’un seul coup d’oeil tous les fichiers JS et CSS chargés sur une page.
Introduction
Le CMS Joomla utilise une variété de scripts JS, pour l’essentiel basés sur la librairie jQuery.
Cette dernière a progressivement remplacé la librairie Mootools, qui a complètement disparu du Frontend, mais qui est maintenue pour certaines fonctionnalités en Backend.
Le « framework » Bootstrap a été rajouté récemment pour faciliter la mise en place d’éléments de design « ready-made » comme les grids, les boutons, les images, les formulaires, etc … Bootstrap comporte une partis JS (liée à jQuery) et une partie CSS.
Mon but dans cet article est de présenter les différentes manières d’inclure les fichiers JS dans Joomla en commençant par les méthodes existantes.
JavaScript et CSS marchant de pair, j’aborderai aussi l’inclusion des fichiers CSS dans Joomla.
Vous pouvez aussi vous référer à ces articles de la documentation Joomla (en français) :
Ajouter du JavaScript – Joomla! Documentation
Frameworks JavaScript – Joomla! Documentation
Ajouter du JavaScript et des CSS à une page – Joomla! Documentation
Les bases
En général, l’utilisateur de Joomla! commence à se préoccuper de JS quand :
il y a un bug. Mon [enregistrement, slideshow, menu, etc, barrez les mentions inutiles] ne fonctionne pas
il veut intégrer son propre script super sympa qu’il a trouvé sur le web
Débogguer et adapter des scripts JS peut être compliqué si l’on ne comprend pas bien les bases de l’inclusion du JS dans Joomla.
Le JavaScript dans les templates
Le premier contact d’un utilisateur Joomla avec le JS et les CSS passe par les templates. Le template Protostar, qui est compris dans le package par défaut d’une installation Joomal native, est une excellente démo pour faire les premiers pas.
JS
Dans l’index.php, localisé ici /templates/protostar/index.php, ligne ± 39
JHtml::_(‘bootstrap.framework’);
Cette ligne intègre toutes les dépendances dont on a besoin en chargeant Jquery + Bootstrap. Elle assure aussi que jQuery n’est chargé qu’une seule fois
Ligne ± 13
$doc = JFactory::getDocument();
Cette ligne est nécessaire pour charger les fichiers JS et CSS additionnels.
Ligne ± 40
$doc->addScript($this->baseurl . ‘/templates/’ . $this->template . ‘/js/template.js’);
Cette ligne utilise l’API Joomla pour charger un fichier JS localisé dans /templates/protostar/js/
CSS
Ligne ± 43
$doc->addStyleSheet($this->baseurl . ‘/templates/’ . $this->template . ‘/css/template.css’);
$doc->addStyleSheet($this->baseurl . ‘/templates/’ . $this->template . ‘/css/custom.css’);
Ces lignes utilisent l’API Joomla pour charger un fichier template.css et un fichier custom.css localisés dans /templates/protostar/css/.
J’ai rajouté un fichier custom.css qui n’existe pas par défaut dans l’index.php du template Protostar pour montrer à quel endroit on peut inclure des fichiers CSS personnalisés.
En résumé, la bonne méthode pour l’inclusion de fichiers JS et CSS :
$doc = JFactory::getDocument();
$doc->addScript($this->baseurl . ‘/templates/’ . $this->template . ‘/js/template.js’);
$doc->addStyleSheet($this->baseurl . ‘/templates/’ . $this->template . ‘/css/template.css’);
Important
On peut toujours rajouter un fichier JS ou CSS via les méthodes classiques, dans la balise « head » :
Mais l’ordre dans lequel se chargent ces fichiers, JS ou CSS, est très important.
Joomla doit exécuter les fichiers jQuery AVANT tout script dépendant.
Les lois de l’HTML et donc des CSS, veulent que le dernier fichier CSS chargé prend la précédente sur tous les autres.
Les développeurs de Joomla ont pris en compte ces principes et conçu l’inclusion des fichiers JS et CSS en conséquence.
Il est donc fortement recommandé d’adopter ces méthodes.
NB : les templates des développeurs de templates réputés (RocketTheme, Joomlart, Yootheme, JoomlaShine, Gavick, etc …) prennent souvent des libertés avec cette méthode et chacun a sa manière de traiter le chargement des fichiers JS et CSS. On en parlera aussi dans un autre article.
Par ailleurs, ajouter un fichier JS ou CSS dans l’index.php du template alors qui lui ne ciblera qu’un module ou un composant est très contre-productif car le-dit fichier sera chargé sur toutes les pages, par définition. On va donc voir des alternatives à cette méthode.
Le JavaScript dans les extensions
Nous savons qu’il faut éviter de modifier les fichiers natifs, et ceux des extensions tierces, à cause des mises à jour régulières de Joomla, des templates et des extensions. Nous avons donc à notre disposition les surcharges de templates, composants, modules.
Je pars du principes que les méthodes de surcharges sont acquises (sinon voir cet article).
1 – La méthode classique
On peut toujours ajouter les fichiers JS ou CSS de la manière suivante, en respectant les chemins/paths vers ces fichiers, que je placerai dans les dossiers « css » et « js » pour des raisons de cohérence.
Prenons la surcharge d’un module « custom », dans default.php, localisé ici :
/templates/protostar/html/mod_custom/default.php
Insertion des fichiers :
defined(‘_JEXEC’) or die;
//insertion
$doc = JFactory::getDocument();
$doc->addStyleSheet(JURI::root().’templates/protostar/css/mod_custom.css’);
$doc->addScript(JURI::root().’templates/protostar/js/mod_custom.js’);
Même méthode pour les composants, dont le com_content, qui gère l’affichage des articles, catégories, page d’accueil.
Idem pour les plugins.
Dans cette configuration, on évite le chargement superflu et générateur de requêtes inutiles en ciblant l’extension et seulement elle.
Je mettrai un bémol sur les plugins, surchargeables, mais qui la plupart du temps, propagent tous les fichiers JS et CSS partout, sans possibilité de contrôle.
2 – La méthode qui tue
Depuis la version 3.xx de Joomla, j’avais été très intéressée par cet article de Michael Babker, « Use the media Folder, Allow Overridable Media », qui présentait une nouvelle approche de l’insertion de fichiers JS et CSS, et des images liées, cette fois-ci, dans le dossier « media ».
On crée un dossier « mes_styles » dans le dossier « media ».
Dans le dossier « mes_styles », on crée un dossier « css », un dossier « images », un dossier « js ».
NB : le respect des minuscules est important pour le nommage de ces fichiers.
On place les fichiers JS, CSS, et les images dans leurs dossiers respectifs. Et là, bingo, plus besoin de se préoccuper des chemins/paths des fichiers, il suffit de rajouter dans notre surcharge du fichier default.php, dans mod_custom, localisé ici : /templates/protostar/html/mod_custom/default.php,
defined(‘_JEXEC’) or die;
JHtml::_(‘stylesheet’, ‘mes_styles/macss1.css’, false, true);
JHtml::_(‘script’, ‘mes_styles/monjs1.js’, false, true);
L’API Joomla ira alors chercher les fichiers à cet endroit, cad le dossier « media/mes_styles ». Cette méthode fonctionne pour les surcharges de composants également. Elle fonctionne aussi dans les modules et les composants eux-mêmes. C’est celle utilisée aujourd’hui par la plupart des développeurs d’extensions.
IMPORTANT
Il est toujours nécessaire de vérifier l’ordre de chargement des fichiers via le code source visible lors de l’affichage de la page.
Un exemple classique : le fichier JS est chargé (et exécuté) avant les fichiers jQuery. C’est un problème si ce fichier est dépendant de jQuery.
On force alors le chargement de jQuery avec :
JHtml::_(‘jquery.framework’);
Qui charge tous les fichiers jQuery nécessaires. On aura donc :
defined(‘_JEXEC’) or die;
JHtml::_(‘jquery.framework’);
JHtml::_(‘stylesheet’, ‘mes_styles/macss1.css’, false, true);
JHtml::_(‘script’, ‘mes_styles/monjs1.js’, false, true);
L’objectif de cet article est de montrer que l’on peut rajouter des fichiers JS et CSS facilement et en évitant au maximum les problèmes de conflits, de fichiers mal placés, et ceux liés aux mises à jour de Joomla, des templates et des extensions.
J’aborderai dans un autre article les cas spécifiques des templates « frameworkés » comme ceux de Warp-Yootheme, Gantry-RocketTheme, Helix-Joomshaper ou PurityIII-Joomlart.
Enjoy !