-
Notifications
You must be signed in to change notification settings - Fork 556
Home
dimple is a library to aid in the creation of standard business visualisations based on d3.js.
The intention is to make the basics easier, while still exposing the d3 components so that you can go off-piste when you get a bit more familiar. The target audience for this is advanced analysts who don't necessarily consider themselves highly proficient in JavaScript but want to build some axis based visualisations.
You must include d3.js in any pages in which you wish to use dimple.
The dimple api is tested against Firefox, Chrome, Safari and IE9. It's browser support is largely inherited from d3 so using it on IE8 and earlier will be difficult/impossible.
The source files for dimple are split across multiple *.js files and combined by grunt. If you would like to develop this project we recommend that you begin by [forking this repository] (/PMSI-AlignAlytics/dimple/fork "Fork Me").
Next you will need to install node.js, if you are not already using it.
The final tool required is grunt. This is installed from the node.js shell using the command:
npm install -g grunt-cli
Having installed grunt CLI, navigate to the root of the dimple repository in the node.js shell and install dependencies (defined in package.json) with the folowing command:
npm install
This should install all prerequisites for development. Once you have modified any of the source files ~/src/... you should be able to recompile the JavaScript in ~/dist/ by running the following in the node.js shell from the root folder of the repository:
grunt
To test your changes you can launch a node.js web server by running the following from the command prompt:
node app.js
This will initialise a node.js webserver on port 3000. You can therefore access your pages under http://localhost:3000/ For any problems with this process, or any more advanced operations, please consult the websites of the relevant products.
The dimple api uses a handful of fundamental objects for chart creation. This is a deviation from the functional chaining pattern of d3, however it should be familiar to those of you coming from many other commercial charting applications.
-
dimple.chart - The chart object is fundamental to all dimple visualisations. It constructs and combines the other objects.
-
dimple.axis - A chart object can contain any number of axis objects. An x axis determines horizontal positioning, a y axis determines vertical positioning, other axis types are also possible. There must be at least an x axis and a y axis for the chart to render, however they may be hidden.
-
dimple.series - A chart object can contain any number of series objects. A series links axes together with data and renders a graphic.
-
dimple.storyboard - A chart object can have a single storyboard which animates the chart over another dimension.
To fit with its ethos of simplicity dimple has its own style rules which are dynamically added to elements, meaning you can get a nice looking chart with no CSS at all. However, we realise that CSS support is one of the most awesome things about d3 so if you want to use it on a dimple chart, just set the noFormats property of the chart object to true. This will prevent dimple from adding any style elements to the DOM. The dimple drawing algorithm also decorates everything with a number of extra classes based on the data, allowing you to pick out individual series or data points for formatting.
To allow you to tinker with the inner workings, dimple exposes all its methods and properties. However it is highly recommended that you stick to the stuff that's supposed to be public, therefore any properties or methods which do not form part of the official public API will be prefixed with an underscore (_). These will not be documented here or necessarily supported in future releases so using them is very much an extreme sport.
Some functions with very contained usage have a double underscore prefix (__) these should definitely not be used widely.
Our intention with dimple is that your code should be simple, therefore the examples shouldn't run to many lines at all. They will hopefully be easily understood and flexible enough that even those new to Javascript can play around with them. If you want to do something completely radical, you might be better off bypassing dimple and going straight to d3.js.
To demonstrate the brevity and simplicity of dimple once the data has been loaded and the svg created (see full examples for this bit - it's not difficult), the code behind a stacked bar chart of Brand Volumes over Regions looks like this:
var chart = new dimple.chart(svg, data);
chart.addCategoryAxis("x", "Region");
chart.addMeasureAxis("y", "Volume");
chart.addSeries("Brand", dimple.plot.bar);
chart.draw();
To see this and some other examples in action please check the examples page.