Cuisine de Gadgets

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Gadget kitchen and the translation is 100% complete.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎français • ‎italiano • ‎português do Brasil • ‎русский

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 User:) et par quiconque ayant les droits utilisateurs edituserjs (habituellement uniquement les administrateurs d'interface). The code is usually hosted on a sub page 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, $wgAllowUserJs doit être activé pour que les scripts utilisateur fonctionnent, et l'extension [[Special:MyLanguage/Extension:Gadgets|]] 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 CodeEditor est installée sur votre wiki.

Write your first user script

In this section, you create an example user script which calculates the estimated reading time of a wiki page.

  1. Ensure you are logged in.
  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 six lines and paste these lines into the page:
var numWords = $("#mw-content-text > div").text().split(" ").length;
var headerWords = $("h1").text().split(" ").length;
var totalWords = numWords + headerWords;
var timeInMinutes = totalWords / 200;
var header = $("h1").text();
$("h1").text(header + " (it will take you " + timeInMinutes + " minutes to read this page)");
  1. Click "Publish changes".
  2. Go to any page. Look at the title.

This example user script is taken from ChickTech High School Kickoff 2017/Tasks . There are more examples for simple user scripts on that 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

This section lists resources which are either needed or helpful for non-simple user scripts.

ResourceLoader

Since 2015 (MediaWiki 1.26), gadgets must use ResourceLoader (phab:T107399). 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.

OOUI

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

MediaWiki Action API

See Special:MyLanguage/API for more information.

Si votre gadget utilise l'API MediaWiki, ajoutez le paramètre "?callback=?" à l'URL de l'API si vous essayez de faire une demande d'API qui enfreindrait la politique de même origine (par exemple, faire une demande à l'API Commons de Wikipédia). Cela déclenche l'utilisation de JSONP et applique certaines restrictions.

VisualEditor

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

Debugging user scripts and gadgets

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
Il existe un travail Jenkins (job, code) pour vérifier automatiquement les gadgets pour ce principe.

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.

Cliquer sur "Aperçu" (ou utiliser le raccourci clavier, généralement Maj + Alt + P) dans l'éditeur exécutera également la dernière version du script. C'est un bon moyen d'itérer sans enregistrer la page. N'oubliez pas que rien n'est enregistré tant que vous n'appuyez pas sur "Publier la page".

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 MediaWiki:Tutorial-QuickRC.js dans la ligne précédente en User:YourName/YourScript.js (remplacez YourName et YourScript 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 phab: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

Si vous souhaitez écrire des fonctionnalités qui aident directement les membres de la communauté Wikimedia, consultez :

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 MediaWiki: namespace on your wiki, and make sure the page names have the prefix Gadget-.
      Example: MediaWiki:Gadget-userfeedback.js
    • 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: userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css
    • Create a page for the gadget in the MediaWiki: namespace with prefix Gadget-. This will generate a label for the gadget on the Special:Preferences page of your wiki.
      Example: MediaWiki:Gadget-userfeedback

Related pages

À l'avenir, les modifications apportées à ResourceLoader ("Gadgets 2.0") simplifieront la gestion des gadgets.