Difference between revisions of "Adding JavaScript/fr"

Revision as of 18:00, 2 June 2015

Other languages:

Deutsch • ‎English • ‎Nederlands • ‎eesti • ‎español • ‎français • ‎português do Brasil • ‎български • ‎فارسی • ‎हिन्दी • ‎বাংলা • ‎中文（台灣）‎

Joomla!

2.5 & 3.x

séries

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

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

to load Jquery + Bootstrap, but you should not rely in this fact on your extensions or custom templates overrides. Always make sure your extension or custom override load the dependencies you need before the template does it, I will explain why later:

For example if you got a custom template override that needs to insert a JS file with some Jquery scripts that does fancy things on all the pages where that template override is being used. In that case you should declare this on the top section of that override file:

JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');

If you are developing a 3rd party extension that you plan to put on the Joomla! extension directory you should do something like this:

if($params->get('add_extension_resources', false))
{
    JHtml::_('jquery.framework');
    $doc->addScript('media/com_fancy/js/fancy-script.js');
}

The conditional clause to decide whether to add or not the extension resources is strongly encouraged and considered a good practice because it gives flexibility to 3rd party developers who don't want to use your extension resources and use custom/modified files without having to battle with Joomla! using workarounds and hacks to be able to remove your original extensions resources in order to avoid duplicates and conflicts.

Explication

If you check the source code of the index.php from the Protostar template, you can see that the statements

JHtml::_('bootstrap.framework');

is added way before the statement

<jdoc:include type="head" />

this can make you think that the framework files and your 3rd party files using methods like

$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
$doc->addScript('media/com_fancy/js/fancy-script.js');

will be added in the right order at the right spot, but that is not the case, because extension files and template override files are processed first and the index.php file of your current template is processed the last. This will cause that your custom JS files get inserted first and the framework files inserted from the template get inserted after.

This happens because the Joomla API (such as $doc->addScript) uses an array to store the JS files paths and they get rendered in the document in the same order they where inserted into that array (FIFO stack), also once a file path is inserted on the array and another API call tries to insert the same file this action is ignored to avid duplicates, it also means that the order of the files is not altered when the same files is attempted to be inserted several times.

Having said that doing this

JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');

at your custom templates overrides and extension, is required and does not cause harm or conflict with the call

JHtml::_('bootstrap.framework');

à votre fichier template index.php.

Liens externes

http://api.joomla.org/Joomla-Platform/HTML/JHtmlBehavior.html#methodframework

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

@@ Line 129: / Line 129: @@
 ==Notes importantes pour les développeurs d’extensions tierces==
-If you are creating a custom template override or extension that needs to add a custom JS file, make sure to add important dependencies such as Jquery or Mootools before your custom JS files. JS framework fiels must always be  loaded before any other files to make sure they get executed first, otherwise other files that load before the frameworks they need are likely to end in JS exceptions.
+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 :