Extension:Graph
Graph Release status: beta |
|||
---|---|---|---|
Implementation | Tag, ContentHandler | ||
Description | Data-driven graphs | ||
Author(s) | Yuri Astrakhan, Dan Andreescu, Frédéric Bolduc (yuriktalk) | ||
License | MIT License | ||
Download | |||
|
|||
Translate the Graph extension if it is available at translatewiki.net |
|||
Check usage and version matrix; code metrics | |||
Open tasks · Report a bug |
The Graph extension allows a <graph>
tag to describe data visualizations (demo) in a JSON format that renders a Vega-based graph.
Contents
General info[edit | edit source]
- See 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).
- Guide - General recommendations on how to use graphs in Wiki.
- Vega for devs - best place of all Vega resources
Installation[edit | edit source]
- If using Vagrant , install with
vagrant enable-role graph && vagrant 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' );
- Special:Version on your wiki to verify that the extension is successfully installed. Done - Navigate to
To users running MediaWiki 1.24 or earlier:
Those instructions describe the new way of installing extensions since MediaWiki 1.25. If you need to install this extension in earlier versions, instead of wfLoadExtension( 'Graph' );
, you need to use:
require_once "$IP/extensions/Graph/Graph.php";
Known bugs & limitations[edit | edit source]
- Total Graphs per page cannot be more than 64KB T100942.
- Graph extension bugs
- Graphoid service bugs
Internals[edit | edit source]
When parsing, 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 way graphs can be easily located on the wiki with propname=graph_specs the special page (or via API). The client browser receives graph definitions as JSON MW values. Additionally, HTML contains empty <div> elements in place where graphs should go:
<div class="mw-wiki-graph" data-graph-id="3cbe2b968108670c001e230dca4682a9d03f8814"></div>
Once everything is loaded into the browser, vega populates each <div> with a graph canvas.
Additionally, graph extension inserts an <img> tag with the HREF pointing to the #Graphoid Service. The image tag will only execute in case of the <noscript> browser, or legacy browser that MediaWiki does not support by using document.write(...).
Alternativelly, Graph extension may be configured to always use just the <img> tag, without adding 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, Graphoid service will be able to access the new definition via MW API.
Security Features[edit | edit source]
<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.
License[edit | edit source]
Vega library is distributed under a modified BSD license acceptable under for us to use.
“ |
This appears to be a copy of the 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. |
” |
—Stephen LaPorte |
Configuration[edit | edit source]
wgGraphDataDomains[edit | edit source]
A list of domains (strings) that the vega code is allowed to pull data from, or false for no restrictions. An empty list disables any external data (inline only). Empty list by default.
- NOTE
- Setting this value to anything other than 'false' will also enable safe mode formula/filter evaluation
wgGraphUrlBlacklist[edit | edit source]
A list of regular expressions (JavaScript regex). All data URLs will be matched against this list, and the URL will be used only if it does not match any of the given regexes. false (default) to disable.
wgGraphIsTrusted[edit | edit source]
If false (default), passes Treat-as-Untrusted:1 header with all graph data requests
wgGraphImgServiceUrl[edit | edit source]
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
wgGraphImgServiceAlways[edit | edit source]
If true, and wgGraphImgServiceUrl is set, renders all graphs on the backend if possible.
Enabling Graph namespace[edit | edit source]
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 service[edit | edit source]
Graphoid (git repo) is a node.js service that converts a graph definition into a PNG image using the same Vega library code that runs in advanced browsers. The service is available on the Wikimedia cluster at graphoid.wikimedia.org.
You can install it yourself:
$ git clone https://gerrit.wikimedia.org/r/mediawiki/services/graphoid
$ cd graphoid
$ npm install
$ npm start
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:19000/mediawiki.org/v1/PageTitle/12345/a64b022a8fa5b7fc5e40a2c95cd0a114b2ae1174.png http://graphoid.wikimedia.org/mediawiki.org/v1/png/Extension:Graph/0/be66c7016b9de3188ef6a585950f10dc83239837.png
You configure the Graph extension to use the Graphoid service in LocalSettings.php with a line like
$wgGraphImgServiceUrl = "//localhost:19000/%1\$s/v1/%2\$s/%3\$s/%4\$s.png";
$wgGraphImgServiceUrl = "//graphoid.wikimedia.org/%1\$s/v1/png/%2\$s/%3\$s/%4\$s.png";
You can further configure the service via its config file.
VisualEditor module[edit | edit source]
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 here for more details.
This module enables graph rendering within VisualEditor, allowing users to see graphs within the editor as opposed to alien extension nodes. Furthermore, users can open up a UI to edit a graph's type, data and padding. The UI also offers a way to edit the 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. |