Gadget kitchen/fr

Bienvenue dans la cuisine des gadgets. Il s'agit d'un didacticiel expliquant comment écrire et utiliser des gadgets et des scripts utilisateur en JavaScript.



Que sont les scripts d'utilisateur et les gadgets?
MediaWiki permet à chacun d'écrire du code public JavaScript pour changer immédiatement le comportement du logiciel. Ce code peut être partagé avec d'autres utilisateurs. Ce code se trouve dans les pages wiki.


 * Un script utilisateur peut être modifié par son auteur originel (s'il est stocké dans l'espace de noms ) et par quiconque ayant les droits utilisateurs edituserjs (habituellement uniquement les administrateurs d'interface). Le code est généralement hébergé dans une sous-page de votre page utilisateur. Les exemples incluent : XTools/ArticleInfo.js et m:User:Hoo man/useful links.js. Les scripts utilisateur sont similaires aux pages JavaScript personnelles telles que Special:MyPage/common.js, mais ils permettent de partager avec d'autres utilisateurs, des portions de code unitaires.
 * Un gadget est un script utilisateur qui a été "promu" par un administrateur d'interface, en l'ajoutant à MediaWiki:Gadgets-definition. Les utilisateurs connectés peuvent activer les gadgets dans l'onglet Gadgets de leurs préférences utilisateur. Les gadgets sont créés et gérés par les administrateurs d'interface.
 * Par souci d'exhaustivité : Il y existe aussi le siteJS situé à MediaWiki:Common.js. Le JavaScript de ce fichier est exécuté automatiquement avec tous les utilisateurs qu'ils soient connectés ou non-connectés. Les administrateurs d'interface peuvent modifier cette page. Veuillez lire la section JavaScript du manuel d'interface pour d'autres informations.

Si vous exécutez votre propre copie de MediaWiki, doit être activé pour que les scripts utilisateur fonctionnent, et l'extension  doit être installée pour permettre de promouvoir des scripts individuels au statut de gadget. Pour une expérience de développement plus agréable, assurez-vous que l'extension est installée sur votre wiki.



Ecrivez votre premier script
Dans cette section, vous allez créer un exemple de script utilisateur qui calcule le temps estimé pour la lecture d'une page du wiki.
 * 1) Assurez-vous d'être connecté.
 * 2) Allez sur Special:MyPage/common.js. Cette page contient votre JavaScript personnel qui est chargé à chaque fois que vous affichez une page (sauf pour Special:Preferences).
 * 3) Créez la page, ou modifiez-la si elle existe déjà.
 * 4) Copiez les six lignes suivantes et collez-les dans la page :
 * 5) Cliquez sur .
 * 6) Ouvrez une page quelconque. Lisez le titre.
 * 1) Ouvrez une page quelconque. Lisez le titre.

Cet exemple de script utilisateur est extrait de Il y a beaucoup d'autres exemples de scripts utilisateur simples sur cette page.

En général, consultez les conventions de codage JavaScript pour écrire du JavaScript conforme au style de MediaWiki.



Développement de scripts utilisateur et de gadgets
Cette section liste les ressources nécessaires ou utiles pour les scripts utilisateur plus élaborés.

ResourceLoader
Les gadgets doivent utiliser ResourceLoader. est une fonctionnalité principale de MediaWiki qui fournit intelligemment des ressources JavaScript et CSS aux utilisateurs et aux lecteurs. Étant donné que les gadgets sont codés en JavaScript, en tant que codeur de gadgets, vous êtes obligé d'interagir avec ResourceLoader.

Votre gadget doit charger les modules ResourceLoader utiles.


 * Modules - Une liste des bibliothèques JavaScript, des plugins jQuery et des utilitaires MediaWiki qui existent déjà dans ResourceLoader et que vous pouvez réutiliser.
 * Voir la documentation jQuery pour toute information concernant l'utilisation de jQuery dans MediaWiki
 * Développer avec ResourceLoader — liste d'utilisations pratiques, comme l'activation du mode debug et aide au débogage.
 * Voir aussi les Meilleures utilisations de ResourceLoader.

OOUI
OOUI est une bibliothèque JavaScript avec des éléments d'interface utilisateur (tels que les fenêtres pop-up) utilisés spécifiquement sur MediaWiki. La bibliothèque des Gadgets de OOUI sur MediaWiki peut être utilisée dans les gadgets.



API Action de MediaWiki
Voir API pour plus d'informations.

VisualEditor
Voir le tutoriel dédié aux gadgets de VisualEditor sur Gadgets de l'Editeur Visuel.



Deboguer les scripts utilisateur et les gadgets

 * Les gadgets sont habituellement compactés par le ResourceLoader, minimisés et aggrégés. Utilisez le paramètre  de l'URI (précédé de   ou , bien sûr), pour demander la version non compressée de la page et pour charger le format  original du source de votre gadget. Voir aussi Developper avec ResourceLoader pour d'autres informations.
 * Apprenez comment utiliser les Outils du développeur pour votre navigateur (par exemple comment désactiver le cache de votre navigateur). Voir la documentation correspondante : Chrome/Chromium, Firefox, Internet Explorer, Opera, Safari.
 * Si un gadget existant pose problème, vous pouvez aussi utiliser la page Special:Gadgets pour connaître l'emplacement du code source du gadget.



Données confidentielles et contenu externe
Vous ne devez pas charger des ressources externes susceptibles de nuire à la confidentialité des utilisateurs. Dans les wikis Wikimedia, les domaines suivants sont considérés comme sûrs :


 * *.wiktionary.org
 * *.wikimedia.org
 * *.wikibooks.org
 * *.wikisource.org
 * *.wikiversity.org
 * *.wikinews.org
 * *.wikiquote.org
 * *.wikidata.org
 * *.wikivoyage.org
 * www.mediawiki.org



Exemple plus complexe de script utilisateur
Découvrez MediaWiki:Tutorial-QuickRC.js qui utilise mw.loader, mw.util, mw.html, mw.user de ResourceLoader, l'API MediaWiki Action, une boîte de dialogue d'interface utilisateur jQuery, jQuery AJAX et la liaison d'événement jQuery.

Copiez et collez le contenu de MediaWiki:Tutorial-QuickRC.js dans votre Special:MyPage/common.js.

Le résultat doit être le même que ci-dessus, mais vous pouvez maintenant modifier le script, jouer avec ou le remplacer par autre chose.



Charger un script utilisateur existant
Dans la section précédente, vous avez copié le contenu d'un script utilisateur. Dans cette section, vous allez charger le script existant MediaWiki:Tutorial-QuickRC.js à la place.


 * 1) Assurez-vous d'être connecté.
 * 2) Allez sur Special:MyPage/common.js. Cette page contient votre JavaScript personnel qui est chargé à chaque affichage de page (sauf pour  Special:Preferences).
 * 3) Créez cette page ou modifiez-la si elle existe déjà.
 * 4) Copiez le texte suivant et collez-le dans la page : mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript');
 * 5) Cliquez sur Publier les modifications. Vous devriez maintenant avoir un lien dans la section Outils appelé Journal rapide des modifications.
 * 6) Cliquez sur Journal rapide des modifications. Vous obtenez une fenêtre pop-up. Elle vous donne un sous-ensemble des modifications récentes sur ce site web.



Utiliser un script sur un autre wiki Wikimedia
Si vous souhaitez utiliser un script sur un autre site web Wikimedia (par exemple la Wikipedia anglaise au lieu de MediaWiki.org), effectuez les mêmes étapes que ci-dessus: indiquez à ResourceLoader de charger votre code. Consultez votre common.js sur la Wikipedia anglaise et ajoutez ce qui suit :

mw.loader.load("//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript");

Vous pouvez également charger le script utilisateur que vous venez de créer ci-dessus, en modifiant  dans la ligne précédente en   (remplacez   et   en conséquence). Ceci nécessite d'abord que vous n'enregistriez pas le code de votre script utilisateur dans Special:MyPage/common.js lui-même, mais à la place, dans une sous-page séparée de votre page utilisateur.

Cela vous permet également d'avoir le code à un seul endroit et de n'en faire la mise à jour qu'une seule fois.



Inconvénients et problèmes des gadgets

 * Les gadgets sont développés par les membres de la communauté. À ce jour, aucune révision de code formelle n'est requise pour les gadgets sur les sites Wikimedia (voir T71445). Veuillez suivre les meilleures pratiques répertoriées sur cette page.
 * Sur les site Wikimedia, la façon de promouvoir un script utilisateur en gadget dans l'onglet « Gadgets » des préférences utilisateur n'est pas toujours claire. Cherchez un administrateur d'interfaces et fournissez lui éventuellement les instructions de déploiement.
 * Wikimedia n'a pas de processus systématique pour réutiliser, modifier ou contribuer aux scripts utilisateur et aux gadgets existants.



Idées sur lesquelles travailler
Certains membres de communautés Wikimedia peuvent partager leurs idées sur ce qu'ils souhaiteraient voir implémenté par d'autres personnes.


 * Gadget Kitchen/Requests - page pas très populaire, ne perdez pas votre temps
 * w:Wikipedia:User scripts/Requests Wikipédia en anglais



Deployer ou activer un gadget
Si votre script utilisateur est amené à devenir un gadget (voir les définitions ci-dessus) sur un wiki, les étapes suivantes sont nécessaires :


 * Etapes pour les auteurs de scripts utilisateur :
 * Trouver un développeur expérimenté pour relire le code de votre gadget. Il n'existe pas de processus formel pour faire cela.
 * Voyez avec les membres de la communauté pour savoir s'il peut y avoir des problèmes quand on active le gadget. Pour le site web MediaWiki.org lui-même, cela s'appelle Village Pump.
 * Recherchez un administrateur de site avec des droits sur les interfaces. Voir la page Special:ListUsers/interface-admin de votre wiki.
 * Etapes pour l'administrateur d'interface :
 * Copiez vos fichiers JS et CSS dans l'espace de noms  de votre wiki, et assurez-vous que le nom des pages a le préfixe  . Exemple :
 * Définissez le gadget sur la page MediaWiki:Gadgets-definition de votre wiki. Cela comprend les modules utilisés, les dépendances, le nom des fichiers JS et CSS, etc. Ceci permettra aux utilisateurs d'activer le gadget sur la page Special:Preferences de leur wiki. Exemple  :
 * Crééez une page pour le gadget dans l'espace de noms  avec le préfix  . Cela va générer une étiquette pour le gadget sur la page Special:Preferences de votre wiki. Exemple :



Contribution aux scripts des utilisateurs
If a user script is made by another user you may be able to contribute to it. You can do this by making a copy of the user script as a subpage of your own user page. Then replace the original user script you had enabled with the one that is a user page in your common.js. Proceed to make edits as you please to your copy of the script. If you want the script to contain the changes you made to your copy of the script, you should ping the author of the script on the discussion page of the original user script with the page that contains your changes and ask them to add the changes. If the user is no longer active, then you should notify the community that your version of the script exists by linking the script on your wiki's list of scripts.



Autres pages en rapport

 * Wikipedia:Scripts utilisateur sur Wikipedia anglais et ses alternatives dans d'autres langues sont les principaux hubs pour le développement de scripts utilisateur et de gadgets sur Wikipedia.
 * Le guide des scripts utilisateur de la Wikipedia anglophone possède des tonnes d'informations utiles pour débuter.
 * Wikipedia:Gadget page sur la Wikipedia anglaise
 * Diapositives d'un atelier pour apprendre les bases des scripts utilisateur et des gadgets (partie de Small wiki toolkits)
 * Liste des gadgets par popularité pour tous les projets Wikimedia
 * Pour un site donné, voir Special:GadgetUsage pour le nombre d'utilisateurs par gadget
 * Compatibilité - Support JavaScript de MediaWiki selon la version des navigateurs
 * A video tutorial from the year 2012 regarding gadgets and user scripts. Un peu obsolète et dont la qualité pourrait être améliorée, mais indique comment utiliser les outils développeur, etc.
 * Extention EventLogging, décrit le mécanisme de la collecte des données créées par l'interaction des utilisateurs avec les gadgets.