Extension:Graph

Manuel des extensions MediaWiki

Graph État de la version : non-maintenu
Implémentation	Balise , ContentHandler
Description	Graphes contrôlés par les données
Auteur(s)	Yuri Astrakhan (Yurik discussion), Dan Andreescu, Frédéric Bolduc
MediaWiki	>= 1.43
Licence	Licence MIT
Téléchargement	Télécharger l'extension Git [?]: Télécharger la branche master de Git parcourir le dépôt (Phabricator · GitHub) historique des validations (commits) contributeurs du dépôt (GitHub) relecture du code
Paramètres $wgGraphDefaultVegaVer $wgGraphAllowHttp $wgGraphAllowedDomains
Accroches utilisées OutputPageParserOutput ParserFirstCallInit
Téléchargements trimestriels	32 (Ranked 108th)
Utilisé par les wikis publics	884 (Ranked 281st)
Traduire l’extension Graph sur translatewiki.net si elle y est disponible
Problèmes	Tâches ouvertes · Signaler un bogue

L'extension Graph permet, au moyen de la balise ‎<graph>, la description de graphiques comme les diagrammes en barre, les camemberts, les frises chronologiques et les histogrammes (voir les démonstrations), dans un format JSON utilisé pour afficher un graphique basé sur la grammaire de visualisation Vega.

Informations générales

L'extension Graph permet d'intégrer dans les pages wiki des graphiques puissants basés sur la grammaire Vega. Les graphiques peuvent aussi bien être interactifs.

Le moyen le plus simple pour intégrer un graphique est d'utiliser un modèle tout prêt comme {{Graph:Chart}}. Ces modèles dissimulent toutes les complexités de Vega. Les utilisateurs avancés peuvent utiliser le bac à sable de Graph pour développer leurs graphiques. Le bac à sable de Graph permet d'utiliser la syntaxe du modèle wiki et JSON. L'extension s'intègre avec VisualEditor et fournit ainsi un outil et un assistant simple pour générer les graphiques de base, en entrant les valeurs directement dans l'éditeur.

Liens utiles

• Documentation Vega 2 – pages de documentation Vega 2 restaurées sur nyurik/vega/wiki.
• Guide - Recommandations générales sur la façon d'utiliser les graphiques dans un Wiki.
• Tutoriel interactif -Instructions étape par étape pour construire un graphique interactif complexe à partir de zéro.
• Page de démo - pour de nombreux exemples et astuces d'utilisation.
• TechTalk Video - une discussion technique de la WMF à propos de l'extension Graph, comprenant une grande démonstration de l'éditeur Lyra (également installé sur labs).
• Pour découvrir quelques fonctionnalités à venir de Vega (Keynote de Jeffrey Heer).
• Vega pour les développeurs - meilleur emplacement des ressources Vega
• Migrer vers Vega 2.0
• Vidéo d'introduction à Vega interactif

Installation

• Requiert l'extension JsonConfig
• Téléchargez et placez le(s) fichier(s) dans un répertoire appelé Graph dans votre dossier extensions/.
  Les développeurs et les contributeurs au code doivent à la place installer l'extension à partir de Git en utilisant:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Graph
• Ajoutez le code suivant à la fin de votre fichier LocalSettings.php  :

  wfLoadExtension( 'Graph' );
  

•  Fait – Accédez à Special:Version sur votre wiki pour vérifier que l'extension a bien été installée.

Installation Vagrant :

• Si vous utilisez Vagrant , installez avec vagrant roles enable graph --provision

Paramètres de configuration supplémentaires

Si vous envisagez de répliquer un environnement de production tel que en.wiki vous devrez réaliser les étapes suivantes :

• Installez Scribunto , Imagemap et TemplateStyles , et autorisez les téléversements SVG
  • si vous employez Vagrant, vous pouvez utiliser vagrant roles enable --provision scribunto imagemap templatestyles svg
• Importez de mediawiki.org : Module:Graph, Module:Graph/doc, Template:Nowrap et Template:Nowrap/styles.css (lien d'export)
• Importez de la Wikipedia anglophone Module:Chart et Module:Chart/Default colors (lien d'export)
• importez le fichier File:Circle_frame.svg

Débogage des graphiques et portage des graphes de Vega 2 vers Vega 5

Un bac à sable est fourni sur Special:GraphSandbox; il fonctionne de manière similaire à l'éditeur graphique Vega. L'outil MediaWiki comprend le code compatible qui fait correspondre les anciens schémas Vega à la version active actuellement. L'insertion d'un ancien schéma dans la zone textuelle principale affiche le schéma modifié et modernisé en-dessous du graphique lorsque c'est possible.

Similaire à vega.github.io/editor, l'objet Vega peut être inspecté avec le JavaScript global VEGA_DEBUG. Voir le guide de débogage de Vega pour son utilisation.

Migration des schémas à partir des anciennes versions de Vega

Initialement, Graph prenait en charge Vega 2. Vous pouvez coller le code JSON des graphiques dans http://vega.github.io/vega-editor/?mode=vega pour voir la manière dont ils étaient rendus, en comparaison avec Vega 5.

Special:GraphSandbox (pour le code le plus récent, voir la version bêta de grappe du bac à sable) peut être utilisé pour faire correspondre les anciens schémas aux nouveaux. Copiez l'ancien schéma dans la zone textuelle principale et le schéma mis à jour apparaîtra dans la zone de texte sous le graphique. Copiez le nouveau schéma dans votre code.

Exemples de diagrammes

Voir la page de démonstration pour plus d'exemples et d'astuces d'utilisation.

Replis définis par l'utilisateur

Lorsque le rendu se fait côté client, il est possible d'utiliser Wikimedia Commons pour fournir une image statique de repli aux utilisateurs noscript. Ceci est une solution temporaire le temps qu'un nouveau service soit mis en place pour fournir la génération du côté serveur.

L'utilisateur doit d'abord téléverser le graphe statique dans Wikimedia Commons.

Les images de repli ont deux variables fallback et fallbackWidth.

fallback est relatif à un nom de fichier de Wikimedia Commons.

fallbackWidth est la largeur de repli des images, en pixels.

Ces variables sont passées au graphique de la manière suivante :

<graph fallback="Graph test seddon.png" fallbackWidth=450>

Là où les modules lua sont utilisés comme Module:Graph, ces variables peuvent être fournies par la fonction de la balise. Si on avait choisi Template:Graph:Chart , cela ressemblerait à :

{{safesubst:#tag:graph|{{safesubst:#invoke:Graph|chartWrapper}} | fallback = {{{fallback|''}}} |  fallbackWidth= {{{fallbackWidth|''}}} }}

Il peut être ensuite utilisé dans un modèle de la manière suivante :

{{Graph:Chart|width=400|height=100|xAxisTitle=X|yAxisTitle=Y
 |type=rect|x=1,2,3,4,5,6,7,8|y=10,12,6,14,2,10,7,9|fallback=Graph test seddon.png|fallbackWidth=450}}

Si la largeur de repli fallbackWidth n'est pas fournie, mais qu'une image est définie, alors l'extension dérive la largeur à partir de celle du graphe fourni. La raison de ceci est qu'il existe souvent une différence entre la largeur de l'image générée et la largeur actuelle de l'image.

{{Graph:Chart|width=400|height=100|xAxisTitle=X|yAxisTitle=Y
 |type=rect|x=1,2,3,4,5,6,7,8|y=10,12,6,14,2,10,7,9|fallback=Graph test seddon.png}}

Données externes

Le protocole HTTP(S) ne peut pas être utilisé pour obtenir les données du graphique. À la place, utilisez un protocole wiki personnalisé tel que wikiraw:, wikiapi: ou autre.

L'extension Graph utilise le paramètre GraphAllowedDomains pour contrôler la résolution de ces protocoles : Notez que parce que les requêtes sont basées sur la structures des éléments wikibase, elles peuvent brusquement s'arrêter de fonctionner quand des données sous-jacentes sont mises à jour et modifiées. C'est parce que les données fournies alors pour créer le graphique sont incomplètes, vides, ou non valides et ne peuvent pas être utilisées. Dans ces cas, le graphe sera vide en sortie (voir phab:T168601).

$wgGraphAllowedDomains = [
    # clés http et https; liste tous les domaines autorisés pour l'accès aux données externes.
    # Tout domaine listé ici autorise aussi automatiquement tous les sous-domaines.
    # Protocoles personnalisés tels que 'wikiraw' ; définit le protocole à utiliser.
    # De cette manière, wikiraw://en.wikipedia.org/Page devient une requête d'API pour https://en.wikipedia.org/w/api.php?action=query&titles=Page&...
    'https' => [ 'wikipedia.org', 'wikimedia.org', ... ],
    'http' => [ 'wmflabs.org', ... ],
    
    # liste des domaines autorisés pour le wikirawupload : protocole d'accès.
    # Correspondance exacte seulement, sans les sous-domaines.
    'wikirawupload' => [ 'upload.wikimedia.org' ],
    
    # même chose que wikirawupload mais pour les requêtes Sparql de Wikidata
    'wikidatasparql' => [ 'query.wikidata.org' ],
];

Fonctionnement interne

Lors de l'analyse syntaxique, l'extension Graph développe tous les paramètres et les expressions du modèle et range les définitions complètes du graphique dans la propriété de page ParserOutput en utilisant le hachage du graphe pour l'ID.

L'extension graph ajoute du code HTML à la page où il y a des graphes : un ‎<div> comportant l'attribut graph-id. Exemple :

<div class="mw-graph" data-graph-id="72edc224f0a10b343c1e84f63dbfc97cac9bc957">
</div>

L'extension Graph ajoute un module JavaScript ResourceLoader ext.graph à la page qui inclut la bibliothèque Vega, et place le JSON des définitions du graphique dans une variable mediawiki.config nommée wgGraphSpecs. Une fois que le client a chargé ce module, la bibliothèque JavaScript Vega remplit chaque ‎<div> avec un canevas HTML et dessine le graphique à l'intérieur qui remplace l'image statique.

Fonctions de sécurité

‎<graph> peut être configuré pour interdire le référencement de sources de données non fiables (Wikimedia par exemple, n'autorise les données que provenant des sites Wikimedia).

Licence

La bibliothèque Vega est distribuée sous une license BSD modifiée acceptable, ce qui nous permet de l'utiliser.

“	Ceci ressemble à une copie de la licence BSD, avec quelques modifications mineures (acceptables). Ce n'est pas gênant pour nous de l'utiliser bien que, idéalement, on ne doit pas faire de telles modifications dans la licence. C'est mieux lorsque l'on ne fait pas ce type de modification dans la licence que l'on utilise car cela évite toute confusion (comme ici) pour savoir si elle reste valable pour les sources libres.	”
—Stephen LaPorte

Configuration

wgGraphAllowedDomains

Voir la section sur les données externes.

Module de l'Éditeur Visuel

Depuis l'été 2015, l'extension Graph est également associée au module ext.graph.VisualEditor qui permet l'édition de graphique dans l'Éditeur Visuel.

Ce module est le fruit d'un projet du Google Summer of Code 2015. Voir phab:T89287 pour plus de détails.

Ce module permet aux utilisateurs de visualiser les graphiques dans l'Éditeur Visuel, contrairement à certaines extensions. De plus, les utilisateurs peuvent ouvrir une boîte de dialogue pour éditer le type de graphique, ses données et l'espacement. L'interface utilisateur offre aussi un moyen d'éditer les paramètres bruts JSON d'un graphe dans l'éditeur visuel, sans passer par l'éditeur de wikitexte classique, donnant la possibilité aux utilisateurs plus avancés d'ajuster les paramètres qui ne sont pas pris en compte par l'interface.

Cette première étape sert de tremplin au développement de l'édition de graphiques dans l'Éditeur Visuel, et les possibilités d'amélioration et d'extension du module sont nombreuses.

Corriger des graphiques erronés

Les erreurs avec les graphiques seront consignées dans la console développeur.

Erreur : Arguments de constructeur incorrects (phab:T277906)

Pour corriger : remplacez filepath:Earthmap1000x500compac.jpg par filepath:Earthmap1000x500.jpg

Exemple.

TypeError: undefined is not an object (evaluating 'datum.firstYear.value')

Correctif: assurez-vous de ne pas avoir intialisé la valeur par défaut à null

Exemple.

Voir aussi

• Diagram extensions
• Plotly — la bibliothèque de graphes à source libre JavaScript (avec des possibilité de représentation en 3D)
• D3 — documents sur le contrôle par les données