d3-selection-multi

This module adds multi-value syntax to selections and transitions, allowing you to set multiple attributes, styles or properties simultaneously with more concise syntax. For example:

d3.select("body").append("div")
    .attrs({
      title: "A cheery, timeless greeting.",
      class: "greeting"
    })
    .text("Hello, world!");

This is equivalent to:

d3.select("body").append("div")
    .attr("title", "A cheery, timeless greeting.")
    .attr("class", "greeting")
    .text("Hello, world!");

Like selection.attr, the values in the multi-value object can be functions of data:

d3.select("body").append("div")
    .attrs({
      title: function(d) { return d.title; },
      id: function(d, i) { return "id-" + i; },
    });

Alternatively, you can pass a function which returns an object, allowing you to share some computational effort across multiple attributes, or to determine which attribute to set dynamically:

d3.select("body").append("div")
    .attrs(function(d, i) { return {title: d.title, id: "id-" + i}; });

This module is not included in the default D3 bundle for parsimony’s sake: the single-value methods such as selection.attr are recommended for most users, as there is little benefit to the shorter syntax provided by these convenience method.

Installing

If you use NPM, npm install d3-selection-multi. Otherwise, download the latest release or load directly from d3js.org as a standalone library. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://d3js.org/d3-color.v1.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v1.min.js"></script>
<script src="https://d3js.org/d3-ease.v1.min.js"></script>
<script src="https://d3js.org/d3-interpolate.v1.min.js"></script>
<script src="https://d3js.org/d3-selection.v1.min.js"></script>
<script src="https://d3js.org/d3-timer.v1.min.js"></script>
<script src="https://d3js.org/d3-transition.v1.min.js"></script>
<script src="https://d3js.org/d3-selection-multi.v1.min.js"></script>
<script>

var div = d3.selectAll("div")
    .attrs({title: "Hello, world!"})
    .styles({"color": "red"});

</script>

Or, in combination with the D3 default bundle:

<script src="https://d3js.org/d3.v4.min.js"></script>
<script src="https://d3js.org/d3-selection-multi.v1.min.js"></script>
<script>

var div = d3.selectAll("div")
    .attrs({title: "Hello, world!"})
    .styles({"color": "red"});

</script>

Try d3-selection-multi in your browser.

API Reference

# selection.attrs(values)

A convenience method on top of selection.attr for setting multiple attributes. If the specified values is an object, the values may be specified either as strings or functions. For example:

selection.attrs({foo: "foo-value", bar: function(d) { return d.bar; }});

If a value is a constant, all elements are given the same attribute value; otherwise, if a value is a function, the function is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. The function’s return value is then used to set each element’s attribute. A null value will remove the specified attribute.

If the specified values is a function, the function is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. The function’s return value must be an object with string values, which are then used to set attributes on the current element. For example:

selection.attrs(function(d) { return {foo: "foo-value", bar: d.bar}; });

Passing a function to selection.attrs is convenient for sharing some computational effort or state across multiple attributes, or for specifying dynamically which attributes to set.

# selection.styles(values[, priority])

A convenience method on top of selection.style for setting multiple style properties. If the specified values is an object, the values may be specified either as strings or functions. For example:

selection.styles({fill: "red", stroke: function(d) { return d.stroke; }});

If a value is a constant, all elements are given the same style property value; otherwise, if a value is a function, the function is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. The function’s return value is then used to set each element’s style properties. A null value will remove the specified style properties.

selection.styles(function(d) { return {fill: "red", stroke: d.stroke}; });

Passing a function to selection.styles is convenient for sharing some computational effort or state across multiple style properties, or for specifying dynamically which style properties to set.

# selection.properties(values)

A convenience method on top of selection.property for setting multiple element properties. If the specified values is an object, the values may be specified either as strings or functions. For example:

selection.properties({foo: "foo-value", id: function(d, i) { return "id-" + i; }});

If a value is a constant, all elements are given the same property value; otherwise, if a value is a function, the function is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. The function’s return value is then used to set each element’s properties. A null value will remove the specified properties.

selection.properties(function(d, i) { return {foo: "foo-value", id: "id-" + i}; });

Passing a function to selection.properties is convenient for sharing some computational effort or state across multiple properties, or for specifying dynamically which properties to set.

# transition.attrs(values)

Like selection.attrs, but for transition.attr.

# transition.styles(values[, priority])

Like selection.styles, but for transition.style.

qpc-github / d3-selection-multi Goto Github PK