Extension:Graph
Graph Release status: stable |
|
---|---|
Implementation | Tag , ContentHandler |
Description | Data-driven graphs |
Author(s) | Yuri Astrakhan (Yurik talk), Dan Andreescu, Frédéric Bolduc |
License | MIT License |
Download | |
Translate the Graph extension if it is available at translatewiki.net | |
Check usage and version matrix. | |
Issues | Open tasks · Report a bug |
The Graph extension allows a <graph>
tag to describe data visualizations such as bar charts, pie charts, timelines, and histograms (demo) in a JSON format that renders a Vega-based graph.
General infoEdit
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 {{Graph:Chart}}. 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 linksEdit
- Guide - General recommendations on how to use graphs in Wiki.
- Interactive Tutorial - a step by step instructions how to build a complex interactive graph from scratch
- Demo page - for many samples and usage tricks
- TechTalk Video - a WMF tech talk discussing Graph extension, including a great demo of Lyra editor (also installed on labs).
- You may also be interested in some of the Vega future capabilities (Keynote by Jeffrey Heer).
- Vega for devs - best place of all Vega resources
- Migrating to Vega 2.0
- Video introduction into interactive Vega
InstallationEdit
- If using Vagrant , install with
vagrant roles enable graph --provision
- Manual installation
- Requires JsonConfig extension
- Download and place the file(s) in a directory called
Graph
in yourextensions/
folder.
- Add the following code at the bottom of your LocalSettings.php:
wfLoadExtension( 'Graph' );
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
To users running MediaWiki 1.24 or earlier:
The instructions above describe the new way of installing this extension using wfLoadExtension()
. If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'Graph' );
, you need to use:
require_once "$IP/extensions/Graph/Graph.php";
Charts examplesEdit
External dataEdit
HTTP(S) protocol cannot be used to get data for the graph.
Instead, use one of the custom wiki protocols like wikiraw:
, wikiapi:
, and others.
Graphoid service and Graph extension use GraphAllowedDomains
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 phab:T168601).
$wgGraphAllowedDomains = [
# http + https keys lists all of the domains allowed for the external data access.
# Any domain listed here automatically permits all subdomains as well.
# Custom protocols like 'wikiraw' use it to determine which protocol to use.
# This way wikiraw://en.wikipedia.org/Page will be an api request to https://en.wikipedia.org/w/api.php?action=query&titles=Page&...
'https' => [ 'wikipedia.org', 'wikimedia.org', ... ],
'http' => [ 'wmflabs.org', ... ],
# list of domains allowed for the wikirawupload: protocol access.
# Exact match only, no subdomains.
'wikirawupload' => [ 'upload.wikimedia.org' ],
# same as wikirawupload but for Wikidata Sparql queries
'wikidatasparql' => [ 'query.wikidata.org' ],
];
Known bugs & limitationsEdit
- Graph extension bugs
- 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 image-rendering property to solve.
InternalsEdit
When parsing, the Graph extension expands all template parameters/expressions, and stores the complete graph definitions in the graph_specs
page property, using graph hashes for IDs.
This means you can easily locate a wiki's graphs with either Special:PageWithProps or the action API.
The graph extension adds HTML to the page where graphs should go, a <div>
containing an <img>
tag.
Sample:
<div class="mw-wiki-graph-container">
<img class="mw-wiki-graph-img"
src="/api/rest_v1/page/graph/png/Extension%3AGraph%2FDemo/1686336/d243aa924db2f82926e0f317217fcce591fe8cd4.png" />
</div>
The <img>
tag's href
attribute points to the #Graphoid service, which provides a 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 ext.graph
ResourceLoader JavaScript module to the page that includes the Vega library, and puts the JSON of graph definitions into a JavaScript mediaWiki.config
variable named wgGraphSpecs
.
Once the client has loaded this module, the Vega JavaScript library populates each <div>
with an HTML canvas and draws the graph in it, replacing the static image.
As of November 2015[update]}}, Wikimedia wikis only enable this interactive rendering for edit preview.
You can configure the Graph extension to always use just the <img>
tag, and not add the Vega libraries or graph definition JSON.
This mode will not work during editing, since page_props
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 FeaturesEdit
<graph>
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. Treat-as-Untrusted
header that MediaWiki uses to prevent CSRF attacks.
LicenseEdit
Vega library is distributed under a modified BSD license acceptable under for us to use.
“ | 600 | ” |
ConfigurationEdit
wgGraphIsTrustedEdit
If false
(default), passes Treat-as-Untrusted:1 header with all graph data requests
wgGraphImgServiceUrlEdit
A format string to form a backend service request URL for the <img> tag. For example:
"//graphoid.wikimedia.org/%1\$s/v1/png/%2\$s/%3\$s/%4\$s.png"
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 false
(default), no <noscript>
urls will be generated
wgGraphUrlBlacklist variable has been removed in 787d64a11 (7 Dec 2015), wgGraphDataDomains has been removed in e0813f85a (28 Jan 2016). Use a wgGraphAllowedDomains instead.
wgGraphUserServiceAlways variable has been removed in b735f63ff4b (30 Sep 2015).
Enabling Graph namespaceEdit
To store graph definitions as standalone pages in their own namespace, configure JsonConfig .
// See https://www.mediawiki.org/wiki/Extension:JsonConfig
$wgJsonConfigModels['graph.jsonconfig'] = 'graph\Content';
$wgJsonConfigs['graph.jsonconfig'] = array(
'namespace' => <PICK-A-NS-NUMBER>,
'nsName' => 'Graph',
'isLocal' => true,
);
Graphoid serviceEdit
Graphoid (git repo) is a node.js service that converts a graph definition into a static PNG image using the same 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 phab:T211881 for more details. The service is available on the Wikimedia cluster at https://www.mediawiki.org/api/rest_v1/#/Page%20content/get_page_graph_png__title___revision___graph_id_.
You can install it yourself:
$ sudo apt-get install libcairo2-dev libjpeg8-dev libpango1.0-dev libgif-dev build-essential g++
$ git clone https://gerrit.wikimedia.org/r/mediawiki/services/graphoid
$ cd graphoid
$ npm install
$ npm start
(note: this package is not being maintained (phab:T211881, and installation may fail, see phab:T196001 , phab: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)
You configure the Graph extension to use the Graphoid service in LocalSettings.php with a line like
$wgGraphImgServiceUrl = "//localhost:6927/%1\$s/v1/%2\$s/%3\$s/%4\$s.png"; //deprecated path, older versions only
$wgGraphImgServiceUrl = "//graphoid.wikimedia.org/%1\$s/v1/png/%2\$s/%3\$s/%4\$s.png"; //deprecated path, older versions only
Configure graphoid servicesEdit
You can further configure the service via its config file.
VisualEditor moduleEdit
Since summer 2015, the Graph extension also comes with a module (ext.graph.VisualEditor) which enables graph editing within VisualEditor.
This module was a result of a Google Summer of Code 2015 project. See phab: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.
This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |
See alsoEdit
- Extension:GraphViz — for displaying graphs of sets of vertices connected by edges (i.e. not charts, like this extension)
- Plotly — The open source JavaScript graphing library (with 3d charting capabilities)
- D3 — Data-Driven Documents