Extension:Chart

MediaWiki extensions manual

Chart Release status: unstable
Implementation	Tag
Description	Renders charts
Author(s)	TODO
Compatibility policy	Master maintains backward compatibility.
MediaWiki	>= 1.43.0
Database changes	No
License	GNU General Public License 3.0 or later
Download	Download extension Git [?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review README
Parameters $wgChartCliPath $wgChartServiceUrl $wgChartProgressiveEnhancement
Hooks used ParserFirstCallInit
Quarterly downloads	2 (Ranked 137th)
Translate the Chart extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

The Chart extension is a project to replace the Graph extension. The extension is currently in development. See Extension:Chart/Project for more details on the development process.

Installation

See the README file in the repository for setup instructions.

How to use

This documentation is duplicated on the beta cluster where you can see live examples while we get this extension up and running in production.

All the charts in this example can be rendered from the same data source Data:Chart_Example_Data.tab, a fictional dataset. Sample contents for these pages can be found in the sample directory.

To render a chart, you will need to define a chart definition to associate with the data source you want to render.

The extension supports the following chart types:

• Bar chart
• Pie chart
• Line chart
• Area chart

A chart definition is relatively simple. In the chart definition define the following:

• source – where to obtain the data for the chart.
• license – the license the chart is available under
• xAxis title – what to label the x axis with
• yAxis title – what to label the y axis with
• type – the type of chart that is being rendered, for different chart types you will need to clone a chart definition.

{
    "license": "CC0-1.0",
    "version": 1,
    "type": "line",
    "xAxis": {
        "title": {
        	"en": "Date"
        }
    },
    "yAxis": {
        "title": {
            "en": "%support",
            "fr": "%soutien"
        }
    },
    "source": "Chart Example Data.tab"
}

Once a chart is defined you can render it easily using the chart parser function. In this case, the chart is defined in Data:Example.Line.chart:

{{#chart:Example.Line.chart}}

Customization

Customization will be extremely limited in the initial proof of concept. We are hoping to use a set of pilot wikis trying out this feature to discuss and evaluate the different needs of our project to find solutions that do not compromise accessibility, device needs (e.g. responsive behaviours) and security (e.g. cannot be abused).

Sizing

Currently charts will occupy the full width of the container you place them in.

We want to ensure that charts can be rendered in a legible manner no matter what device they are read on and we are still thinking through this carefully in T376845

Theming

Currently charts are restricted to a single color palette. This color palette has been carefully designed to consider accessibility needs of our readers. The thinking that went into these colors can be explored in T369863.

We acknowledge that some charts require specific color themes, for example representing data relating to political parties and we will continue to explore ways we can support this type of customization without compromising the ability for readers with accessibility needs (e.g. color blindness) to use them.

Internationalization

The chart format supports different languages and these must be defined inside the chart definition. See this example of the same chart with a Spanish legend. The use of the uselang querystring (e.g. ?uselang=es doesn't impact the chart).

We do not support embedding charts in a language different to the content language.

Known issues

Currently, charts do not adjust to RTL display (phab:T375575), and numbers do not appear localized (phab:T375574).

Types of chart

The following examples will not render until Charts is available in production. For all charts, data is expected to be arranged in columns where the first column represents the x axis, and the columns that follow represent series on the Y axis.

Line

{{#chart:Example.Line.chart}}

Bar

{{#chart:Example.Bar.chart}}

Area

{{#chart:Example.Area.chart}}

Pie

Pie charts are a special type of chart and data sources may require modification to render appropriately.

When reading data, any non-number columns (e.g. X axis) will be discarded and the sum of all rows will be represented on the chart.

For example, in the example where you have multiple rows depicting values for A, B and C on multiple dates e.g. January 1st, January 2nd, the pie chart segment for A will represent the sum of all A's row values across those dates.

{{#chart:Example.Pie.chart}}

Technical documentation

Given the problems with Extension:Graphs, careful consideration has gone into all the decisions into the new extension with the hope of building trust and confidence in its replacement.

You can read through the technical decisions that have been made so far in the code repository in the docs/adr folder.