J3.x

Ajouter du JavaScript et des CSS à une page

From Joomla! Documentation

This page is a translated version of the page J3.x:Adding JavaScript and CSS to the page and the translation is 49% complete.

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎中文(台灣)‎

This is one of a series of API Guides, which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

Insertion à partir d'un fichier

Joomla allows you to add Javascript and CSS files to your HTML document, and it puts the associated <script> and <link> elements within the HTML <head> section. To do this you call the addScript and addStyleSheet methods of the Joomla object which represents the HTML document. Since Joomla! buffers all the HTML-related data that makes up a page before output, it is possible to call these methods anywhere within your code.

Tout d'abord, obtenir une référence de l'objet du document en cours :

use Joomla\CMS\Factory;
$document = Factory::getDocument();
// above 2 lines are equivalent to the older form: $document = JFactory::getDocument();

Pour une feuille de style, utilisez ce code :

$document->addStyleSheet($url);

Pour ajouter un fichier JavaScript, utilisez ce code :

$document->addScript($url);

$url est la variable contenant le chemin complet vers le fichier JavaScript ou CSS. Par exemple : JUri::base() . 'templates/custom/js/sample.js'

Notez que ceci ne permet PAS pas l'intégration de 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.

$options and $attributes Parameters

You can add $options and $attributes parameters to the above methods. The $options control overall how the <script> and <link> elements are output while the $attributes get set as HTML attributes within those tags. (Note that although there are Deprecated markers against the addScript and addStyleSheet methods of the Joomla Document API, these markers refer just to the signature of these methods; the form of the signature using $options and $attributes parameters is not deprecated). The $options parameter should be an array, and 2 different options are currently supported:

  • 'version' => 'auto' If this is set then a "media version" is appended as a query parameter to the CSS or JS URL within the <script> or <link> element. This is a string (an md5 hash) which is generated from factors including the Joomla version, your Joomla instance secret and the date/time at which the media version was generated. The media version is regenerated whenever anything is installed on the Joomla instance, and its purpose is to force browsers to then reload the CSS and JS files instead of using possibly outdated versions from cache.

For example

$document->addStyleSheet("...demo.css", array('version'=>'auto'));
// leads to something like
// <link href="...demo.css?37e343bbb4073e0dfe5b1eb40b6" rel="stylesheet">

The string of characters after the ? is the md5 hash, which will change when extensions or Joomla itself are installed/upgraded/deinstalled.

  • 'conditional' => 'lt IE 9' (as an example). This outputs the <script> or <link> within a Conditional Comment which earlier versions of Internet Explorer interpreted.

For example

$document->addScript("...demo.js", array('conditional'=>'lt IE 9'));
// leads to
// <!--[if lt IE 9]><script src="...demo.js"></script><![endif]-->

The $attributes parameter should also be an array, and these are mapped to be html attributes of the <script> or <link> element. For example,

$document->addScript("...demo.js", array(), array('async'=>'async'));
// leads to
// <script src="...demo.js" async></script>

Ajouter des options à votre code JavaScript

Joomla! 
≥ 3.7
Disponible uniquement à partir de Joomla! 3.7

(Note that these Options are different from the $options parameter described above).

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);

Passing language strings to Javascript

There are cases when you may want to output an error message in your JavaScript code and want to use the Joomla mechanism of language strings. You could manage this by using addScriptOptions to pass down each language string you need, but Joomla provides a more succint solution. To pass a language string to JavaScript do in your PHP code, for example,

JText::script('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'); Then in your JavaScript code you can do:

var message = Joomla.JText._('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'); to obtain in the user's language the text message associated with the language constant. Obviously certain language strings have embedded %s characters, so in your JavaScript code you will have to handle that, eg using an external JavaScript sprintf library or string replace, 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 avec un Javascript

Par exemple, le code suivant est utilisé pour définir un outil personnalisé d'infobulles basé sur mootools.

For example, the following code is used to define a custom tool tip that takes advantage of 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

Cela est également utile si vous insérez un champ de formulaire en CSS dans votre code. Par exemple, vous voudrez peut-être demander à un utilisateur de choisir une couleur de contour. Appelez la valeur du champ de formulaire et assignez lui une variable $bordercolor dans mod_example.php. Puis, dans le tmpl/default.php, vous pouvez inclure les éléments suivants :

$document = JFactory::getDocument();
$document->addStyleSheet('mod_example/mod_example.css');
$style = '#example {
	border-color:#' . $bordercolor . ';
	}';
$document->addStyleDeclaration( $style );

Ici, mod_example.css contient le fichier CSS de tous les styles de base non-paramétrés. Puis, le paramètre bordercolor du champ de formulaire est ajouté séparément.

Ajouter des balises personnalisées

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.

Sample Module Code

Below is the code for a simple Joomla module which you can install and run to demonstrate adding CSS and JavaScript, and can adapt to experiment with the concepts above. If you are unsure about development and installing a Joomla module then following the tutorial at Creating a simple module will help. In a folder mod_css_js_demo create the following 4 files:

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);}); 
});

Zip up the mod_css_js_demo directory to create mod_css_js_demo.zip. Within your Joomla administrator go to Install Extensions and via the Upload Package File tab select this zip file to install this sample mod_css_js_demo module. Make this module visible by editing it (click on it within the Modules page) then:

  1. making its status Published
  2. selecting a position on the page for it to be shown
  3. on the menu assignment tab specify the pages it should appear on

When you visit a site web page then you should see the module in your selected position, and it should display

  • a message Hello World! which the CSS file should change to display in red
  • a button which when you click it will execute an alert() showing the language string and variable which were passed down from the PHP code.

Using your browser's development tools you can also view the <script> and <link> elements within the HTML and see the JavaScript output on the console.