Vizabi documentation
What is Vizabi?
Gapminder Vizabi is our framework for developing maintainable visual exploration tools. It has support for mobile devices, responsiveness, localization, embedding and unified data schema.
You can freely use Vizabi to:
- embed our chart into your web page (and modify the options if you like);
- create a new chart based on your data;
- extend any of our charts to create your own, or create one from scratch.
Downloading
See the changelog to keep track of what’s new in the current version.
There are different alternatives for downloading the Vizabi library files:
-
Direct Download , the zip archive contains JavaScript and CSS files required to run Vizabi.
-
Via NPM package manager using:
npm install vizabi --saveEmbedding
Bubble chart
You can embed a Vizabi tool on your page or blog and tell your story with our graph:
In the following example, Vizabi BubbleChart will appear in the div placeholder
<link rel="stylesheet" type="text/css" href="path/to/vizabi.css">
<script src="path/to/vizabi.js"></script>
<div id='placeholder' width="600px" height="400px"></div>
<script>
var viz = Vizabi('BubbleChart', document.getElementById('placeholder'), {
state: {
},
data: {
reader: 'reader-type',
path: '/path/to/your/file'
// for inline reader you can specify your data manually
/*
data: [
{
column: 'value'
},
...
]
*/
},
ui: {
buttons: ['find', 'colors', 'fullscreen']
}
});
</script>Line chart
Similarly, you can also embed our line chart.
In the following example, Vizabi LineChart will appear in the div placeholder
Vizabi('LineChart', document.getElementById('placeholder'), {
state: {
},
data: {
reader: 'reader-type',
path: '/path/to/your/file'
},
ui: {
buttons: ['find', 'colors']
}
});Responsiveness
Responsiveness
You can also embed the chart in a placeholder with flexible width. Resize the browser window to see the effect on the previous chart or view the example on Codepen. Styling and layouting of the bubble chart tool will change.
<div id='placeholder' style='position: absolute; top: 0; bottom: 0; left: 0; right: 0;'></div>If on a mobile, just flip your device.
Tuning
Colors
Vizabi tools are crafted to be highly customisable. You can enable or disable features and do all sorts of tuning. Let’s hack the color of regions.
Vizabi Initialization:
Vizabi('BubbleChart', document.getElementById('placeholder'), {
state: {
"marker": {
"color": {
"palette": {
"asi": "teal",
"ame": "limegreen",
"eur": "red",
"afr": "deepskyblue"
}
}
}
}
});This state → marker → color → palette sequence is rather obscure. Read the bubble chart default state here to see what is possible to change.
Indicators
One strong side of Vizabi framework is that you can change the displayed indicators as easily as you change colors. Let’s set X axis to show population and color to show life expectancy:
Vizabi('BubbleChart', document.getElementById('placeholder'), {
state: {
"marker": {
"color": {
"use": "indicator",
"which": "lex"
},
"axis_x": {
"use": "indicator",
"which": "pop"
}
}
}
});Entities
We can also select which entities will be visible on the chart. In the next example we make the graph display only the Nordics and color them so that they look different:
Vizabi('BubbleChart', document.getElementById('placeholder'), {
state: {
"entities": {
"show": {
"filter": {
"geo": [ "dnk", "fin", "isl", "nor", "swe"]
}
}
},
"marker": {
"color": {
"use": "property",
"which": "geo"
}
}
}
});Language
Vizabi framework supports localisation. In the following example we switch the language to Swedish and provide a few language strings:
Vizabi('BubbleChart', document.getElementById('placeholder'), {
language: {
id: "se",
strings: {
se: {
"title": "Bubblar titel",
"indicator/lex": "Livslängd",
"indicator/gdp_per_cap": "BNP per capita",
"indicator/pop": "Befolkning",
"indicator/geo.region": "Region",
"indicator/geo": "Geo kod",
"indicator/time": "Tid",
"indicator/geo.category": "Geo kategori",
"scaletype/linear": "Linjär",
"scaletype/log": "Logaritmisk",
"scaletype/time": "Tid",
}
}
}
});The same customization options (color, entities, indicator, language) also work for the other charts. Learn more about the available options for line chart or bar chart.
Creating own tool
Read our blog post: Creating your own tool
Vizabi Framework
As a framework, Vizabi provides a number of features in order to ease development of new tools, while maintaining consistency between them.
When you add Vizabi to a page, Vizabi will be added to the global scope.
<script type="text/javascript" src="path/to/vizabi.js"></script>
<script type="text/javascript">
console.log(Vizabi);
</script>You can use it to initialize existing tools, like the BubbleChart or LineChart, or extend the framework with new functionality.
Vizabi.Class
Provides basic prototype inheritance to all Vizabi classes. It also provides the useful method _super, which can be used to call the super class method.
var Animal = Vizabi.Class.extend({
init: function() {
this.alive = true;
},
move: function() {
return "It is moving";
}
});
var Dog = Animal.extend({
init: function() {
this.barking = true;
this._super(); //calls super init
}
});
var doug = new Dog();
//expect doug.alive = true
//expect doug.move() to return "It is moving"It also allows classes to be registered in collections. This is particularly useful when defining reusable components.
Animal.extend('Cat', {
init: function() {
this.smart = true;
this._super();
}
});
var animals = Animal.getCollection();
//expect animals to contain 'Cat'
var myCat = new Animal.get('Cat');
//myCat is an instance of CatVizabi.utils
Provides basic utility functions. See all here. Example:
var u = Vizabi.utils.unique([1,2,2,2,2,3]);
//u = [1, 2, 3]Vizabi.Promise
Basic promises implementation. Example:
var promise = new Vizabi.Promise();
promise.then(function() {
console.log('done');
});
promise.resolve();Vizabi.Events
Base class for events. It provides useful functionality such as on and trigger:
var myEvents = new Vizabi.Events();
myEvents.on("shout", function() {
console.log("Hello World");
});
myEvents.trigger("shout");
//prints "Hello World" to console;It also allows for more advanced binding formats and triggering multiple events:
var myEvents = new Vizabi.Events();
myEvents.on({
"shout": function() {
console.log("Hello World");
},
"shout:loud": function() {
console.log("HELLO WORLD!");
}
);
myEvents.trigger("shout:loud");
//prints "HELLO WORLD!" to console;
myEvents.triggerAll("shout:loud");
//prints "HELLO WORLD!" and "Hello World" to console;Vizabi.Model
Base class for models. It extends Vizabi.Events. Models come with basic setters and getters. It also triggers special events.
var m = new Vizabi.Model({
value: 1800,
start: 1800,
end: 2015,
submodel: { //objects become submodels
value: "test"
}
});
console.log(m.value); //prints "1800" to console;
m.on('change:value', function() {
console.log("value changed!");
});
m.value = 1990;
//triggers 'change:value' and prints "value changed!" to consoleThere are some special models that we call hooks. They have the properties use and which and they are used to bind a model to data. These types of models have super powers. They can request data and map data points. There’s a section dedicated to these types of models.
Extending Vizabi.Model
Vizabi comes with many built-in models/hooks. You can find them under src/models . All of them extend Vizabi.Model. You can also create your own model like this:
var myModel = Vizabi.Model.extend({ /*methods*/ });And you can register your model (if reusable):
Vizabi.Model.extend('mymodel', { /*methods*/ });Vizabi built-in models use the later syntax. You can also see all registered models with Vizabi.Model.getCollection().
Validation
All models execute validation after any change. This is useful to guarantee consistency. Check out the example below
var MyModel = Vizabi.Model.extend({
init: function(values, parent, bind) {
//defaults
values = Vizabi.utils.extend({
value: 1800, start: 1800, end: 2015,
}, values);
this._super(values, parent, bind);
},
//validate is always called after changing the model
validate: function() {
if(this.start > this.end) this.end = this.start;
if(this.value > this.end || this.value < this.start)
this.value = this.start;
}
});
m = new MyModel({ start: 2000, end: 2010, value: 2020 });
m.value; //should be 2000 because of validation ruleVizabi.Tool
Vizabi tools are the ultimate wrapper, the final packaging of our components. Think of it as an app. Vizabi.Tool extends Vizabi.Component, so they are essentially a component (which means they can render and include components) with an extra touch.
Vizabi tools have default_options, which basically describe the entire model structure of the tool and include other models. Moreover, they have a special model and template. Finally, they have their own validate method which allows for cross model validation.
For more details, checkout how LineChart is implemented.
Built-in tools
Vizabi currently ships with three built-in Tools: BubbleChart, LineChart and BarChart.
You can initialize registered tools with the following:
Vizabi("<ToolName>", document.getElementById("<id_placeholder>"), {
/* options */
});Contributing
You can be part of our adventure
You can run Vizabi source code on your machine, and contribute to the development of tools or the framework.
Here are some of the things we would love to improve:
- Development of awesome visualization tools
- Improvement of QA and testing routines
- More readers that support various data formats
- More buttons and UI controls
- Offline version for Windows and Mac