Visualization Meta.json Properties

This page documents everything that can be configured in the meta.json descriptors of visualization types in Datawrapper.

title

The name of the visualization as displayed in Datawrapper UI. Datawrapper expects a dictionary in the format { "language": "title" }. Hint: if this property is missing, Datawrapper won't display the visualization in the UI, so renaming the property to, say, "_title" is an easy way to temporarily disable a visualiztion.

Example:

"title": {
    "en": "Bar Chart",
    "de": "Balken (horizontal)",
    "fr": "Diagramme à bandes horizontales"
}

version

The version of the visualization. It is very important to increment the version number every time the visualization code changes, because otherwise new charts are going to run on the previous version. The way it works is this: every time a chart is being published (e.g. sent to Amazon S3), the JS code of the involved visualization is packed and stored on S3 under a file name like lib/donut-chart-1.2.beta.min.js. Once a new version of a vis is published, it will be never overwritten. This ensures that every chart created with a specific version of a chart is still running as expected, and we don't need to worry about backward-compatibility.

Example:

"version": "1.2.2"

requires

If a visualization needs a certain minimum version of Datawrapper in order to work properly, you should specify this using the requires property.

"requires": "1.2.7"

extends

Most visualization types on Datawrapper share common functionality, and extends is how you define which is the "parent" visualization type. This information is used by Datawrapper to load JS and CSS files of the parent visualization before loading the actual visualization. This is very useful if you want to provide visualizations as separate type although they are literally running on the same code. A good example for this is the donut chart which is essentially a pie chart with an inner radius > 0.

Note that it is not enough to define the parent vis in extends, but you need to actually extend from the parent JavaScript class in your visualizations code as well. See donut-chart.js for reference.

Example:

"extends": "pie-chart"

order

This is used to sort the visualizations in the Datawrapper UI.

Example:

"order": 100

dimensions

Describes how many data dimensions the visualization is able to show. Can be set to 1 or 2 at the moment, as Datawrapper doesn't support more than two-dimensional datasets. If set to 1, Datawrapper displays a select element for picking the row that is going to be displayed.

Example:

"dimensions": 2

libraries

If the visualization needs additional JavaScript libraries, they need to be named here. The base path for all the libraries is /www/static/vendor/, so if you include "d3js/d3.min.js" Datawrapper will try to load /www/static/vendor/d3js/d3.min.js.

Example:

"libraries": [
    "d3js/d3.light.js",
    "raphaeljs/raphael-2.1.0.min.js"
]

options

Here you can define additional options provided by the visualization. Everything defined here will be displayed in the visualization specific options. The first level is a key-value store, where the keys define the ID of each option an the values describe them.

type: checkbox

Adds a simple yes/no choice in form of a checkbox.

"my-option": {
    "type": "checkbox",
    "default": true,
    "label": {
        "de": "...", "en": "...", "fr": "...", ...
    }
}

type: radio

Adds a simple yes/no choice in form of a checkbox.

"legend-position": {
    "type": "radio",
    "label": {
        "en": "Legend position", "fr": "...", "de": "..."
    },
    "options": [{
        "value": "right",
        "label": {
            "en": "right",
            "de": "rechts",
            "fr": "à droite"
        }
    },{
        "value": "top",
        "label": {
            "en": "top",
            "de": "oben",
            "fr": "en haut"
        }
    },{
        "value": "inside",
        "label": {
            "en": "inside",
            "de": "innen",
            "fr": "dedans"
        }
    }],
}

type: text

Allows the user to enter a string which can be shown in the visualization.

"my-option": {
    "type": "text",
    "label": {
        "de": "...", "en": "...", "fr": "...", ...
    }
}

Conditional options

Sometimes you need options only to be displayed under certain conditions. For instance, you don't need the text field for displaying a custom value if the checkbox "show custom value" is set to false. You can define such dependencies using the depends-on property of each option.

"show-custom-value": {
    "type": "checkbox"
},
"custom-value": {
    "type": "text",
    "depends-on": {
        "show-custom-value": true
    }
}

locale

Some visualizations need to display localizable text, such as "other" in pie charts or "stack percentages" in stacked column charts. These are not defined in core locale but in each visualizations meta.json. If a visualization extends another visualization it will inherit its locale, so the donut chart doesn't need to define "other", too.

"locale": {
    "other": { "de": "andere", "fr": "autre" }
}

color-by

By default the custom color selector in Datawrapper will allow users to define custom colors for each data series. Some visualizations, however, need different color strategies. In grouped column charts, color is needed to differentiate between the groups, for instance. Currently supported modes are "series", "row", and "hierarchy".

"color-by": "row"