Datawrapper
Datawrapper is a tool that enables to create enticing visualizations in seconds, without any programming skills.
It draws inspiration from ManyEyes and GoogleCharts but remains entirely open-source and independent from a third-party server.
Any developper can add a visualization type, using (or not) a JavaScript library like D3 or Raphael, and a specific theme.
Install
To install Datawrapper on your server, download all files from GitHub or do a 'git pull'. Create the appropriate tables in your database using the .sql dump. Then create a file with your database passwords to be stored in /actions/passwords.php under the form
<?php
$hostname = "hostname";
$database = "database_name";
$username = "user_name";
$password = "password";
?>
Then modify the production domain name in /config.php ('$prod_domain') if you do not host your application on CloudControl.
To-Do
- Remove the hardcoded elements to visualization building
- Improve the responsive table option (auto-resize the iframe)
- Let users modify a previously created chart
- Use an Analytics solution to track a chart's performance
- Add a fallback solution for less compatible JS libs
- Use gettext in JS
Themes
Themes are meant to let organizations create charts that have their own look-and-feel.
Themes are listed in /themes/config.json using the following structure:
"theme_slug":
{
"name": "theme_slug",
"desc": "theme_name",
"image": {
"width": image_width,
"height": image_height,
"format": "image_extension"
},
"restricted": ["domain1", "domain2"]
}
Theme name
'theme_slug' is the identifier of the theme. 'theme_name' is the long form name that will be displayed (no multi-language support).
Theme image
You can specify an image (e.g. the organization's logo) for your theme, to be stored in themes/images/ under the name 'theme_slug'.'image_extension'.
Set "image" to 'null' if you don't have one.
Restrictions
A theme can be restricted to certain users only, using their e-mail address as a filter. 'restricted' is an array of domain names. Only users with an e-mail address from 'domain1' or 'domain2' will be able to use the theme.
Set 'restricted' to 'null' if the theme is free for all to use.
Theme structure
Themes are JS files stored in '/themes/js' under the format 'theme_slug'.js.
They use the structure of Highchart themes
Visualizations
Datawrapper makes it easy to add a new type of visualization.
Visualizations are listed in the file '/visualizations/config.json.php'
Adding a JS library
"d3":
{
"name": "D3.js",
"dependancies": ["d3/d3.js", "d3/d3.layout.js"],
"compatibility": {
"IE": "9.0+",
"FF": "3.0+",
"Chrome": "2.0+",
"Safari": "4.0+"
}
}
'dependancies' is an array of files stored in the '/visualizations/' folder.
'compatibility' lets users know with which browsers the library is compatible. The list of browsers so far only include IE, Firefox, Chrome and Safari. If you haven't tested the library under one of these browsers, just leave the line blank.
Adding a visualization
"pie":{
"name": "pie",
"desc": "'. _("Pie chart").'",
"library": "highcharts",
"vis_code": "pie.js",
"resources":{
"'. _("Understanding Pie Charts").'": "http://eagereyes.org/techniques/pie-charts"
}
}
Each visualization is described in the file 'visualizations/config.json.php'. They have a slug_name ('pie' in this case) and a long-form name users will see, under 'desc'. The long-form name is translated using gettext.
Additionally, a visualization can have "ressources" attached to it, which are links (with titles translated) displayed when users click the question mark next to the visualization when building their charts.
The JS file that adapts the csv data to the visualization's needs is stored in 'vis_code'. Files are stored in 'visualizations/types/vis_code'.
Building a visualization
Visualizations are built in 2 parts. The first part formats the data according to the visualization's needs, the second part builds the actual chart.
The first part is found in the file under 'vis_code'. It takes the variable 'csv_data' and stores the data in the 'options' object.
The second part is built on a ad-hoc basis. In '/js/functions.js', the function render_chart(opt, theme) renders the chart. As of now (see to-do), appropriate functions building the chart are hard-coded. They need to be made dynamic.