Ajouter du JavaScript et des CSS à une page
From Joomla! Documentation
Ce document fait partie d'une série de Guides API, dont l'objectif est de vous aider à comprendre comment utiliser les API de Joomla en fournissant des explications détaillées et des exemples de code que vous pouvez facilement installer et exécuter.
Insertion à partir d'un fichier
Joomla permet d'ajouter des fichiers Javascript et CSS à votre document HTML, et place les éléments <script> et <link> associés dans la section <head> du HTML. Pour ce faire, vous appelez les méthodes addScript et addStyleSheet de l'objet Joomla qui représente le document HTML. Puisque Joomla ! met en mémoire tampon toutes les données HTML qui composent une page avant la sortie, il est possible d'appeler ces méthodes n'importe où dans votre code.
Tout d'abord, obtenez une référence à l'objet document actuel :
use Joomla\CMS\Factory;
$document = Factory::getDocument();
// above 2 lines are equivalent to the older form: $document = JFactory::getDocument();Ensuite, pour une feuille de style, utilisez ce code :
$document->addStyleSheet($url);Pour ajouter un fichier JavaScript, utilisez ce code :
$document->addScript($url);où $url est la variable contenant le chemin d'accès complet au fichier JavaScript ou CSS. Par exemple :
JUri::base() . 'templates/custom/js/sample.js'
Notez que cela ne comprendra **PAS** Mootools ou jQuery. Si votre script nécessite Mootools ou jQuery,veuillez consulter Les frameworks JavaScript pour plus d'informations sur la façon de les intégrer (notez que jQuery peut être intégré nativement sur Joomla! 3.x). Il était possible de faire cela avec JHTML, cependant cette méthode a été dépréciée dans Joomla! 2.5 et supprimée dans Joomla! 3.x.
Paramètres $options et $attributs
Vous pouvez ajouter les paramètres $options et $attributes aux méthodes ci-dessus. $options contrôle globalement la manière dont les éléments <script> et <link> sont émis alors que les $attributes sont définis comme attributs HTML dans ces balises. (Notez que, bien qu'il existe des marqueurs d'obsolescence pour les méthodes addScript et addStyleSheet de l'API Joomla Document API, ces marqueurs se réfèrent uniquement à la signature de ces méthodes ; la forme de la signature utilisant la méthode ; la forme de la signature en utilisant les paramètres $options and $attributes ne sont pas dépréciés). Les paramètres $options définissent un tableau, et deux options différentes sont actuellement prises en charge :
- 'version' => 'auto' Si cette option est activée, une "version du média" est ajoutée comme paramètre de requête à l'URL CSS ou JS dans l'élément <script> ou <link>. Il s'agit d'une chaîne (un hachage md5) qui est générée à partir de facteurs comprenant la version de Joomla, votre secret d'instance Joomla et la date/heure à laquelle la version du média a été générée. La version média est régénérée chaque fois que quelque chose est installé sur l'instance Joomla, et son but est de forcer les navigateurs à recharger ensuite les fichiers CSS et JS au lieu d'utiliser les versions éventuellement périmées du cache.
Par exemple
$document->addStyleSheet("...demo.css", array('version'=>'auto'));
// leads to something like
// <link href="...demo.css?37e343bbb4073e0dfe5b1eb40b6" rel="stylesheet">La chaîne de caractères après le ? est le hachage md5, qui change lorsque des extensions ou Joomla lui-même sont installés/mises à niveau/désinstallés.
- 'conditional' => 'lt IE 9' (à titre d'exemple). Cela produit le <script> or <link> dans un commentaire conditionnel que les versions antérieures d'Internet Explorer interprétaient.
Par exemple
$document->addScript("...demo.js", array('conditional'=>'lt IE 9'));
// leads to
// <!--[if lt IE 9]><script src="...demo.js"></script><![endif]-->Le paramètre $attributes doit également être un tableau, et ceux-ci sont mappés pour être des attributs html de l'élément <script> our <link>. Par exemple
$document->addScript("...demo.js", array(), array('async'=>'async'));
// leads to
// <script src="...demo.js" async></script>Ajouter les options à votre code JavaScript
(Notez que ces options sont différentes du paramètre $options décrit ci-dessus).
A côté de l'ajout de scripts inline, Joomla! fournit un mécanisme pour sauvegarder les paramètres dans l'"optionsStorage". Ceci vous permet de gérer aisément les paramètres existant côté serveur et côté client. Ceci vous permet aussi de placer toute la ligique JavaScript dans le fichier JavaScript, qui sera mis en cache par le navigateur.
Joomla! utilise un mécanisme spécifique pour charger de manière paresseuse ("lazy loading") les paramètres côté client. Il n'utilise pas le JavaScript inline, qui est adapté pour la vitesse de rendu d'une page, et rend votre site plus amical pour les testeurs de temps de chargement (i.e. Google).
L'utilisation de "optionsStorage" et préférable au JavaScript inline pour ajouter les paramètres de script.
Exemple d'utilisation
Ajoutez les paramètres de script dans votre module :
$document = JFactory::getDocument();
$document->addScriptOptions('mod_example', array(
'colors' => array('selector' => 'body', 'color' => 'orange'),
'sliderOptions' => array('selector' => '.my-slider', 'timeout' => 300, 'fx' => 'fade')
));Accédez à vos options côté client :
var myOptions = Joomla.getOptions('mod_example');
console.log(myOptions.colors); // Print your options in the browser console.
console.log(myOptions.sliderOptions);Surchargez les paramètres du côté serveur. (Possible jusqu'au rendu de l'entête (head).) :
$document = JFactory::getDocument();
// Get existing options
$myOptions = $document->getScriptOptions('mod_example');
// Change the value
$myOptions['colors'] = array('selector' => 'body', 'color' => 'green');
// Set new options
$document->addScriptOptions('mod_example', $myOptions);Passer des chaînes de langue à Javascript
Dans certains cas, vous pouvez vouloir afficher un message d'erreur dans votre code JavaScript et utiliser le mécanisme de chaînes de langue de Joomla. Vous pourriez gérer cela en utilisant addScriptOptions pour transmettre chaque chaîne de langue dont vous avez besoin, mais Joomla offre une solution plus succincte. Pour passer une chaîne de langue à JavaScript, faites dans votre code PHP, par exemple,
JText::script('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'); Ensuite, dans votre code JavaScript, vous pouvez faire :
var message = Joomla.JText._('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'); pour obtenir dans la langue de l'utilisateur le message textuel associé à la constante de langue. Il est évident que certaines chaînes de langage contiennent des caractères %s intégrés. Dans votre code JavaScript, vous devrez donc gérer cela, par exemple en utilisant une bibliothèque JavaScript sprintf externe ou un remplacement de chaîne, etc.
Insertion de scripts inline dans un fichier PHP
Si vos codes Javascript ou CSS sont générés à l'aide de PHP, vous pouvez ajouter le script ou une feuille de style directement dans le head de votre document :
$document = JFactory::getDocument();
// Add Javascript
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
// Add styles
$style = 'body {'
. 'background: #00ff00;'
. 'color: rgb(0,0,255);'
. '}';
$document->addStyleDeclaration($style);Exemple JavaScript
Par exemple, le code suivant est utilisé pour définir une info-bulle personnalisée qui tire parti de Mootools.
function getToolTipJS($toolTipVarName, $toolTipClassName){
$javascript = 'window.addEvent(\"domready\", function(){' ."\n";
$javascript .= "\t" .'var $toolTipVarName = new Tips($$("' . $toolTipVarName .'"), {' ."\n";
$javascript .= "\t\t" .'className: "' .$toolTipClassName .'",' ."\n";
$javascript .= "\t\t" .'initialize: function(){' ."\n";
$javascript .= "\t\t\t" .'this.fx = new Fx.Style(this.toolTip, "opacity", {duration: 500, wait: false}).set(0);' ."\n";
$javascript .= "\t\t" .'},' ."\n";
$javascript .= "\t\t" .'onShow: function(toolTip){' ."\n";
$javascript .= "\t\t\t" .'this.fx.start(1);' ."\n";
$javascript .= "\t\t" .'},' ."\n";
$javascript .= "\t\t" .'onHide: function(toolTip) {' ."\n";
$javascript .= "\t\t\t" .'this.fx.start(0);' ."\n";
$javascript .= "\t\t" .'}' ."\n";
$javascript .= "\t" .'});' ."\n";
$javascript .= '});' ."\n\n";
return $javascript;
}
$document = JFactory::getDocument();
$document->addStyleSheet("/joomla/components/com_mycustomcomponent/css/mytooltip.css",'text/css',"screen");
$document->addScriptDeclaration(getToolTipJS("mytool","MyToolTip"));Notez que pour que ce JavaScript soir utile, il est nécessaire d'inclure le nom de la classe appropriée dans le code HTML, ainsi que de fournir le fichier mytooltip.css. Ceci n'est pas le sujet de cet article.
Exemples de CSS
Ceci est également utile si vous insérez un champ de formulaire CSS dans votre code. Par exemple, dans un module, vous pourriez vouloir que l'utilisateur choisisse la couleur de la bordure. Appelez la valeur du champ de formulaire et attribuez-lui une variable $bordercolor dans mod_example.php. Ensuite, dans tmpl/default.php, vous pouvez inclure ce qui suit :
$document = JFactory::getDocument();
$document->addStyleSheet('mod_example/mod_example.css');
$style = '#example {
border-color:#' . $bordercolor . ';
}';
$document->addStyleDeclaration( $style );Le fichier mod_example.css contient le fichier CSS de tous les styles non basés sur des paramètres. Ensuite, le paramètre bordercolor/champ de formulaire est ajouté séparément.
Ajouter un tag personnalisé
Il se présentera des occasions où même ces fonctions ne seront pas assez flexibles, car elles sont limitées à l'écriture du contenu des balises <script /> ou <style /> et qu'il est impossible d'ajouter des éléments en dehors de ces balises. Un exemple serait l'inclusion d'un lien de feuille de style avec des commentaires conditionnels, de sorte qu'il soient lus uniquement par Internet Explorer 6 ou plus ancien. Pour ce faire, vous devez utiliser $document->addCustomTag :
$stylelink = '<!--[if lte IE 6]>' ."\n";
$stylelink .= '<link rel="stylesheet" href="../css/IEonly.css" />' ."\n";
$stylelink .= '<![endif]-->' ."\n";
$document = JFactory::getDocument();
$document->addCustomTag($stylelink);S'il était nécessaire d'inclure d'autres CSS conditionnels, incluez toujours la méthode "addCustomTag" après sa déclaration.
Exemple de code de module
Vous trouverez ci-dessous le code d'un module Joomla simple que vous pouvez installer et exécuter pour démontrer l'ajout de CSS et de JavaScript, et que vous pouvez adapter pour expérimenter les concepts ci-dessus. Si vous n'êtes pas sûr du développement et de l'installation d'un module Joomla, vous pouvez suivre le tutoriel à l'adresse suivante : Création d'un module simple . Dans un dossier mod_css_js_demo, créez les 4 fichiers suivants :
mod_css_js_demo.xml
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
<name>css js demo</name>
<version>1.0.1</version>
<description>Code for including JS and CSS links</description>
<files>
<filename module="mod_css_js_demo">mod_css_js_demo.php</filename>
<filename>demo.css</filename>
<filename>demo.js</filename>
</files>
</extension>mod_css_js_demo.php
<?php
defined('_JEXEC') or die('Restricted Access');
use Joomla\CMS\Factory;
$document = Factory::getDocument();
$options = array("version" => "auto");
$attributes = array("defer" => "defer");
$document->addScript(JURI::root() . "modules/mod_css_js_demo/demo.js", $options, $attributes);
$document->addStyleSheet(JURI::root() . "modules/mod_css_js_demo/demo.css", $options);
$document->addScriptOptions('my_vars', array('id' => "css-js-demo-id2"));
JText::script('JLIB_HTML_EDIT_MENU_ITEM_ID');
echo '<h1 id="css-js-demo-id1">Hello World!</h3>';
echo '<button id="css-js-demo-id2">Click here!</button>';demo.css
#css-js-demo-id1 {
color: red;
}demo.js
jQuery(document).ready(function() {
const params = Joomla.getOptions('my_vars');
console.log(params);
console.log("JS language constant: " + Joomla.JText._('JLIB_HTML_EDIT_MENU_ITEM_ID'));
var message = Joomla.JText._('JLIB_HTML_EDIT_MENU_ITEM_ID');
message = message.replace("%s", params.id);
document.getElementById(params.id).addEventListener("click", function() {alert(message);});
});Compressez le répertoire mod_css_js_demo pour créer mod_css_js_demo.zip. Dans l'administration de votre site Joomla, allez dans Installer des extensions et via l'onglet Télécharger un fichier d'archive, sélectionnez ce fichier zip pour installer cet exemple de module mod_css_js_demo. Rendez ce module visible en le modifiant (cliquez dessus dans la page Modules) puis :
- rendre son statut publié
- sélectionner une position sur la page pour qu'il soit affiché
- Dans l'onglet "Affectation des menus", indiquez les pages sur lesquelles il doit apparaître.
Lorsque vous visitez la page web d'un site, vous devriez voir le module à la position sélectionnée, et il devrait afficher
- un message Hello World ! que le fichier CSS doit modifier pour l'afficher en rouge
- un bouton qui, lorsque vous cliquez dessus, exécute une commande alert() montrant la chaîne de langue et la variable qui ont été transmises par le code PHP.
En utilisant les outils de développement de votre navigateur, vous pouvez également visualiser les éléments <script> et <link> dans le code HTML et voir la sortie JavaScript sur la console.