search

romsson / d3-gridding

grids for rapid D3 charts mockups
https://romsson.github.io/d3-gridding/example/capture/display.html
BSD 3-Clause "New" or "Revised" License
104 stars 7 forks source link
d3 d3-gridding d3js dataviz design grid infovis javascript mock treemap

readme

d3-gridding

npm version Build Status dependencies Status

Create rapid mock-ups for D3 charts, using data-driven grids.

modes layouts

Left: grids available in the toolkits; Right: layouts for page partition to nest grids within

Example

<!DOCTYPE html>
<meta charset="utf-8">
<body>
<script src="https://unpkg.com/d3@5"></script>
<script src="https://unpkg.com/d3-gridding@0.1"></script>
<script>

var width = 400,
    height = 300;

var gridding = d3.gridding()
  .size([width, height])
  .mode("grid");

var data = d3.range(250);

var griddingData = gridding(data);

var svg = d3.select("body").append("svg")
    .attr("width", width)
    .attr("height", height);

svg.selectAll(".square")
    .data(griddingData)
  .enter().append("rect")
    .style("fill", "none")
    .style("stroke", "black")
    .attr("width", function(d) { return d.width; })
    .attr("height", function(d) { return d.height; })
    .attr("transform", function(d) { return "translate(" + d.x + "," + d.y + ")"; })

  </script>
</body>

Output below and live coding version.

minimalistic grid

The code snippet below lets you create dots organized as a grid:

d3.select("body").append("svg")
    .attr("width", 800)
    .attr("height", 600)
    .selectAll("circle")
    .data(
      d3.gridding()
        .size([800, 600])
        .mode("vertical")(d3.range(10))
    )
  .enter().append("circle")
    .attr("r", 10)
    .attr("transform", function(d) { 
      return "translate(" + d.cx + "," + d.cy + ")"; 
      });

More Examples

How to use it

To install, use NPM npm install d3-gridding or download the latest release.

To use, include the d3-gridding.js JavaScript file in your HTML code or use the following:

<script src="https://unpkg.com/d3-gridding@0.1"></script>

Output below and live coding version.

minimalistic circle grid

The magic happens with gridding which turns an array of JavaScript Objects, into another array with additional attributes:

> gridding([{}, {}, {}])

[▶ Object, ▶ Object, ▶ Object]

[▼ Object                    ]
    x: 0
    y: 300
    cx: 300
    cy: 300
    height: 600
    width: 266.6666666666667

It becomes interesting when changing the type of layout, which will organize the elements differently, by changing the value of the attributes above:

gridding.mode("horizontal");

var points = svgPoints.selectAll(".point")
  .data(gridding(data));

That's pretty much what you need to know at this point to get started. Below is a list of functions that will let you customize the layouts and retrieve internal values.

Note that parameters can also be set as group, using a JSON object:

var gridding = d3.gridding()
  .params({
    "size": [800, 600],
    "mode": "vertical",
    "offset": function(d) { return [d.x, d.y]; }
  });

Layouts

Layouts help to divide and organize a page into regions. Layouts actually are grids that are generated with some dataset that can be seen as proportions. Below is an example of dataset that is from this list of layouts. See the layout list and source code.

var layout = {
  "name": "basic3columns",
  "values": [
    {"index": 1, "__x": 10, "__y": 10, "__height": 0, "__width": 0},
    {"index": 2, "__x": 0, "__y": 0, "__height": 10, "__width": 2, "name": "left"},
    {"index": 3, "__x": 2, "__y": 0, "__height": 10, "__width": 6, "name": "main"},
    {"index": 4, "__x": 8, "__y": 0, "__height": 10, "__width": 2, "name": "right"}]
};

The result is as below and can be found on this page.

layout 3col

Then to draw the layout you may need to set the grid parameters accordingly as below.

var gridding = d3.gridding()
  .params({
    "size": [width, height],
    "offset": [0, 0],
    "mode": "coordinate",
    "valueX": "__x",
    "valueY": "__y",
    "valueWidth": function(d) { return d["__width"]},
    "valueHeight": function(d) { return d["__height"]}
  });

And finally drawing the layout the very same way one draws a grid.

svgSquares.selectAll(".square")
    .data(gridding(layout.values))
  .enter().append("rect")
    .attr("class", "square")
      .attr("width", function(d) { return d.width; })
      .attr("height", function(d) { return d.height; })
      .attr("transform", function(d) { 
        return "translate(" + d.x + "," + d.y + ")"; 
      });

Nesting

One of the most powerful property of grids is to allow their nesting

-Simple recursive function

-How to set the grids in one param element?

Rendering methods

d3-gridding is agnostic to the rendering method

SVG

Canvas

Divs

WebGL

API

# d3.gridding().mode(mode)

The mode parameter sets the layout:

Others

# d3.gridding().sort([compare])

Sets the sort function, similar to D3's and defaults to:

function(a, b) { return a - b; }

Thus you can use D3's sorting functions such as d3.ascending and d3.descending.

# d3.gridding().value([accessor])

Sets the value accessor function, similar to D3's and defaults to:

function value(d) { return d; }

# d3.gridding().valueY([string || accessor])

The value can either be a traditional accessor function but for attributes this time, or the data attribute itself directly as a string:

.valueY(function value(d) { return d["index"]; })

or

.valueY("index")

# d3.gridding().valueY([string || accessor])

See valueY().

# d3.gridding().padding(value)

Sets the local offset between grid elements (default: 1px).

# d3.gridding().offset(value)

Sets the global offset for all elements (default: 0px) as an array [left, top].

# d3.gridding().orient("up" | "down" (default))

Orients the grid & diagonal layouts either upwards or downwards when adding / removing cells.

# d3.gridding().radius(value)

Radius for radial layout.

# d3.gridding().sort(value || function)

Sort by attribute value (or function if value is a function.

# d3.sortAsc().sortAsc(true || false)

By default, ascending sorting by sort attribute || function defined previously.

Credits