d3plus-shape

d3plus-shape

Fancy SVG shapes for visualizations

Installing

If you use NPM, npm install d3plus-shape. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom bundle using Rollup or your preferred bundler. You can also load directly from d3plus.org:

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

Getting Started

Let's say you want to draw 2 rectangles with distinct labels and colors. If you structure your data like this:

var data = [
  {text: "Box #1", width: 200, height: 150, x: 100, y: 75, color: "cornflowerblue"},
  {text: "Box #2", width: 150, height: 100, x: 285, y: 100, color: "firebrick"}
];

It can be passed to the rectangle generator like this:

new d3plus.Rect()
  .data(data)
  .fill(function(d) { return d.color; })
  .label(function(d) { return d.text; })
  .render();

It even detects that the blue rectangle should have a dark label and the red rectangle's should be light!

Please note that the x and y positions are relative to the center of the rectangles.

Click here to view this example live on the web.

API Reference

Classes

Circle ⇐ Shape

Image

Line ⇐ Shape

Rect ⇐ Shape

Shape

Circle ⇐ Shape

Kind: global class
Extends: Shape

• Circle ⇐ Shape
  • new Circle()
  • .r([value])
  • .update(selector)
  • .x([value])
  • .y([value])

new Circle()

Creates SVG circles based on an array of data.

Circle.r([value])

If value is specified, sets the radius accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current radius accessor.

Kind: static method of Circle

Param	Type
[value]	function | Number

Example

function(d) {
  return d.r;
}

Circle.update(selector)

Updates the style and positioning of the elements matching selector and returns the current class instance. This is helpful when not wanting to loop through all shapes just to change the style of a few.

Kind: static method of Circle

Param	Type
selector	String | HTMLElement

Circle.x([value])

If value is specified, sets the x accessor to the specified function or number and returns the current class instance. 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 Circle

Param	Type
[value]	function | Number

Example

function(d) {
  return d.x;
}

Circle.y([value])

If value is specified, sets the y accessor to the specified function or number and returns the current class instance. 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 Circle

Param	Type
[value]	function | Number

Example

function(d) {
  return d.y;
}

Image

Kind: global class

• Image
  • new Image()
  • .render([callback])
  • .data([data])
  • .duration([ms])
  • .height([value])
  • .id([value])
  • .select([selector])
  • .url([value])
  • .width([value])
  • .x([value])
  • .y([value])

new Image()

Creates SVG images based on an array of data.

Example (a sample row of data)

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

Example (passed to the generator)

new Image().data([data]).render();

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.render([callback])

Renders the current Image to the page. If a callback is specified, it will be called once the images are done drawing.

Kind: static method of Image

Param	Type
[callback]	function

Image.data([data])

If data is specified, sets the data array to the specified array and returns the current class instance. 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

Param	Type	Default
[data]	Array	[]

Image.duration([ms])

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

Kind: static method of Image

Param	Type	Default
[ms]	Number	600

Image.height([value])

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

Kind: static method of Image

Param	Type
[value]	function | Number

Example

function(d) {
  return d.height;
}

Image.id([value])

If value is specified, sets the id accessor to the specified function and returns the current class instance. 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

Param	Type
[value]	function

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 the current class instance. If selector is not specified, returns the current SVG container element.

Kind: static method of Image

Param	Type	Default
[selector]	String | HTMLElement	d3.select("body").append("svg")

Image.url([value])

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

Kind: static method of Image

Param	Type
[value]	function

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 the current class instance. If value is not specified, returns the current width accessor.

Kind: static method of Image

Param	Type
[value]	function | Number

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 the current class instance. If value is not specified, returns the current x accessor.

Kind: static method of Image

Param	Type
[value]	function | Number

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 the current class instance. If value is not specified, returns the current y accessor.

Kind: static method of Image

Param	Type
[value]	function | Number

Example

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

Line ⇐ Shape

Kind: global class
Extends: Shape

• Line ⇐ Shape
  • new Line()
  • .curve([value])
  • .update(selector)
  • .x([value])
  • .y([value])

new Line()

Creates SVG lines based on an array of data.

Line.curve([value])

If value is specified, sets the line curve to the specified string and returns the current class instance. If value is not specified, returns the current line curve. The number returned should correspond to the horizontal center of the rectangle.

Kind: static method of Line

Param	Type	Default
[value]	String	"linear"

Line.update(selector)

Updates the style and positioning of the elements matching selector and returns the current class instance. This is helpful when not wanting to loop through all shapes just to change the style of a few.

Kind: static method of Line

Param	Type
selector	String | HTMLElement

Line.x([value])

If value is specified, sets the x accessor to the specified function or number and returns the current class instance. 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 Line

Param	Type
[value]	function | Number

Example

function(d) {
  return d.x;
}

Line.y([value])

If value is specified, sets the y accessor to the specified function or number and returns the current class instance. 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 Line

Param	Type
[value]	function | Number

Example

function(d) {
  return d.y;
}

Rect ⇐ Shape

Kind: global class
Extends: Shape

• Rect ⇐ Shape
  • new Rect()
  • .height([value])
  • .update(selector)
  • .width([value])
  • .x([value])
  • .y([value])

new Rect()

Creates SVG rectangles based on an array of data. See this example for help getting started using the rectangle generator.

Rect.height([value])

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

Kind: static method of Rect

Param	Type
[value]	function | Number

Example

function(d) {
  return d.height;
}

Rect.update(selector)

Updates the style and positioning of the elements matching selector and returns the current class instance. This is helpful when not wanting to loop through all shapes just to change the style of a few.

Kind: static method of Rect

Param	Type
selector	String | HTMLElement

Rect.width([value])

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

Kind: static method of Rect

Param	Type
[value]	function | Number

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 the current class instance. 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

Param	Type
[value]	function | Number

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 the current class instance. 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

Param	Type
[value]	function | Number

Example

function(d) {
  return d.y;
}

Shape

Kind: global class

• Shape
  • new Shape()
  • .backgroundImage([value])
  • .config([value])
  • .data([data])
  • .duration([ms])
  • .fill([value])
  • .fontColor([value])
  • .fontFamily([value])
  • .fontResize([value])
  • .fontSize([value])
  • .id([value])
  • .label([value])
  • .labelBounds([bounds])
  • .labelPadding([value])
  • .lineHeight([value])
  • .on([typenames], [listener])
  • .opacity([value])
  • .render([callback])
  • .scale([value])
  • .select([selector])
  • .stroke([value])
  • .strokeWidth([value])
  • .textAnchor([value])
  • .verticalAlign([value])

new Shape()

An abstracted class for generating shapes.

Shape.backgroundImage([value])

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

Kind: static method of Shape

Param	Type	Default
[value]	function | String	false

Shape.config([value])

If value is specified, sets the methods that correspond to the key/value pairs and returns the current class instance. If value is not specified, returns the current configuration.

Kind: static method of Shape

Param	Type
[value]	Object

Shape.data([data])

If data is specified, sets the data array to the specified array and returns the current class instance. If data is not specified, returns the current data array. A shape will be drawn for each object in the array.

Kind: static method of Shape

Param	Type	Default
[data]	Array	[]

Shape.duration([ms])

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

Kind: static method of Shape

Param	Type	Default
[ms]	Number	600

Shape.fill([value])

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

Kind: static method of Shape

Param	Type	Default
[value]	function | String	"black"

Shape.fontColor([value])

If value is specified, sets the font-color accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current font-color accessor, which by default returns a color that contrasts the fill color. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type
[value]	function | String | Array

Shape.fontFamily([value])

If value is specified, sets the font-family accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current font-family accessor. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type	Default
[value]	function | String | Array	"Verdana"

Shape.fontResize([value])

If value is specified, sets the font resizing accessor to the specified function or boolean and returns the current class instance. 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 shape. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type
[value]	function | Boolean | Array

Shape.fontSize([value])

If value is specified, sets the font-size accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current font-size accessor. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type	Default
[value]	function | String | Array	12

Shape.id([value])

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

Kind: static method of Shape

Param	Type
[value]	function

Shape.label([value])

If value is specified, sets the label accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current text accessor, which is undefined by default. If an array is passed or returned from the function, each value will be rendered as an individual label.

Kind: static method of Shape

Param	Type
[value]	function | String | Array

Shape.labelBounds([bounds])

If bounds is specified, sets the label bounds to the specified function and returns the current class instance. If bounds is not specified, returns the current inner bounds accessor.

Kind: static method of Shape

Param	Type	Description
[bounds]	function	The given function is passed the data point, index, and internally defined properties of the shape and should return an object containing the following values: width, height, x, y. If an array is returned from the function, each value will be used in conjunction with each label.

Example

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

Shape.labelPadding([value])

If value is specified, sets the label padding to the specified number and returns the current class instance. If value is not specified, returns the current label padding. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type	Default
[value]	function | Number | Array	10

Shape.lineHeight([value])

If value is specified, sets the line-height accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current line-height accessor. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type
[value]	function | String | Array

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

Adds or removes a listener to each shape 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 Shape

Param	Type
[typenames]	String | Object
[listener]	function

Shape.opacity([value])

If value is specified, sets the opacity accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current opacity accessor.

Kind: static method of Shape

Param	Type	Default
[value]	Number	1

Shape.render([callback])

Renders the current Shape to the page. If a callback is specified, it will be called once the shapes are done drawing.

Kind: static method of Shape

Param	Type
[callback]	function

Shape.scale([value])

If value is specified, sets the scale accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current scale accessor.

Kind: static method of Shape

Param	Type	Default
[value]	function | Number	1

Shape.select([selector])

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

Kind: static method of Shape

Param	Type	Default
[selector]	String | HTMLElement	d3.select("body").append("svg")

Shape.stroke([value])

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

Kind: static method of Shape

Param	Type	Default
[value]	function | String	"black"

Shape.strokeWidth([value])

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

Kind: static method of Shape

Param	Type	Default
[value]	function | Number	0

Shape.textAnchor([value])

If value is specified, sets the text-anchor accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current text-anchor accessor, which is "start" by default. Accepted values are "start", "middle", and "end". If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type	Default
[value]	function | String | Array	"start"

Shape.verticalAlign([value])

If value is specified, sets the vertical alignment accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current vertical alignment accessor, which is "top" by default. Accepted values are "top", "middle", and "bottom". If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape

Param	Type	Default
[value]	function | String | Array	"start"

_{Documentation generated on Thu, 18 Aug 2016 21:50:23 GMT}