leahfitch / elm-d3

Elm bindings for D3.js

elm-d3

elm-d3 provides Elm bindings for d3.js. It enables you to create type-safe, composable widgets using HTML, SVG, and CSS. D3 acts as a conceptual basis for the library, as well as an alternative renderer for Elm.

Installation

First make sure that you have node.js installed, as well as the Elm compiler. Once you've installed those dependencies, clone the elm-d3 repository and run the following command from the root directory:

elm-make

This will locally install the smash utility and build the library.

To get an example compiled and running in your browser, use the following command:

elm-make examples/Circles.elm --output circles.html

You must then edit the HTML file and add a <script> tag that will load the D3.js library. (Unfortunately, it is no longer possible to control linking of external JavaScript code using the Elm compiler, so this manual step is necessary.) Then, load it up on your browser:

open build/examples/circles.html

If you're not using OS X, the last command won't work. In that case open circles.html however you normally would in your operating system. Once the page is open, move your mouse left and right to add and remove circles, and move your mouse up and down to change their brightness.

Conceptual Prerequisites

In order to effectively use elm-d3, you should be familiar with the core concepts of D3.js, including data joins, nested selections, and reusable charts. The following series of blog posts by @mbostock introduce these concepts quite nicely, and independently of elm-d3 should be read by anybody that is interested in developing their D3.js skills:

• Thinking in Joins
• Nested Selections
• Towards Reusable Charts

Usage

elm-d3 is designed to be a very literal interpretation of the D3.js API. In fact, any D3.js code that uses only the Core Selection API should be fairly straightforward to port over to elm-d3. For example, here's a fragment of code taken from the Voronoi Diagram example (original D3.js version):

voronoi : D3 [D3.Voronoi.Point] [D3.Voronoi.Point]
voronoi =
  selectAll "path"
  |. bind cells
     |- enter <.> append "path"
     |- update
        |. fun attr "d" (\ps _ -> path ps)
        |. fun attr "class" (\_ i -> "q" ++ (show ((%) i 9)) ++ "-9")

Operations such as selectAll, enter, and attr have the same behavior as their D3.js counterparts. The bind operation is equivalent to the data() operator from D3.js, though it requires its argument to be a function. Similarly, attr also requires a function as its second argument, which takes the data bound to the element and the element's index in the selection. Another difference is that elm-d3 replaces method chaining with the |. operator. For example,

selectAll "path"
|. bind cells

is equivalent to

d3.selectAll("path")
  .data(cells)

Sequencing is another operation that's slightly different in elm-d3. In Javascript, there's a common pattern where you apply a data bound to a selection, assign it to a variable, and then apply enter(), update, and exit() operations to the variable. In place of sequencing, you would use the |- infix operator. Its use is illustrated in the example above. You can see the equivalent code in JavaScript below.

var path = d3.selectAll('path')
    .bind(function(d) { ... });

path.enter()
  .append('path');

path
    .attr('d', function(d) { ... })
    .attr('class', function(d) { ... });

Rendering

Creating a selection such as voronoi above does not actually draw anything to the screen. Rather, it defines a computation that the runtime knows how to draw to the screen. To do this, you use the render function. Its first two arguments are the height and width of the drawing area. The third is the D3 a b that will be rendered. The final argument is the datum of type a that will be bound to the selection. The result is an Element that the Elm runtime knows what to do with:

main : Element
main = render 800 600 voronoi [{x: 200, y: 200}, {x: 320, y:100}]

Further documentation

For more information about the API, the source file in src/D3.elm. Each function is preceded by a comment describing the equivalent expression in JavaScript. Types are also very instructive.

License

BSD3, see LICENSE file for its text.