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 100% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎中文(台灣)‎

Insertion à partir d'un fichier

Pour avoir un document HTML formaté correctement, vous devez mettre toutes les références aux fichiers JavaScript et CSS dans la partie du <head>. Puisque Joomla! génère tout le code HTML d'une page avant sa sortie, il est possible d'ajouter ces références au sein des balises <head> de votre page. La façon la plus simple de le faire est d'utiliser la fonctionnalité intégrée à Joomla.

JDocument

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

$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.

Ajouter des options à votre code JavaScript

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

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

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.

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.