Class: c3.Selection

Defined in: js/c3.coffee

Overview

The c3 selection object is used internally as an abstraction around D3 selections to provide common functionality and patterns. It is not meant to provide a general solution or replace D3. The motivation behind it is to normalize design patterns and performance optimizations useful for c3 visualizations on top of what D3 offers. In particular, it is useful to allow c3 users to define options which c3 visualizations can then use to do the actual DOM updates.

Please refer to c3.Selection.Options for user-configurable options.

c3 visualizations create c3.Selection objects to in turn create and represent various DOM nodes. c3.Selection.Options objects are used to persist user options that are used in subsequent updates or styling of nodes. For example, there is a circle_options {c3.Selection.options} used to describe how to setup and style circles in a scatter plot. You can still modify the different selection option properties, which will then be used as appropriate when redraw() or restyle() is called.

Variables

Author:

See also:

Variables Summary

opt = 
{}

[c3.Selection.Options] User configurable options for ongoing update() and style() manipulation of nodes.

opt_array = 
undefined

[Array<c3.Selection.Options>] Array of user options for each node in the selection based on the index.

Instance Method Summary

Constructor Details

# (void) constructor(d3_selection = d3.select(), query, before, children_only)

TODO: Support all possible selectors.

Create a new selection

Parameters:

  • d3_selection ( {https://github.com/mbostock/d3/wiki/Selections d3.selection )
  • query ( String ) — Search string to query in the parent selection to make this new selection. If a class is specified, such as "tag.class", then the class will automatically be added to newly created nodes.
  • before ( String ) — An optional selector to insert nodes before. :first-child will insert nodes at the beginning.
  • children_only ( boolean ) — Only select direct children, not all descendents

Instance Method Details

# (void) select(query, before, children_only)

Create a new c3 selection based on the current selection

Parameters:

  • query ( String ) — Search string to query in the parent selection to make this new selection. If a class is specified, such as "tag.class", then the class will automatically be added to newly created nodes.
  • before ( String ) — An optional selector to insert nodes before. :first-child will insert nodes at the beginning.
  • children_only ( boolean ) — Only select direct children, not all descendents

# (void) inherit(query, create = true, prepend = false) Bound

Create a child node for each node in the parent's selection with a 1:1 mapping to the same data. For example, if the parent selection had a set of svg:g nodes, then inheriting from that with a circle query would create an svg:circle node nested in each svg:g node.

Parameters:

  • query ( String ) — Node type to create as nested nodes in the current selection
  • create ( Boolean, String ) — Create missing child nodes for new nodes or set to restore to ensure that child nodes are created for existing parent nodes that don't already have them.
  • prepend ( Boolean ) — If true, then prepend child nodes instead of appending them. Note that this will not prepend in front of any text content, only child nodes.

# (void) singleton(datum) Bound

Create a single DOM node based on the passed in data. Ensure that only one node will be created and will remove extra nodes that match the query if they previously existed.

Parameters:

  • datum ( * ) — The datum to bind to the DOM node. This may be left undefined.

# (void) bind(data, key) Bound

Update the DOM nodes based on the provided data using D3. Create new nodes and remove them as necessary so there is a node for each element in the data array and they are bound together. The key function is optional and is used to uniquely identify data elements. So, even if the data is reordered in subsequent calls to update, they will still be bound to the same DOM nodes. Animate opacity for entering or exiting nodes if animate is set in the options unless the opacity style is defined.

Parameters:

  • data ( Array ) — Array of data to bind to the DOM
  • key ( Function ) — Accessor to uniquely identify data elements

# (void) remove() Bound

Remove this selection

# (void) options(opt = {}, opt_accessor)

Set persistent user-configurable options. A reference to these options are stored in the selection and are used for future manipulation in update() and style(). options for a specific data element.

Parameters:

  • opt ( c3.Selection.Options ) — User-configurable options to define how to setup and style the selection's nodes.
  • opt_accessor ( Function ) — An optional accessor to return

# (void) animate(animate = true)

Allow animations for this selection during binding or positioning if the user requested them with animate in the c3.Selection.Options.

Parameters:

  • animate ( Boolean ) — Allow animations

# (void) update() Bound

This will setup event handlers for new nodes and update classes, tooltips, text, and html for all nodes based on the current data and options.

# (void) position(attrs, old_attrs) Bound

Update the attribute values for the dom nodes of this selection based on the values and callbacks set in attrs.

Parameters:

  • attrs ( Object ) — A map where the keys represent DOM attribute names and the values are the corresponding values or functions to set them. The functions are called via D3. They are passed the bound datum and index to the data as arguments and the this context is set to refer to the HTML element.
  • old_attrs ( Object ) — A map for the previous attributes to use for new elements if they are animated.

# (void) position_tweens(attrs) Bound

Update the attribute values for the dom nodes of this selection based on tween functions in attrs

Parameters:

  • tweens ( Object ) — A map where the keys represent DOM attribute names and the values are corresponding tween functions for animating them. The functions are called via D3. They are passed the bound datum and index to the data as arguments and the this context refers to the HTML element. They should return a "tween" function thich takes a time parameter from 0-1 as the transition animation progresses based on the easing function. It is the tween function that should finally return the value of the attribute for that point in the transition.

# (void) style(style_new) Bound

A method to style and setup CSS classes for the nodes in the selection based on the current {c3.Selection.options options}.

Parameters:

  • style_new ( Boolean ) — By default all nodes will be updated. If this is set, then only new nodes will be updated. This only works if the data was bound with a key function to avoid nodes having incorrect styles when the bound data is dynamically rearranged.

# (HTMLElement) node() Bound

Return a single HTML Element for this selection. Mostly useful if you know the selection only represents a single node.

Returns:

  • ( HTMLElement ) — node

    Quickly fuzzy find classes, mixins, methods, file:

    Control the navigation frame:

    You can focus and blur the search input: