Extension:Graph

The Graph extension allows a  tag to describe data visualizations such as bar charts, pie charts, timelines, and histograms (1>Special:MyLanguage/Extension:Graph/Demo|demo) in a JSON format that renders a Vega-based graph.

General info
Graph extension allows powerful Vega based graphs to be added to the wiki pages. Graphs can be both static and interactive.

The easiest way to add a graph is to use a ready-made template such as. These templates hide all Vega complexities. Power users can use the Graph Sandbox to develop graphs. Graph sandbox allows wiki template syntax in addition to JSON.

Useful links

 * Vega 2 documentation - restored Vega 2 documentation pages.


 * - General recommendations on how to use graphs in Wiki.


 * - step by step instructions how to build a complex interactive graph from scratch


 * - for many samples and usage tricks


 * [https://www.youtube.com/watch?v=j7DTn9jHnI0 TechTalk Video] - a WMF tech talk discussing the Graph extension, including a great demo of the [http://idl.cs.washington.edu/projects/lyra Lyra editor] (also installed [http://lyra.wmflabs.org/ on labs]).


 * You may also be interested in some of the Vega [https://www.youtube.com/watch?v=GdoDLuPe-Wg future capabilities] (Keynote by Jeffrey Heer).


 * [http://vega.github.io/ Vega for devs] - best place of all Vega resources




 * [https://www.youtube.com/watch?v=Y8Fp9z-9DWc Video introduction into interactive Vega]

Additional config setup
If you are looking to replicate a production environment like en.wiki you will need to complete the following steps:

Roles


 * Enable graphs role


 * Enable scribunto role


 * Enable imagemap role

Templates and Lua Modules


 * Copy Module:Graph locally


 * Copy Module:Graph/doc locally


 * Copy Template:Nowrap locally


 * Copy Module:Chart locally


 * Copy Module:Chart/Default_colors locally.
 * Copy File:Circle_frame.svg locally

Charts examples
See for many samples and usage tricks.

User defined fallback
When using client side rendering, it is possible to use Wikimedia Commons to provide a static fallback image to  </> users. This is a temporary solution until a new service is put in place to provide server side rendering to replace the soon to be decomissioned Graphoid service.

The user must first upload the static graph to Wikimedia Commons.

Fallback images have two variables <tvar|1> </> and <tvar|2> </>.

<tvar|1> </> relates to a Wikimedia Commons filename.

<tvar|1> </> is the fallback images width in pixels.

These variables are pass through the graph in the following way:

Where lua modules are used such as <tvar|1>Module:Graph</> then these variables can be provided via the tag function. If <tvar|1></> were adapted, it would look like this:

It would then be utilised in a template in the following manner:

If a fallbackWidth isn't provided but an image is defined then the extension will derive the width from the provided graph width. The reason for this is there is frequently a difference in the rendered image width and the actual image width.

External data
HTTP(S) protocol cannot be used to get data for the graph. Instead, use one of the custom guide>Special:MyLanguage/Extension:Graph/Guide#External_Data</>|wiki protocols like,  , and others.

Graphoid service and Graph extension use <tvar|gad> </> setting to control how these protocols are resolved: Note that because queries rely on the structure of wikibase items, they may suddenly stop working if the underlying data is edited and changes, as it may yield incomplete, empty or invalid data that can't be used to create a graph. In these cases the graph will end up empty (see T168601).

Known bugs & limitations

 * [<tvar|bugs1>https://phabricator.wikimedia.org/tag/graph/</> Graph extension] bugs
 * [<tvar|bugs2>https://phabricator.wikimedia.org/tag/graphoid/</> Graphoid service] bugs
 * Fails to implement ISO 8601 timescales so only Gregorian calendars can be used in timelines


 * Image upscaling on most browsers can be blurry by default. Set the appropriate <tvar|1>image-rendering</> property to solve.

Internals
When parsing, the Graph extension expands all template parameters/expressions, and stores the complete graph definitions in the  page property, using graph hashes for IDs. This means you can easily locate a wiki's graphs with either [<tvar|spec-page>https://www.mediawiki.org/wiki/Special:PagesWithProp?propname=graph_specs</> Special:PageWithProps] or [<tvar|api>//www.mediawiki.org/w/api.php?action=query&list=pageswithprop&continue=&formatversion=2&pwppropname=graph_specs</> the action API].

The graph extension adds HTML to the page where graphs should go, a <tvar|div></> containing an <tvar|img></> tag. Sample:

The <tvar|img></> tag's  attribute points to the 1>#Graphoid service</>|#Graphoid service, which provides a [//www.mediawiki.org/api/rest_v1/page/graph/png/Extension%3AGraph%2FDemo/1686336/d243aa924db2f82926e0f317217fcce591fe8cd4.png static image of the graph].

If the Graph extension is configured for interactivity, and if the client browser has JavaScript enabled and is not a legacy browser to which ResourceLoader does not ship JavaScript, then the client browser renders graphs on the fly. The Graph extension adds an <tvar|1> </> ResourceLoader JavaScript module to the page that includes the Vega library, and puts the JSON of graph definitions into a JavaScript 2>Special:MyLanguage/ResourceLoader/Core_modules#mediaWiki.config</>| variable named <tvar|3> </>. Once the client has loaded this module, the Vega JavaScript library populates each <tvar|div></> with an HTML canvas and draws the graph in it, replacing the static image. , Wikimedia wikis only enable this interactive rendering for edit preview.

You can configure the Graph extension to always use just the <tvar|img></> tag, and not add the Vega libraries or graph definition JSON. This mode will not work during editing, since <tvar|code> </> do not get updated until after the save. Once saved, the Graphoid service will be able to access the new graph definition via the action API.

Security features
can be configured to disallow referencing untrusted data sources (e.g. Wikimedia only allows data from the Wikimedia sites). It can also send extra headers whenever accessing external data, e.g.  header that MediaWiki uses to prevent CSRF attacks.

License
Vega library is distributed under a [<tvar|license>https://github.com/vega/vega/blob/master/LICENSE</> modified BSD license] acceptable under for us to use.

bsd>http://opensource.org/licenses/BSD-3-Clause</> BSD license], with some minor (acceptable) modifications. It's not a problem for us to use it, although ideally they would not make changes like this to the license. It's better if people do not make these changes to their license, to avoid confusion (like this) about whether the license is safe for open-source use.

wgGraphIsTrusted
If  (default), passes Treat-as-Untrusted:1 header with all graph data requests

wgGraphImgServiceUrl
A format string to form a backend service request URL for the &lt;img> tag. For example:

Would produce this URL:

//graphoid.wikimedia.org/mediawiki.org/v1/png/Extension:Graph/0/be66c7016b9de3188ef6a585950f10dc83239837.png /{domain}/v1/png/{title}/{revid}/{hash}.png

Parameters will be supplied in this order: 1=server, 2=title, 3=revid, 4=graph-hash-id. All parameters will be escaped with rawurlencode. If the value is  (default), no <tvar|1></> urls will be generated

Other variables
<tvar|var1>wgGraphUrlBlacklist</> variable has been removed in <tvar|url1>787d64a11</> (7 Dec 2015).

<tvar|var2>wgGraphDataDomains</> has been removed in <tvar|url2>e0813f85a</> (28 Jan 2016). Use a <tvar|var3>wgGraphAllowedDomains</> instead.

<tvar|var>wgGraphUserServiceAlways</> variable has been removed in <tvar|url>b735f63ff4b</> (30 Sep 2015).

Enabling Graph namespace
To store graph definitions as standalone pages in their own namespace, configure <tvar|ext></>.

Graphoid service
Graphoid is a node.js  service that converts a graph definition into a static PNG image using the same [<tvar|vega>http://vega.github.io/vega/</> Vega] library code that runs in advanced browsers. The reason Graphoid was initially developed was to provide a static image so we wouldn't have to bundle Vega and d3 resource loader modules with every page response. See <tvar|1>T211881</> for more details. The service is available on the Wikimedia cluster at <tvar|graphoid>https://www.mediawiki.org/api/rest_v1/#/Page%20content/get_page_graph_png__title___revision___graph_id_</>.

You can install it yourself:

(note: this package is not being maintained (T211881, and installation may fail, see T196001, T239100. npm i --build-from-source may help.)

The service URLs contain the domain of the page (for example mediawiki.org), service version (v1), the title of the page with the graph (PageTitle), revision ID of the page (12345, but could be 0 for current), and a hash ID of the graph itself (also used in HTML page to identify graph definition), for example:

http://localhost:6927/mediawiki.org/v1/PageTitle/12345/a64b022a8fa5b7fc5e40a2c95cd0a114b2ae1174.png (deprecated url)

https://www.mediawiki.org/api/rest_v1/page/graph/png/Extension%3AGraph/3420825/72edc224f0a10b343c1e84f63dbfc97cac9bc957.png

You configure the Graph extension to use the Graphoid service in LocalSettings.php with a line like

Configure graphoid services


You can further configure the service via its config file.

VisualEditor module
Since summer 2015, the Graph extension also comes with a module (ext.graph.VisualEditor) which enables graph editing within 1>Special:MyLanguage/VisualEditor</>|VisualEditor.

This module was a result of a Google Summer of Code 2015 project. See <tvar|1>T89287</> for more details.

This module allows users to see graphs within VisualEditor, as opposed to alien extension nodes. Furthermore, users can open up a dialog to edit a graph's type, data and padding. The UI also offers a way to edit a graph's raw JSON specification within VE without having to switch to the classic wikitext editor, in case more advanced users want to tweak settings not supported by the UI.

This first step serves as a stepping stone for many possibilities with graph editing within VisualEditor, and there are a lot of ways in which the module can be improved and expanded.