-
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.
If you only intend to make use of dimple in your web page just include the following script references:
<script src="http://d3js.org/d3.v3.min.js"></script>
<script src="http://dimplejs.org/dist/dimple.v2.0.0.min.js"></script>
You can then access the API from the dimple namespace.
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 but check the advanced examples first, there's more here than simple charts.
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.
If you want to contribute to the dimple code-base 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. This is used for grunt (explained below) as well as running a web server for tests and hosting the examples in development.
The final tool required is grunt which we use to combine the source js files into a single distribution file. Grunt 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. Dimple uses continuous testing through grunt karma. When developing dimple run:
grunt test
This puts karma in continuous test mode. It will run in the background and immediately raise an exception if you save a source file which breaks a unit test.
To view an example and examine the affect of 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 example http://localhost:3000/examples/bars_horizontal.html. For any problems with this process, or any more advanced operations, please consult the websites of the relevant products.
If you do not wish to develop dimple but do want to play with the examples on your local machine, you must serve them over a web server. There are many options available for doing this and if you have a preferred approach, please use it, otherwise I recommend node.js as a quick and free solution.
Begin by installing node.js from here.
Next, download the dimple example code (and other files) from here. You will need to extract the contents of the zip file into a folder of your choice. In this example I'll assume it is C:\Temp\MyDimpleSite
Now launch your operating system's command line and navigate to your new folder. For example if you are using Windows - launch cmd.exe and type:
cd\temp\mydimplesite
Next you need to install all the application dependencies, which is as simple as typing the following in the command prompt:
npm install
This should automatically install everything you need (Thanks node.js!). Then run the following:
node app.js
Which will launch a node express web server on port 3000, whose configuration is in the app.js file. This won't actually do anything visible, the cursor will go to the next line and happily blink there forever.
Now you can browse the examples in your favourite browser. So for the horizontal bars example use the following URL:
http://localhost:3000/examples/bars_horizontal.html
This will serve the example file from your hard drive located at:
C:\Temp\MyDimpleSite\examples\bars_horizontal.html
All of the examples on the dimple site will be located in this folder and can be accessed similarly.