Update: I wrote a tutorial on the basic usage of d3-workbench for my blog.
d3-workbench helps you to quickly create data visualization prototypes with d3.js.
It consists of three main components:
d3-wb, a collection of Javascript-libraries and plug-ins extending d3.js.d3-wb-server, a local application rendering visualizations in your browser while you develop.workbench, your working directory.
d3-workbench is not a framework, even though it offers libraries with strict APIs. It's neither required to use any of the utilities, reusable charts or plug-ins (e.g., if you just want to benefit from the server component), nor is your data visualization bound to a d3-workbench environment.
Think of d3-workbench as a distribution as in «Linux distribution» with d3.js being the kernel.
All components are d3.js V5-ready.
d3-workbench uses node and npm. Make sure you have both installed and npm available on the command-line.
As admin install by executing
npm install -g d3-workbenchand to start as regular user
d3-workbench -i +DEMOA browser window will open and display a demo workbench. To start with your own project, create a new folder somewhere and run
d3-workbench -i /path/to/myfolderInstead of the demo workbench, an empty workbench is created, providing you with a new collection containing a sample visualization to start with.
To start d3-workbench from source, use the start script
npm start -- -i /path/to/myfolder -vNotice the -- otherwise the remaining options are considered npm options.
To start d3-workbench through docker, you can build from the provided Dockerfile
docker build -t d3-workbench .
docker run -ti --rm -p 50321:50321 d3-workbenchd3-wb consists of the following components:
d3-wb.js: The core component that minimizes boilerplate code for common tasks such as setting up SVGs with margin conventions, handling data paths, resizing SVGs to parent DIVs, etc.d3-wb-modules/: A set of modules to speed up visualization by providing utilities for recurring tasks such as adding titles, axis, tool-tips or HTML-components, changing color themes and working with data. These modules required3-wb.jsto be loaded first.d3-wb-reusable-charts/: A collection of basic charts such as bar, line, scatter or donut charts. All charts are designed to be fully reusable (in the spirit of «Towards Reusable Charts» and «Towards Updatable D3.js Charts»), can be used independently from d3-workbench and don't required3-wb.js.
Library releases of different combinations of these components are available depending on your needs.
d3-wb-server is an engine, that helps you to manage and create your data visualization prototypes. d3-wb-server takes care of..
- Assembling and rendering of your local files into a browser-based collection/visualization viewer
- Automatic lookup and setup of local files/folders
- Auto-reload of the browser if you change a file in your workbench
- Standalone full-screen SVGs and SVG galleries out of the box
- Offline-work
workbench is a local folder that contains your visualization work in progress. Shipped with d3-workbench comes a workbench that demonstrates all the reusable charts and libraries. Your work is organized in collections.
In your workbench's top-level you will find your collections (in the example a collection of chart examples and utility examples).
Inside a collection you will find one folder for each of the collection's visualizations, e.g., an example implementation of the reusable bar chart.
The overall file/folder structure for your workbench:
<workbench>
|-- d3-wb-version - Stores the d3-workbench version that created this workbench
|-- info.json - A file to configure the top-level webpage
|-- local.css - A local CSS file to change the appearance of the top-level webpage
|-- local.cs - A local JS file to be executed if the top-level webpage is requested
|-- collection_1/ - A subfolder, i.e. a collection of visualizations
|-- info.json - Like above, but applied to the current collection
|-- local.css - Like above, but applied to the current collection
|-- local.js - Like above, but applied to the current collection
|-- viz_1/ - A visualization
|-- info.json - Like above, but applied to the current visualization
|-- data.csv - A file containing the data for this visualization
|-- svg.js - The implementation file for this visualization
|-- collection_2/ ...
The info.json file currently supports the following options:
| Option | Explanation |
|---|---|
| title | Title of the current (sub-) page |
| isroot | Mark the current folder as root folder (deprecated) |
| height | Desired visualization height (only applied to visualizations) |
| ignore | A list of sub-folders to be ignored |
Below you find some information on a typical workflow using d3-workbench.
In the beginning you probably use d3-workbench as described above. After you've installed the application, you create a new workbench and create collections and visualizations.
Consider the default workbench as an up-to-date cookbook for all things possible with d3-workbench. For example if you want to create a sankey diagram yourself, checkout the visualization code, especially the necessary data format and the javascript-code.
workbench folders have no external dependencies except for d3-workbench available on the command line. If you want to share your collections, you can simple ZIP-compress your workbench and send it to someone. Or you might put your workbench on GitHub and work collaboratively. Notice that each workbench contains a version-file indicating the d3-workbench version it was created with.
As long as you haven't introduced any new dependencies, you can include the library components of d3-workbench into bl.ocks or your own website. There is an example bl.ock/gist where you can see how it's applied. Inside the running demo instance you will find another example under the path coll_01_tech_specs/000-index-manual/.
To auto-scale your visualization to a surrounding div you would use a code snippet like this:
<!-- Define a unique ID for the DIV containing the visualization
and optional a class to style it, e.g., the desired
width and height. -->
<div id="figure" class="figures">
<!-- Add an empty SVG body with a unique SVG ID. -->
<svg id="svg-figure"></svg>
<!-- Reference your d3 script..
- embedded: set to true so d3wb will look for the surrounding DIV
- datapath: relative path to where your data is stored
- svgid: ID of your SVG element
- divid: ID of your surrounding DIV element
-->
<script src="svg.js"
embedded="true"
datapath="."
svgid="svg-figure"
divid="figure" ></script>
</div>Of course you can simple put a web server in front of a running d3-workbench instance and host your work from there. There is a demo instance using this particular method available at https://d3-workbench.bastis.cloud/.
In this case a simple Apache-based URL-Rewrite was used:
RewriteEngine On
RewriteRule ^(.*)$ http://localhost:50321/$1 [P]
This software is licensed under GPLv3.
Icon made by https://www.flaticon.com/authors/smashicons from https://www.flaticon.com/ is licensed by CC 3.0 BY.
Even though the overall interfaces are stable, so you can safely work with d3-workbench, the project is still evolving and there is a ton of things still to do. This includes. Contributions and beta-testers are always welcome. You can get in contact with me via my hub-page.