d3plus-shape

A javascript library that draws data-driven shapes to DOM using the popular d3 library.

Installation Options

• NPM
• Browser
• AMD and CommonJS
• Custom Builds

NPM

npm install d3plus-shape

Browser

In a vanilla environment, a d3plus_shape global is exported. To use a compiled version hosted on d3plus.org that includes all dependencies:

<script src="https://d3plus.org/js/d3plus-shape.v0.4.full.min.js"></script>

For development purposes, you can also load all dependencies separately:

<script src="https://d3js.org/d3-color.v0.4.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v0.4.min.js"></script>
<script src="https://d3js.org/d3-ease.v0.7.min.js"></script>
<script src="https://d3js.org/d3-interpolate.v0.7.min.js"></script>
<script src="https://d3js.org/d3-selection.v0.7.min.js"></script>
<script src="https://d3js.org/d3-timer.v0.4.min.js"></script>
<script src="https://d3js.org/d3-transition.v0.2.min.js"></script>

<script src="https://d3plus.org/js/d3plus-color.v0.2.min.js"></script>
<script src="https://d3plus.org/js/d3plus-text.v0.4.min.js"></script>

<script src="https://d3plus.org/js/d3plus-shape.v0.4.min.js"></script>

Otherwise, click here to download the latest release.

AMD and CommonJS

The released bundle natively supports both AMD and CommonJS, and vanilla environments.

Custom Builds

The source code is written using standard import and export statements. Create a custom build using Rollup or your preferred bundler. Take a look at the index.js file to see the modules exported.

API Reference

Functions

image([data])

Creates SVG images based on an array of data. If data is specified, immediately draws the images based on the specified array and returns this generator. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

rect([data])

Creates SVG rectangles based on an array of data. If data is specified, immediately draws squares based on the specified array and returns this generator. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

image([data])

Creates SVG images based on an array of data. If data is specified, immediately draws the images based on the specified array and returns this generator. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

Kind: global function

Example (a sample row of data)

var data = {"url": "file.png", "width": "100", "height": "50"};

Example (passed to the generator)

image([data]);

Example (creates the following)

<image class="d3plus-shape-image" opacity="1" href="file.png" width="100" height="50" x="0" y="0"></image>

Example (this is shorthand for the following)

image().data([data])();

Example (which also allows a post-draw callback function)

image().data([data])(function() { alert("draw complete!"); })

• image([data])
  • .data([data])
  • .duration([ms])
  • .height([value])
  • .id([value])
  • .select([selector])
  • .url([value])
  • .width([value])
  • .x([value])
  • .y([value])

image.data([data])

If data is specified, sets the data array to the specified array and returns this generator. If data is not specified, returns the current data array. An tag will be drawn for each object in the array.

Kind: static method of image

image.duration([ms])

If ms is specified, sets the animation duration to the specified number and returns this generator. If ms is not specified, returns the current animation duration.

Kind: static method of image

image.height([value])

If value is specified, sets the height accessor to the specified function or number and returns this generator. If value is not specified, returns the current height accessor.

Kind: static method of image

Example

function(d) {
  return d.height;
}

image.id([value])

If value is specified, sets the id accessor to the specified function and returns this generator. If value is not specified, returns the current id accessor. This is useful if you want to duplicate the same image.

Kind: static method of image

Example

function(d) {
  return d.url;
}

image.select([selector])

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns this generator. If selector is not specified, returns the current SVG container element.

Kind: static method of image

image.url([value])

If value is specified, sets the URL accessor to the specified function and returns this generator. If value is not specified, returns the current URL accessor.

Kind: static method of image

Example

function(d) {
  return d.url;
}

image.width([value])

If value is specified, sets the width accessor to the specified function or number and returns this generator. If value is not specified, returns the current width accessor.

Kind: static method of image

Example

function(d) {
  return d.width;
}

image.x([value])

If value is specified, sets the x accessor to the specified function or number and returns this generator. If value is not specified, returns the current x accessor.

Kind: static method of image

Example

function(d) {
  return d.x || 0;
}

image.y([value])

If value is specified, sets the y accessor to the specified function or number and returns this generator. If value is not specified, returns the current y accessor.

Kind: static method of image

Example

function(d) {
  return d.y || 0;
}

rect([data])

Creates SVG rectangles based on an array of data. If data is specified, immediately draws squares based on the specified array and returns this generator. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

Kind: global function

Example (a sample row of data)

var data = {"id": 0, "x": 100, "y": 50, "width": 200, "height": 100};

Example (passed to the generator)

rect([data]);

Example (creates the following)

<g class="d3plus-shape-rect" id="d3plus-shape-rect-0" transform="translate(100,50)">
  <rect width="200" height="100" x="-100" y="-50" fill="black"></rect>
</g>

Example (this is shorthand for the following)

rect().data([data])();

Example (which also allows a post-draw callback function)

rect().data([data])(function() { alert("draw complete!"); })

• rect([data])
  • .backgroundImage([value])
  • .data([data])
  • .duration([ms])
  • .fill([value])
  • .fontColor([value])
  • .fontFamily([value])
  • .fontResize([value])
  • .fontSize([value])
  • .height([value])
  • .id([value])
  • .innerBounds([bounds])
  • .label([value])
  • .labelPadding([value])
  • .lineHeight([value])
  • .on([typenames], [listener])
  • .select([selector])
  • .stroke([value])
  • .strokeWidth([value])
  • .textAnchor([value])
  • .verticalAlign([value])
  • .width([value])
  • .x([value])
  • .y([value])

rect.backgroundImage([value])

If value is specified, sets the background-image accessor to the specified function or string and returns this generator. If value is not specified, returns the current background-image accessor.

Kind: static method of rect

rect.data([data])

If data is specified, sets the data array to the specified array and returns this generator. If data is not specified, returns the current data array. A rectangle will be drawn for each object in the array.

Kind: static method of rect

rect.duration([ms])

If ms is specified, sets the animation duration to the specified number and returns this generator. If ms is not specified, returns the current animation duration.

Kind: static method of rect

rect.fill([value])

If value is specified, sets the fill accessor to the specified function or string and returns this generator. If value is not specified, returns the current fill accessor.

Kind: static method of rect

rect.fontColor([value])

If value is specified, sets the font-color accessor to the specified function or string and returns this generator. If value is not specified, returns the current font-color accessor, which by default returns a color that contrasts the fill color.

Kind: static method of rect

rect.fontFamily([value])

If value is specified, sets the font-family accessor to the specified function or string and returns this generator. If value is not specified, returns the current font-family accessor.

Kind: static method of rect

rect.fontResize([value])

If value is specified, sets the font resizing accessor to the specified function or boolean and returns this generator. If value is not specified, returns the current font resizing accessor. When font resizing is enabled, the font-size of the value returned by label will be resized the best fit the rectangle.

Kind: static method of rect

rect.fontSize([value])

If value is specified, sets the font-size accessor to the specified function or string and returns this generator. If value is not specified, returns the current font-size accessor.

Kind: static method of rect

rect.height([value])

If value is specified, sets the height accessor to the specified function or number and returns this generator. If value is not specified, returns the current height accessor.

Kind: static method of rect

Example

function(d) {
  return d.height;
}

rect.id([value])

If value is specified, sets the id accessor to the specified function and returns this generator. If value is not specified, returns the current id accessor.

Kind: static method of rect

Example

function(d) {
  return d.id;
}

rect.innerBounds([bounds])

If bounds is specified, sets the inner bounds to the specified function and returns this generator. If bounds is not specified, returns the current inner bounds accessor.

Kind: static method of rect

Example

function(shape) {
  return {
    "width": shape.width,
    "height": shape.height,
    "x": -shape.width / 2,
    "y": -shape.height / 2
  };
}
      

rect.label([value])

If value is specified, sets the label accessor to the specified function or string and returns this generator. If value is not specified, returns the current text accessor, which is undefined by default.

Kind: static method of rect

rect.labelPadding([value])

If value is specified, sets the label padding to the specified number and returns this generator. If value is not specified, returns the current label padding.

Kind: static method of rect

rect.lineHeight([value])

If value is specified, sets the line-height accessor to the specified function or string and returns this generator. If value is not specified, returns the current line-height accessor.

Kind: static method of rect

rect.on([typenames], [listener])

Adds or removes a listener to each rectangle for the specified event typenames. If a listener is not specified, returns the currently-assigned listener for the specified event typename. Mirrors the core d3-selection behavior.

Kind: static method of rect

rect.select([selector])

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns this generator. If selector is not specified, returns the current SVG container element.

Kind: static method of rect

rect.stroke([value])

If value is specified, sets the stroke accessor to the specified function or string and returns this generator. If value is not specified, returns the current stroke accessor.

Kind: static method of rect

rect.strokeWidth([value])

If value is specified, sets the stroke-width accessor to the specified function or string and returns this generator. If value is not specified, returns the current stroke-width accessor.

Kind: static method of rect

rect.textAnchor([value])

If value is specified, sets the text-anchor accessor to the specified function or string and returns this generator. If value is not specified, returns the current text-anchor accessor, which is "start" by default. Accepted values are "start", "middle", and "end".

Kind: static method of rect

rect.verticalAlign([value])

If value is specified, sets the vertical alignment accessor to the specified function or string and returns this generator. If value is not specified, returns the current vertical alignment accessor, which is "top" by default. Accepted values are "top", "middle", and "bottom".

Kind: static method of rect

rect.width([value])

If value is specified, sets the width accessor to the specified function or number and returns this generator. If value is not specified, returns the current width accessor.

Kind: static method of rect

Example

function(d) {
  return d.width;
}

rect.x([value])

If value is specified, sets the x accessor to the specified function or number and returns this generator. If value is not specified, returns the current x accessor. The number returned should correspond to the horizontal center of the rectangle.

Kind: static method of rect

Example

function(d) {
  return d.x;
}

rect.y([value])

If value is specified, sets the y accessor to the specified function or number and returns this generator. If value is not specified, returns the current y accessor. The number returned should correspond to the vertical center of the rectangle.

Kind: static method of rect

Example

function(d) {
  return d.y;
}