Jump to content

Cuisine des Gadgets

From mediawiki.org
This page is a translated version of the page Gadget kitchen and the translation is 91% complete.
Outdated translations are marked like this.
Languages:

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 User:) 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, $wgAllowUserJs doit être activé pour que les scripts utilisateur fonctionnent, et l'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.

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 : 
    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)");
  5. Cliquez sur Publier les modifications.
  6. Ouvrez une page quelconque. Lisez le titre.

Cet exemple de script utilisateur est extrait de ChickTech High School Kickoff 2017/Tasks . Il y a beaucoup d'autres exemples de scripts utilisateur simples sur cette page.

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.

Cliquer sur "Aperçu" (ou utiliser le raccourci clavier, généralement ⇧ Shift+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".

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

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. 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 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

Within the context of a MediaWiki website the Action API can be accessed from JavaScript via the mw.Api JavaScript API. (mw.ForeignApi for allowed cross-site requests, e.g. between WMF wikis.) Voir API pour plus d'informations.

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

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

Deboguer les scripts utilisateur et les gadgets

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
Il a existé une tâche Jenkins (job, code) qui vérifiait automatiquement les gadgets pour ce principe, mais elle n'a pas été activée depuis 2022.

Exécuter du code au chargement de la page

La tâche commune à l'exécution du code et au chargement de la page comporte plusieurs pièges dans lesquels même les contributeurs expérimentés peuvent tomber.

  • Tout d'abord, si votre code utilise les éléments du DOM, exécutez-le au chargement de la page. Sinon votre code pourrait s'exécuter trop tôt. La manière générale de faire cela est d'utiliser la fonction $() de jQuery qui fait la même chose que $(document).ready().
  • Néanmoins, si votre code fonctionne sur le contenu de la page (l'élément #mw-content-text), vous devez utiliser l'accroche 'wikipage.content' à la place. De cette manière votre code va retraiter la page avec succès quand elle sera mise à jour de manière asynchrone et que l'accroche sera réactivée. Il existe toute une variété d'outils qui font cela, allant de l'aperçu des modifications jusqu'à la mise à jour automatique de la liste de suivi.
  • Assurez-vous de ne travailler qu'avec les descendants de l'élément $content utilisé par votre fonction gestionnaire et non pas avec la page complète. Sinon vous pourriez terminer en exécutant le même code plusieurs fois sur les mêmes éléments. Notez que l'accroche 'wikipage.content' peut être activée réellement plusieurs fois.
  • Faites attention sur ce qui est passé dans l'argument $content de la fonction gestionnaire. Il ne faut pas supposer qu'il s'agit de l'élément #mw-content-text. Il peut s'agir d'une petite partie de la page, par exemple quand elle est prévisualisée.

Un code qui fonctionne avec le contenu de la page et qui évite les pièges mentionnés ci-dessus peut ressembler à ceci : 

mw.hook( 'wikipage.content' ).add( function ( $content ) {
	const $target = $content.find( '.targetClass' );
	if ( $target.length ) {
		// Faites les choses avec $target
	}

	// Exécutez seulement certaines opérations lorsque #mw-content-text figure dans l'argument
	if ( $content.is( '#mw-content-text' ) ) {
		const $note = $( '<div>' )
			.addClass( 'myScript-note' )
			.text( 'MyScript has successfully processed the content!' );
		$content.prepend( $note );
	}
} );

Si votre code fonctionne avec le contenu de la page et ajoute des gestionnaires d'événements aux éléments du DOM alors, au lieu d'utiliser l'accroche 'wikipage.content' et de chercher les éléments pour leur attacher des écouteurs d'événements quand l'accroche est activée, vous pouvez attacher un écouteur d'événements sur un élément en dehors de la zone de contenu ou du document complet, mais en filtrant les événements à l'aide d'un sélecteur (voir la documentation jQuery). C'est-à-dire que au lieu d'écrire $content.find( '.targetClass' ).on( 'click', ... ), vous pouvez écrire $( document ).on( 'click', '.targetClass', ... ).

Recording metrics

Some gadgets are serious business. When your gadget gets serious, you might want to instrument it for analytics purposes, for example to measure the click rate of specific UI elements added to a page by the gadget.

Page principale : Gadget kitchen: recording metrics


Miscellaneous

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 phab: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.

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, il s'agit de la Pompe du village.
    • 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 MediaWiki: de votre wiki, et assurez-vous que le nom des pages a le préfixe Gadget-.
      Exemple : MediaWiki:Gadget-userfeedback.js
    • 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  : userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css
    • Crééez une page pour le gadget dans l'espace de noms MediaWiki: avec le préfix Gadget-. Cela va générer une étiquette pour le gadget sur la page Special:Preferences de votre wiki.
      Exemple : MediaWiki:Gadget-userfeedback

Contribution aux scripts des utilisateurs

Si une autre personne a écrit le script utilisateur vous avez la possibilité d'y contribuer. Vous pouvez le faire en réalisant une copie du script utilisateur en tant que sous-page de votre propre page utilisateur. Ensuite, remplacez le script utilisateur original que vous avez activé par celui de la page utilisateur de votre common.js. Continuez à améliorer votre copie du scénario. Si vous voulez que le script contienne les modifications que vous avez apportées dans votre copie, vous devez faire un ping de l'auteur du script sur la page de discussion du script utilisateur original en indiquant la page contenant vos modifications et lui demander d'ajouter les modifications. Si l'utilisateur n'est plus actif, vous devez informer la communauté que votre version du script existe en ajoutant le lien correspondant dans la liste des scripts de votre wiki.

Autres pages en rapport

Retrieved from "https://www.mediawiki.org/w/index.php?title=Gadget_kitchen/fr&oldid=6741916"