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

Outdated translations are marked like this.
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 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! provides a mechanism to store the options in the "optionsStorage". This allows you to nicely manage existing options on the server side and on the client side. It also allows you to place all JavaScript logic into the JavaScript file, which will be cached by browser.

Joomla! uses a special mechanism for "lazy loading" the options on the client side. It doesn't use inline JavaScript, which is good for page rendering speed, and makes your site more friendly to the Speed Testers (eg Google).

The use of "optionsStorage" is preferred over inline JavaScript for adding 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 your options on the client side:

var myOptions = Joomla.getOptions('mod_example');
console.log(myOptions.colors); // Print your options in the browser console.
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 it is declared.