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

Other languages:
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 extension. 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

Beside adding inline scripts, Joomla! provide mechanism to store the options in the "optionsStorage". This is allowed to nicely manage an existing options on the server side and on the client side. And allow to place all JavaScript logic to the JavaScript file, that will be cached by browser.

Joomla! use special mechanism for "lazy loading" the options on the client side. It do not use inline JavaScript, that is good for page rendering speed, and make your site more friendly for the Speed Tester (eg Google).

Thus use "optionsStorage" preferred, than use inline JavaScript to add the script options.

Example of use

Add the script options to your module:

$document = JFactory::getDocument();
$document->addScriptOptions('mod_example', array(
    'colors' => array('selector' => 'body', 'color' => 'orange'),
    'sliderOptions' => array('selector' => '.my-slider', 'timeout' => 300, 'fx' => 'fade')
));

Access to your options on the client side:

var myOptions = Joomla.getOptions('mod_example');
console.log(myOptions.colors); // Print in the browser console your options
console.log(myOptions.sliderOptions);

Override the options on server side (possible until the head rendering):

$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 fonctionne correctement, il serait 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, dans un module, vous voudrez peut-être demander à un utilisateur de choisir une couleur de contour. Après l'appel des valeurs des champs de formulaires et l'affectation d'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);

If it was necessary to include other conditional CSS, always include the "addCustomTag" method after declare it.