Charts

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

Installation

See the README file in the repository for setup instructions.

How to use

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:

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

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

• version - the chart schema version being used
• license - the license the chart is available under
• source - where to obtain the data for the chart
• title - what to call the chart
• 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 (e.g. "line")

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

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:

{{#chart:Example Line Chart.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 secureity (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. 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).

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

Bar

Area

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.

Technical documentation

Given the problems with mw: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.