Ajouter du JavaScript
From Joomla! Documentation
Note that a more up-to-date Joomla document covering this topic can be found at Adding JavaScript and CSS to the page, although it currently doesn't cover the more advanced topics at the bottom of this page.
Le JavaScript (également connu comme ECMAScript) est un langage de scripts principalement utilisé côté client et développé afin d'étendre et d'améliorer l'expérience utilisateur. Joomla! propose aux développeurs des mécanismes faciles à utiliser pour inclure du JavaScript dans leurs extensions en utilisant les méthodes API. Il existe différentes méthodes pour intégrer du JavaScript dans vos extensions Joomla! et certaines vont être présentées ci-dessous.
Utilisation
Il existe trois méthodes pour l'intégration de JavaScript dans votre code à l'aide de l'API Joomla : JDocument::addScriptDeclaration, JDocument::addScript et script. Ces méthodes doivent être appelées soit dans votre classe View de composant <yourcomponent>/views/<yourview>/view.html.php ou par un script de template <yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php ou dans le cas d'un module, dans son script de template <yourmodule>/tmpl/<yourtemplate>.php.
JavaScript en ligne
Les blocs de code JavaScript peuvent être déclarés directement dans la vue de template pour un composant ou un module par l'utilisation des classes : JDocument de la méthode addScriptDeclaration :
<?php
$document = JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>JavaScript externe
Comme alternative, vous pouvez séparer votre code JavaScript en le plaçant dans un fichier séparé. Séparer votre code JavaScript dans un fichier externe peut rendre le code de votre template plus facile à lire surtout si le JavaScript est longue et complexe.
Il existe deux façons d'inclure un fichier JavaScript à l'aide de l'API Joomla. La première consiste à utiliser la classe JDocument de la méthode addScript :
<?php
$document = JFactory::getDocument();
$document->addScript('/media/system/js/sample.js');
?>La seconde utilise la classe JHTML de la méthode script :
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>L'API a changé dans 3.x, de sorte que le deuxième paramètre ne peut pas être une chaîne de caractères. Si vous avez vraiment besoin d'utiliser cette méthode, vous devez inclure le lien absolut vers votre fichier JavaScript :
<?php
JHtml::script(Juri::base() . 'templates/custom/js/sample.js');
?>You can use options in a third parameter. This example shows the options version and relative . The file example should be saved in the folder media/com_example/js/example.min.js. So you do NOT need to insert the js in the path you insert as second parameter.
<?php
JHtml::_('script', 'com_example/example.min.js', array('version' => 'auto', 'relative' => true));
?>Description
Les méthodes des API Joomla! JDocument::addScriptDeclaration, JDocument::addScript et script permettent d'intégrer du JavaScript dans le fichier Joomla! index.php via la balise d'en-tête :
<jdoc:include type="head"/>Utiliser les méthodes JDocument::addScript ou script pour implémenter JavaScript dans le fichier index.php donnera le code HTML suivant :
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>L'appel de la méthode de la classe JDocument::addScriptDeclaration générera le code HTML suivant :
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>L'utilisation de ces méthodes est fortement recommandée car elle différencie clairement un autre langage de script (JavaScript) d'avec le langage principal PHP, ce qui garantit que tous les JavaScript seront correctement intégrés entre les balises <head></head>. Dans le de JDocument::addScript et JHTML::script, cela permettra de s'assurer qu'un fichier JavaScript ne sera intégré qu'une seule fois (il n'y aura pas de fichiers .js doublons).
À l'aide d'un Framework JavaScript
Un framework Javascript fournit aux développeurs une fonctionnalité générique pour le traitement des différentes tâches de codage dans un cadre familier, cohérent et indépendant de la plateforme. Un framework permet au développeur d'oublier les subtilités de la mise en œuvre d'une fonction spécifique pour différents navigateurs web et ainsi de rester concentrés sur les exigences du logiciel.
Deux Frameworks JavaScript sont disponibles dans Joomla! 3.x à savoir jQuery et Mootools. jQuery est un framework nouvellement introduit dans le cadre de l'intégration du nouveau framework HTML Bootstrap. Mootools est une bibliothèque JavaScript héritée qui est désormais remplacée par jQuery et uniquement intégrée pour des questions de rétro-compatibilité avec les extensions tierces.
Dans presque tous les cas vous devriez utiliser un framework lorsque vous travailler avec JavaScript dans le cadre du développement de vos extensions ou templates et leur intégration est très simple à mettre en oeuvre avec les API Joomla.
Joomla! 3.x et jQuery
Pour plus d'informations sur la façon d'intégrer un framework dans Joomla! 3.x, veuillez consulter le guide sur les Frameworks JavaScript dans Joomla 3.x.
Joomla! 1.5/2.5 et Mootools
Sauf si vous devez assurer la maintenance d'un code JavaScript utilisant Mootools ou si vous développez une extension pour des versions 2.5 ou antérieures de Joomla, il est recommandé d'utiliser jQuery à la place.
Tout d'abord, il vous faudra inclure le code Mootools dans votre extension. Pour inclure le framework Mootools dans votre extension, vous devez ajouter le code suivant à votre fichier view.html.php ou tmpl :
POUR JOOMLA! 1.5
JHTML::_('behavior.mootools');POUR JOOMLA! 2.5
JHtml::_('behavior.framework');Le code ci-dessus donnera le même résultat que lors d'une déclaration jQuery. Cela permet de s'assurer que Mootools est inclus correctement et une fois uniquement.
Ensuite, l'utilisation de Mootools est presque identique à celle de jQuery :
JFactory::getDocument()->addScriptDeclaration('
window.addEvent("domready", function() {
alert($("list").getElements("li").length);
});
');Vous pouvez consulter plus d'informations à propos de Mootools sur http://mootools.net/. Pour la documentation de l'API, veuillez consulter : http://mootools.net/docs/core.
Notes importantes pour les développeurs d’extensions tierces
Dans le cadre de la création d'un override de template ou d'une extension qui impose d'ajouter un fichier JS personnalisé, assurez-vous d'ajouter d'importantes dépendances, telles que Jquery ou Mootools avant votre fichier JS personnalisé. Les fichiers de framework JS doivent toujours être chargés avant tout autres fichiers afin de s'assurer qu'ils soient exécutés en premier, sinon d'autres fichiers qui seront chargés avant pourraient apparaître comme des exceptions JS.
Certains templates comme Protostar ou Beez intègrent toutes les dépendances dont vous avez besoin en utilisant des fonctions comme :
JHtml::_('bootstrap.framework');
pour charger Jquery + Bootstrap, mais vous ne devriez pas procéder ainsi pour vos extensions ou vos surcharges de templates. Assurez-vous que votre extension ou votre surcharge charge les dépendances dont vous avez besoin, avant que le template ne le fasse, je vous expliquerai pourquoi plus tard :
Par exemple, vous avez une surcharge personnalisée de template qui a besoin de l'intégration de fichier JS avec des scripts Jquery sur toutes les pages de remplacement de votre template. Dans ce cas, vous devez le déclarer au début de la section de votre fichier de surcharge :
JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
Si vous développez une extension tierce que vous souhaiter proposer sur le Joomla! Extensions Directory, vous devrez faire quelque chose comme ceci :
if($params->get('add_extension_resources', false))
{
JHtml::_('jquery.framework');
$doc->addScript('media/com_fancy/js/fancy-script.js');
}
La clause conditionnelle pour décider d'ajouter ou non les ressources de l'extension est très fortement encouragée et cela est considéré comme étant une bonne pratique car elle permet une flexibilité aux développeurs d'extensions tierces qui ne veulent pas utiliser vos ressources d'extension mais plutôt d'utiliser des fichiers modifiés/personnalisés sans avoir à se battre contre Joomla! en créant des solutions de rechange et des hacks pour être en mesure de retirer les ressources de vos extensions qui seront des doublons ou généreront des conflits.
Explication
Si vous regardez le code source de l'index.php du template Protostar, vous pouvez voir que les déclarations
JHtml::_('bootstrap.framework');
est ajoutée avant la déclaration
<jdoc:include type="head" />
cela peut vous faire penser que les fichiers framework et vos fichiers tierces utilisent les méthodes comme
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
$doc->addScript('media/com_fancy/js/fancy-script.js');
sera ajouté dans le bon ordre, au bon endroit, mais ce n'est pas le cas car les fichiers d'extension ou les surcharges de template sont exécuté en premier et le fichier index.php de votre template actuel est exécuté en dernier. Cela fera que vos fichiers JS personnalisés seront insérés en premier et que les fichiers du framework seront insérés après.
Ceci se produit parce que l'API Joomla! (tel que $doc->addScript) utilise un tableau array pour stocker les chemins des fichiers JS et ils seront rendus dans le document dans le même ordre qu'ils auront été insérés dans cet array (pile FIFO). Egalement, une fois qu'un chemin d'accès au fichier est inséré dans le tableau et qu'un autre appel d'API tente d'insérer le même fichier, de cette action est ignorée pour éviter les doublons. Cela signifie également que l'ordre des fichiers n'est pas modifié lorsque les mêmes fichiers tenteront d'être insérés plusieurs fois.
Après avoir exposé cela, il convient d'ajouter
JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
à votre surcharge personnalisée de template ou extension est requis et ne causera pas de dommages ou conflits avec l'appel :
JHtml::_('bootstrap.framework');
de votre fichier template index.php.
Liens externes
https://api.joomla.org/cms-2.5/classes/JHtmlBehavior.html#method_framework
https://api.joomla.org/cms-3/classes/JHtmlBehavior.html#method_framework
http://en.wikipedia.org/wiki/JavaScript