Extension:Graph/Guide/fr

From mediawiki.org
This page is a translated version of the page Extension:Graph/Guide and the translation is 100% complete.
Languages:

Cette page est destinée à la communauté pour partager les meilleures pratiques sur l'utilisation de l'extension Graph . Voir aussi le Tutoriel interactif de Graph .

Organiser les graphiques dans un wiki

Séparez les graphiques des articles

Même si les graphiques peuvent être placés à l'intérieur de l'article, il est de loin préférable de les intégrer sous forme de modèles séparés, comme par exemple Template:Graph:<yourgraphname> qui peut être inséré avec 

{{Graph:<yourgraphname>}}

Personnaliser les graphiques

Même si vous pouvez intégrer les paramètres du graphique directement dans le graph, généralement ce n'est pas une bonne idée de faire ainsi. Les graphiques doivent être conçus comme des modèles flexibles qui peuvent être réutilisés dans plusieurs articles avec des ensembles de données et un style différents. Par exemple, même si la largeur et la hauteur du graphique peuvent être codées en dur : 

"width": 400, "height": 200,   // mauvais

il devrait être écrit comme un modèle de paramètres avec des valeurs par défaut, permettant une personnalisation facile : 

{{#tag:graph|{
    ...
    "width": {{{width|400}}}, "height": {{{height|200}}},   // bien formulé
    ...
} }}

Séparez les données du graphique

Tout comme pour le style ci-dessus, les données elles-mêmes ne doivent pas être stockées dans le graphique. Considérons une page avec un grand tableau qui peut être présentées dans un graphique, par exemple le liste des toiles les plus chères. La page contient un tableau assez complexe avec des données :
{|
! Price 
! Painting 
! Image 
! Artist 
! Year 
! ...
|-
! data-sort-value="$300"|~$300
| ''[[When Will You Marry?|Nafea Faa Ipoipo (When Will You Marry?)]]''
| [[File:Paul Gauguin, Nafea Faa Ipoipo? (When Will You Marry?) 1892, oil on canvas, 101 x 77 cm.jpg|95px]]
| {{sort|Gaugin, Paul|[[Paul Gauguin]]}}
| 1892
...
|}

L'approche la plus simple pour construire un graphique consiste à extraire les données utiles et à placer le graphique avec ces données à côté du tableau. Même si cela fonctionne, cette approche n'est pas très bonne car il y a deux copies des mêmes données qui devront être mises à jour après chaque changement. De plus, si le graph se trouve à l'intérieur du texte, l'article s'allonge et cumule du texte, du code et des données - moins de personnes pourront le modifier. Si le graphique est placé dans un modèle séparé, les rédacteurs sont plus susceptibles d'oublier de le mettre à jour lorsqu'ils modifient les données.

La solution adéquate, même si elle est un peu plus difficile à mettre en place au début, offrira un cheminement beaucoup plus sûr et plus facile à gérer, et pourra être réutilisée pour ce genre de liste.

  1. Créer une page séparée avec les données brutes, de préférence au format JSON. La structure de ce fichier est déterminée par les données nécessaires à la liste.
  2. Créer un module Lua avec une fonction qui convertit ces données brutes en une table wiki bien formatée.
  3. Dans le même module Lua, créez une autre fonction qui extrait les données nécessaires au graphique et les affiche sous forme de données au format JSON.
  4. Créer le modèle de graphique qui peut utiliser les données ci-dessus et le tracer.
  5. Enfin, insérez ces deux éléments dans la page de la liste :

Insérer un tableau bien formaté avec des données : 

{{#invoke:MyLuaModule|BuildTable|PageWithSourceData|...}}

Insérer un graphique avec les mêmes données : 

{{Graph:MyGraph | {{#invoke:MyLuaModule|ExtractGraphData|PageWithSourceData|...}} }}

Données externes

Les données du graphique peuvent être intégrées dans la définition du graphique, ou fournies via un lien "url". Contrairement à la balise Vega standard, la balise du graphique nécessite que tous les liens externes utilisent l'un des protocoles personnalisés du wiki :

  • tabular:///PageWithTabularDataOnCommons.tab - Récupère les ensembles tabulaires de Commons. Doit être utilisé avec "format": {"type": "json", "property": "data"} (ou "meta" ou "fields"). Les données passées au graphe sont déjà traduite dans la langue du wiki.

Par exemple, cet ensemble de données sera passé au graphe dans ce format : 

{
  "meta": [{
    "description": "Women's weekly earnings as a percent of men's by age, annual averages",
    "license_code": "CC0-1.0+",
    "license_text": "Creative Commons Zero",
    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
    "sources": "Copied from [https://www.bls.gov/opub/ted/2006/oct/wk1/art02.txt bls.gov] (United States Department of Labor)"
  }],

  "fields": [{
    "name": "year",
    "type": "number",
    "title": "Year"
  }, {
    "name": "age_16_24",
    "type": "number",
    "title": "16–24 y/o"
  }, ... ],

  "data": [{
    "year": 1979,
    "age_16_24": 78.5,
      ...
  }, ...]
}
  • map:///PageWithGeoJsonDataOnCommons.map - Récupère l'ensemble de données cartographiques de Commons. Doit être utilisé avec "format": {"type": "json", "property": "data.features"} (on peut aussi utiliser "meta" pour obtenir la même information que pour tabular) Les données passées au graphe sont déjà traduite dans la langue du wiki.
  • wikifile:///Albert_Einstein_photo_1921.jpg - Récupère l'image File:Albert_Einstein_photo_1921.jpg à partir de Commons pour une marque d'image. Il est toujours recommandé d'ajouter ?width=... (et / ou height) pour que l'image ait la bonne taille et pour réduire la charge du serveur.
  • OBSOLETE, use wikifile: instead wikirawupload:{{filepath:Albert Einstein photo 1921.jpg}} - Donne une image pour le graphique, par exemple de Commons. Cette balise précise tout contenu provenant du domaine des téléversements uploads.*, sans paramètre de requête. Utilisez le mot-clé magique filepath pour obtenir le chemin du fichier et la taille optionnelle de l'image.
  • wikiraw:///Article%20title/subpage - Donne le contenu brut d'une page de wiki, où le chemin d'accès est le titre de la page. Le domaine est facultatif et, s'il est spécifié, peut être n'importe quel hôte Wikimedia tel que fr.wikipedia.org, commons.wikimedia.org, ...
  • wikiapi:///?action=query&list=allpages - Récupère les données à partir de l'API MediaWiki. Le domaine est facultatif.
  • wikirest:///api/rest_v1/page/... - Appelez l'API RESTbase. Le domaine est facultatif.
  • geoshape:///?ids=408,664 ou geoshape:///?query=SELECT... - Obtenir les représentations cartographiques (comme le Topojson) de régions données, en utilisant les ID Wikidata, ou une requête URL encodée (dans SPARQL), avec la colonne "id" spécifiant les formes géographiques voulue.
  • mapsnapshot:///?width=__&height=__&zoom=__&lat=__&lon=__ [&style=__] - Fait un lien avec le service de photographie cartographique, de sorte qu'une carte statique peut être dessinée pour un lieu/ un zoom/une taille donné. Les paramètres sont convertis en une demande d'image pour Kartotherian - https://maps.wikimedia.org/img/{style},{zoom},{lat},{lon},{width}x{height}@2x.png

Exemples de graphique avec des données externes

Pour voir des exemples fonctionnels de json graph utilisant des données externes vous pouvez utiliser le paramètre debug= des modèles Template:Graph:Lines et Template:Graph:Stacked. Invocation d'un modèle ci-dessous, à titre d'exemple 

{{Graph:Lines
| debug=1
| table=bls.gov/US Women's weekly earnings as a percent of men's by age, annual averages.tab
| type=year | xField=year
| series="age_16_24", "age_25_34", "age_35_44", "age_45_54"
| yZero=false | yMin=50 | yMax=100
}}

va générer le json cohérent de graph 

{
  //
  // ATTENTION: This code is maintained at https://www.mediawiki.org/wiki/Template:Graph:Lines
  //            Please do not modify it anywhere else, as it may get copied and override your changes.
  //            Suggestions can be made at https://www.mediawiki.org/wiki/Template_talk:Graph:Lines
  //
  // Template translation is in https://commons.wikimedia.org/wiki/Data:Original/Template:Graphs.tab
  //

  "version": 5,
  "$schema": "https://vega.github.io/schema/vega/v5.json",
  "width": 400,
  "height": 300,
"padding": "strict",
  "signals": [{"name": "rightwidth", "update": "width + padding.right", "value":"400" }],
  "data": [{
    "name": "chart",
    "url": "https://commons.wikimedia.org/w/api.php?action=jsondata&formatversion=2&title=bls.gov%2FUS+Women%27s+weekly+earnings+as+a+percent+of+men%27s+by+age%2C+annual+averages.tab&format=json&origin=*",
    "format": {"type": "json"
      , "property": "data"
      
    },
    "transform": [


      // Convert xField parameter into a field "_xfield"
      {"type": "formula", "as": "_xfield", "expr":
"datetime(datum.year, 0, 1)"
      },
      {"type": "collect", "sort": {"field": ["_xfield"]} }
, {"type": "fold", "fields": ["age_16_24", "age_25_34", "age_35_44", "age_45_54"]}
, {"type": "formula", "as": "_yfield", "expr": "datum.value" }

    ]
  },
// source of labels for `tabletype=tab`
  {
    "name": "labels",
    "url": "https://commons.wikimedia.org/w/api.php?action=jsondata&formatversion=2&title=bls.gov%2FUS+Women%27s+weekly+earnings+as+a+percent+of+men%27s+by+age%2C+annual+averages.tab&format=json&origin=*",
    "format": {"type": "json", "property": "fields"},
    "transform": [


    ]
  },



  ],
  "scales": [
    {
      "name": "x",
      "type": "time",
      "domain": {"data": "chart", "field": "_xfield"},
      "range": "width",
      

      
    },
    {
      "name": "y",
      "type": "linear",
      "range": "height",
      "domain": {"data": "chart", "field": "_yfield"},
      "zero": false,
      "domainMin": 50,
      "domainMax": 100,
      
    },
    {
      "name": "color",
      "type": "ordinal",
      "range": {"scheme": "category10"}, 
      "domain": {"data": "chart", "field": "key"}
    },
{
      "name": "labels",
      "type": "ordinal",
"domain": {"data": "labels", "field": "name"},
      "range": {"data": "labels", "field": "title"},
    }
  ],

  "axes": [
    {
      "scale": "x", "orient": "bottom", "tickSize": 0,
      "tickCount": 7,
      
      
      
      "encode": { 
        "update": { "labels": { 
          
          
        } } 
       }
    },
    {
      "scale": "y", "orient": "left", "tickSize": 0,
      
      
      
      
      "encode": { 
        "labels": { 
          
          
        } 
       }
    }
  ],

  "marks": [
    // Group data by the group parameter or "key", and draw lines, one line per group
    {
      "type": "group",
      "from": {
        "facet": {
          "name": ["key"],
          "data": "chart",
          "groupby": ["key"]
        }
      },
      "marks": [
        {
          "type": "line",
          "from": {"data": ["key"]},
          "encode": {
            "hover": {
              "stroke": {"value": "red"}
            },
            "update": {
              "stroke": {"scale": "color", "field": "key"}
            },
            "enter": {
              "y": {"scale": "y", "field": "_yfield"},
              "x": {"scale": "x", "field": "_xfield"},
              "stroke": {"scale": "color", "field": "key"},
              "interpolate": {"value": "linear"},
              "strokeWidth": {"value": 2.5}
            }
          }
        }
        
      ],
    },





  ]
}
Voir ou modifier les données brutes du graphique.

Problèmes fréquents

Rappel sur les paramètres des modèles imbriqués

Les modèles exigent que vous sépariez les paramètres des modèles imbriqués par au moins un caractère, sinon le graphique ne s'affichera tout simplement pas et vous obtiendrez une erreur de syntaxe. Faites attention ! 

"values": {{{1|{{#invoke:Graph:Utils|expandDict|{"BR":"pink","US":"blue"} }}}}} // ne va rien générer
"values": {{{1|{{#invoke:Graph:Utils|expandDict|{"BR":"pink","US":"blue"} }} }}} // génère le rendu, remarquez l'espace dans les parenthèses fermantes

Utilisation d'accolades doubles dans les graphiques

Vega 2 prend en charge les paramètres des modèles, tels que "template": "{{indexDate | time: '%b %Y'}}", mais MediaWiki tentera de trouver le modèle "indexDate" pour l'inclure (transclure). Pour éviter cela, utilisez \u007b au lieu de la première accolade, \u007d au lieu de la dernière accolade de fermeture, et le {{!}} au lieu du symbole de pipe "|" : : "\u007b{indexDate {{!}} time: '%b %Y'}\u007d"

Débogage

  • Le meilleur endroit pour développer et déboguer est dans le Bac à sable de Graph. Copiez le code JSON pour voir le graphique changer en temps réel pendant que vous tapez. Le bac à sable de Graph comprend les commentaires de JSON et étend le balisage du wiki. Voir le panneau inférieur droit pour le JSON converti.
  • Pour obtenir le graphique JSON à partir d'un modèle, alors que le graphe est en train de s'afficher, utilisez la ligne d'instruction suivante dans la console de débogage du navigateur (cliquez pour afficher le Json). Si la page contient plus d'un graphique, incrémentez [0] jusqu'à obtenir celui que vous souhaitez. Supprimez le premier et le dernier apostrophe, puis faites un copier / coller dans l'éditeur Vega ci-dessus.
JSON.stringify(Object.values(mw.config.get("wgGraphSpecs"))[0])
  • Dans Google Chrome, ceci copie la chaîne de caractères directement dans le presse papiers [1]:
copy(JSON.stringify(Object.values(mw.config.get("wgGraphSpecs"))[0]))
  • Vous pouvez aussi utiliser le débogueur du navigateur pour inspecter le graphique qui vous intéresse (même s'il ne s'affiche pas) - vous devriez voir quelque chose de similaire à <div class="mw-graph ... data-graph-id="834d6921e69e66a00b40d8606e39e414145f8288" .... Copiez la valeur du hachage, appuyez sur Echap (dans Chrome) et utilisez cette ligne d'instruction pour afficher le code JSON (remplaçant la valeur de hachage par la votre). Supprimez le premier et le dernier apostrophe, puis faites un copier/coller dans l'éditeur Vega au dessus.
JSON.stringify(mw.config.get('wgGraphSpecs')['834d6921e69e66a00b40d8606e39e414145f8288'])
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:Graph/Guide/fr&oldid=6415105"