Update: I wrote a tutorial on the basic usage of
d3-workbench for my blog.
In a nutshell
d3-workbench helps you to quickly create data visualization prototypes with d3.js.
It consists of three main components:
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.
As admin install by executing
npm install -g d3-workbench
and to start as regular user
d3-workbench -i +DEMO
A 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/myfolder
Instead 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
npm start -- -i /path/to/myfolder -v
-- otherwise the remaining options are considered
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-workbench
d3-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 require
d3-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 require
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
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.
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> |-- 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/ ...
info.json file currently supports the following options:
|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.
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.
Integrate visualizations in other websites
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>
Self-host your collections online
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]
License and further information
This software is licensed under GPLv3.
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.