Ajouter du JavaScript et des CSS à une page

Other languages:

Deutsch • ‎English • ‎español • ‎français • ‎中文（台灣）‎

Changement d'API

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

C'est une option beaucoup moins flexible. Cependant, elle est plus efficace pour un grand nombre de scénarios tels que notamment pour inclure une feuille de style dans un template. Bien sûr, vous aurez aussi besoin de coder manuellement certaines des étapes qui qui auraient été effectuées automatiquement avec l'utilisation de la méthode JHtml ci-dessous.

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

où $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).

JHtml

JHtml offre beaucoup plus de souplesse que JDocument, tout en utilisant les mêmes fonctionnalités de base - en effet, JHtml appelera JFactory::getDocument()->addStyleSheet() ou JFactory::getDocument()->addScript().

Si vous souhaitez simplement intégrer un chemin d'accès au fichier, dans un template par exemple, alors il est préférable d'utiliser JDocument. Cependant, si vous souhaitez prendre en compte l'activation du système de débogage afin d'inclure un un script de compression ou tirer profiter des scripts de substitution de templates et de feuilles de style, il sera préférable d'utiliser JHtml. Il est recommandé à tous les développeurs d'extensions tierces d'utiliser JHtml pour permettre aux développeurs de templates de proposer la substitution de templates ainsi que de leurs CSS et javascript.

JHtml::script

Ce qui suit est la signature de cette fonction. Vous pouvez en apprendre plus sur : JHtml::script sur api.joomla.org :

script(string $file, boolean $framework = false, boolean $relative = false, boolean $path_only = false, boolean $detect_browser = true, boolean $detect_debug = true) : mixed

Inclure un fichier javascript en utilisant JHtml peut présenter plusieurs avantages. La premier est dans le cas ou votre fichier javascript est dépendant de mootools. Dans ce cas, vous pouvez alors l'inclure automatiquement en paramétrant le second paramètre de la méthode sur 'true' comme ci-dessous :

<?php
JHtml::script(JUri::base() . 'templates/custom/js/sample.js', true);
?>

Le troisième paramètre de cette méthode autorise une plus grande personnalisation des extensions par la substition des fichiers javascript de templates. Le premier paramètre suppose que vous débutez par le dossier JPATH_BASE/media où vous indiquez le nom de votre extension, suivi par le nom de votre fichier javascript. Le chemin sera alors JPATH_BASE/media/com_search/js/search.js à la suite du snippet JHtml.

<?php
JHtml::script('com_search/search.js', false, true);
?>

Remarque : le sous-répertoire js recherché dans le répertoire com_search ne doit pas être spécifié dans la méthode JHtml.

Cependant si un fichier existe dans js/com_search/search.js, il sera inclus à la place. Imaginons par exemple qu'une extension utilise un fichier dépendant de mootools mais que l'utilisateur souhaite que seul le jQuery soit chargé. Cela signifie qu'un utilisateur pourra surcharger le fichier avec la version jQuery.

Par défaut, Joomla va inclure automatiquement une version compressée et non compressée des scripts selon que le mode de débogage est activé ou désactivé. Appelez votre script compressé search.min.js et la version non compressée script-uncompressed.js ou script.js pour utiliser cette fonctionnalité et pour améliorer le débogage des scripts. Vous devez appeler la fonction avec la version compressée, comme ceci :

<?php
JHtml::script('com_search/search.min.js');
?>

En outre, vous pouvez inclure des fichiers spécifiques de navigateurs. Joomla peut rechercher dans les types de fichiers suivants :

filename.ext
filename_browser.ext
filename_browser_major.ext
filename_browser_major_minor.ext

Cela peut vous permettre d'inclure internet des fichiers spécifiques pour internet explorer 6 par exemple. En ayant un search.js pour un usage général avec un search_msie_6.js pour corriger des éléments sur internet explorer 6.

JHtml::stylesheet

Ce qui suit est la signature de cette fonction. Vous pouvez en apprendre plus sur : JHtml::script sur api.joomla.org :

L'utilisation de JHtml pour inclure un fichier CSS peut présenter plusieurs avantages. Le premier est d'autoriser la surcharge des fichiers CSS pour permettre une plus grande personnalisation des extensions. Régler le troisième paramètre sur 'true' suppose que vous commencez par le dossier JPATH_BASE/media - où vous indiquez le nom de votre extension, suivi du nom de votre fichier CSS. Le chemin recherché sera alors JPATH_BASE/media/com_search/css/search.css pour l'élément JHtml.

<?php
JHtml::stylesheet('com_search/search.css', array(), true);
?>

Remarque : le sous-répertoire css recherché dans com_search ne doit pas être spécifié dans la méthode JHtml.

Cependant, s'il existe au dessus un fichier dans css/com_search/search.css, celui-ci sera inclus à la place. Cela permet aux utilisateurs de personnaliser l'apparence d'une extension pour mieux correspondre aux styles de leurs templates.

En outre, vous pouvez inclure des fichiers spécifiques de navigateurs. Joomla peut rechercher dans les types de fichiers suivants :

filename.ext
filename_browser.ext
filename_browser_major.ext
filename_browser_major_minor.ext

Cela peut vous permettre d'inclure internet des fichiers spécifiques pour internet explorer 6 par exemple. En ayant un search.js pour un usage général avec un search_msie_6.js pour corriger des éléments sur internet explorer 6.

De la même façon qu'avec JHtml::script, si $detect_debug est paramétré sur 'true' et que vous faite passer une feuille exemple.min.css alors, lorsque le mode de débogage est activé, la feuille de style, si elle existe, sera utilisé à la place.

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', array(), true);
$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);

J3.x