Gadget kitchen/fr

Bienvenue dans la cuisine de 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 à quiconque 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). The code is usually hosted on a subpage of your user page. Examples include: XTools/ArticleInfo.js and m:User:Hoo man/useful links.js. User scripts are similar to the personal JavaScript pages such as Special:MyPage/common.js, but they allow single code chunks to be shared with other users.
 * 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 a 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. Interface administrators can edit that page. Read Manual:Interface/JavaScript for detailed information.

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) Soit vous créez la page, soit vous la modifiez si elle existait 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
Since 2015 (MediaWiki 1.26), gadgets must use ResourceLoader (T107399). 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 que vous pouvez réutiliser.
 * See the jQuery documentation for information about using jQuery in MediaWiki
 * Developing with ResourceLoader — A list of useful practices, like enabling the debug mode and help with debugging.
 * Also see the ResourceLoader best practices.

OOUI
OOUI is a JavaScript library with user interface elements (for example pop-up windows) specifically for use in MediaWiki. The library Using OOUI in MediaWiki#Gadgets can be used in gadgets.

MediaWiki Action API
See API for more information.

VisualEditor
See VisualEditor/Gadgets for a tutorial specifically for VisualEditor gadgets.

Debugging user scripts and gadgets

 * Gadgets are usually compacted by the ResourceLoader, minimized and aggregated. Use the  URI parameter (preceded by   or , of course), to ask for the non-compacted version of the page and to load the "original source form" of your gadget. Also see Developing with ResourceLoader for more information.
 * Learn how to use the Developer Tools of your browser (for example how to disable the cache in your browser). See the corresponding documentation: Chrome/Chromium, Firefox, Internet Explorer, Opera, Safari.
 * If an existing gadget has problems, you can also use the page Special:Gadgets to find the source code location of a gadget.

Privacy and external content
Vous ne devez pas charger de 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

A more complex user script example
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 et le remplacer par autre chose.

Load an existing user script
In the previous section, you copied the content of a user script. In this section, you will load the existing script MediaWiki:Tutorial-QuickRC.js instead.


 * 1) Assurez-vous que vous êtes connecté.
 * 2) Visit Special:MyPage/common.js. This page holds your personal JavaScript that is loaded on every page view (except for Special:Preferences).
 * 3) Either create the page or edit the page if it already exists.
 * 4) Copy the following text and paste it into the page: mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript');
 * 5) Click "Publish changes". You should now have a link in the "Tools" section called "Quick changelog".
 * 6) Click "Quick changelog". You get a pop-up window. It shows you a subset of the recent changes on this website.

Use a script on another Wikimedia wiki
Si vous souhaitez utiliser un script sur un autre site Web Wikimedia (par exemple Wikipedia anglais au lieu de MediaWiki.org), vous effectuez les mêmes étapes que ci-dessus: vous indiquez à ResourceLoader de charger votre code. Consultez votre common.js sur Wikipedia anglais 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). This first requires that you do not store the code of your user script in Special:MyPage/common.js itself but instead in a separate sub page of your user page.

This also helps to keep code in one single place, so you have to update code in only one place.

Disadvantages and problems of 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.
 * On Wikimedia sites, the process how to "promote" a user script to a gadget in the "Gadgets" tab of the user preferences is not always clear. You will have to find an interface administrator and might have to provide deployment instructions to them.
 * Wikimedia lacks a systematic process for re-using, modifying and contributing to existing user scripts and gadgets.

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 - not a popular page, so you might waste time
 * w:Wikipedia:User scripts/Requests for English Wikipedia

Deploying or enabling a gadget
If your user script should become a gadget (see the definitions above) on a wiki, the following steps are needed:


 * Steps for the user script author:
 * Recruit an experienced developer to review your gadget code. There is no formal process to do so.
 * Check with community members if there aren't any concerns with enabling the gadget on a wiki. For the website MediaWiki.org itself, this would be Project:Village Pump.
 * Recruit a site administrator with interface rights. See the page Special:ListUsers/interface-admin on your wiki.
 * Steps for the interface administrator:
 * Copy your JS & CSS files in the  namespace on your wiki, and make sure the page names have the prefix  . Example:
 * Define the gadget on the MediaWiki:Gadgets-definition page of your wiki. That includes the modules used, dependencies, JS, and CSS file names, etc. This will allow users to enable the gadget on the Special:Preferences page of your wiki. Example:
 * Create a page for the gadget in the  namespace with prefix  . This will generate a label for the gadget on the Special:Preferences page of your wiki. Example:

Related pages

 * 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.
 * The user scripts guide on the English Wikipedia has tons of useful information to get you started.
 * Wikipedia:Gadget page sur Wikipedia anglais
 * Slides for a workshop to teach the basics of user scripts and gadgets (part of Small wiki toolkits)
 * Liste des gadgets par popularité dans tous les projets Wikimedia
 * For a specific website, see Special:GadgetUsage for the number of users that each gadget has
 * Compatibility - MediaWiki's JavaScript support per browser and browser version
 * A video tutorial from the year 2012 regarding gadgets and user scripts. This is a bit outdated and the quality could be better, but shows how to use developer tools etc.
 * See Extension:EventLogging for a mechanism to gather data created from users interacting with a gadget.