Class: c3.Base Abstract

Defined in:

js/c3.coffee

Overview

This class is abstract.

Note: In the documentation, please look at the "Variables Summary" to see what properties can be set for each type of visualization.

The Base parent object that all c3 visualizations are inherited from.

Visualization Object Construction

c3 follows the convention that users should pass an "options" object to render() or the constructor when creating a visualization object. That options object is then used to "extend" the newly created visualization object. Thus, any members of that options object become members of the visualization. With this mechanism any properties defined in the class prototype will act as a default value. Setting options are optional unless marked as REQUIRED in the documentation.

External Interface

This Base object defines a set of methods as the standard external interface for visualizations:

Internal Implementation

The following methods represent the implementation of the visualization. They are broken down this way to allow optimizations and reduce redundant work. Individual visualizations should implement virtual methods that are named the same as these only with a preceding underscore such as _init(), _size(), and so on.

Extensibility and Events

To support extensibility and user customization of visualizations, all c3 visualizations will fire events to reflect the external API. Clients may attach handlers to these events to perform additional actions, further modify the DOM, attach more handlers to DOM elements, freely leverage D3, etc. These events are named to match the cooresponding external API. Events named with an "_start" appended will also be fired before the coorespdoning external API action is taken to allow customizations to perform actions either before or after the default built-in behaviour.

Styling

Visualizations generally have several approaches to determine the styles of various DOM elements with different performance and flexitility tradeoffs.

First, the c3 library itself sets various default styles for certain items. These generally are about functionality and it tries not to specify a default look.
The client may set up CSS stylesheet rules to determine how various DOM elements look. For example, the fill color for all area graphs may be set with ".c3.plot layer.area path { fill: red; }"
A CSS class can be assigned to a specific instance for per-chart styles. The class and classes properties in c3.Selection.Options are useful for this.
c3.Selection.Options.styles provides a mechanism to set styles for individual elements based on a constant or a callback function.
Finally, with the aid of events, the user can attach a handler and manually modify the DOM with complete freedom using D3, JQuery, direct W3C DOM API, or any other mechanism.

Examples:

Creating and extending a new visualization

var my_table = new c3.Table({
    anchor: '#my_div',
    data: [ 1, 2, 3, 4 ],
    columns: [
        {
            header: { text: "Number" },
            cells: { text: (datum)=> datum },
        }, {
            header: { text: "Squared" },
            cells: { text: (datum)=> datum * datum },
        }
    ]
});
my_table.on('redraw', function() { console.log("Table redraw was called; add customizations here."); });

Author:

Douglas Armstrong

Direct Known Subclasses

c3.Legend c3.Table c3.Chart

Variables Summary

_next_uid =

anchor =

undefined

[String, DOM node] Optional selector string or DOM node to attach visualization to. If no anchor is provided, then a div node is created but not attached to the DOM when you render(). The anchor proprety refers to this node so you can attach it to the DOM later as you wish.

Examples:

anchor: "#my_node"
anchor: $('#my_node')[0]
anchor: d3.select('#my_node').node()
anchor: d3.select('#your_node').append('div').attr('id','my_node').node()

height =

undefined

[Number,String] The height of the visualization in pixels. c3 will update this value when resize() is called based on the anchor size. Either c3 can initially set this value based on the anchor element size or the user can set it, in which case c3 will size the anchor element accordingly.

width =

undefined

[Number,String] The width of the visualization in pixels. c3 will update this value when resize() is called based on the anchor size. Either c3 can initially set this value based on the anchor element size or the user can set it, in which case c3 will size the anchor element accordingly.

anchor_styles =

undefined

[Object] Object pairs to set CSS styles. This is only called during initial rendering. Keys represent the style names and values are callbacks or values to set that style.

handlers =

undefined

[Object] An object to setup event handlers on the chart for user extensions with a declarative style. The keys represent the event names and the values are the cooresponding handlers. This is really just a shortcut for calling the on() method on your instantiated visualization object.

Instance Method Summary

# (void) render(opt) Bound Initial rendering
# (void) resize(width, height) Bound Resize the visualization explicitly or to match the size of its associated anchor div DOM element.
# (void) redraw(origin = 'redraw') Bound Update the visualization to reflect new/removed or updated data
# (void) restyle() Bound Restyle the elements to reflect updated data
# (void) init() Initialization
# (void) _prep()
# (void) _init()
# (void) size(width, height) Update state and scales based on current size of the anchor div DOM element
# (void) _size()
# (void) update(origin) Update DOM data bindings based on new or modified data set
# (void) _update()
# (void) draw(origin) Actually place DOM elements based on current scales.
# (void) _draw()
# (void) style(style_new) Set the DOM elements styles, classes, etc.
# (void) _style()

Constructor Details

# (void) constructor(opt)

Instance Method Details

# (void) render(opt) Bound

Initial rendering

Parameters:

opt ( Object ) — An options object that is used to extend the c3 visualization with its provided options.

# (void) resize(width, height) Bound

Resize the visualization explicitly or to match the size of its associated anchor div DOM element. Call this if the DOM element changes size in order to properly refresh the visualization.

Parameters:

width ( Number ) — Optional width to set the anchor DOM node width
height ( Number ) — Optional height to set the anchor DOM node height

# (void) redraw(origin = 'redraw') Bound

Update the visualization to reflect new/removed or updated data

# (void) restyle() Bound

Restyle the elements to reflect updated data

# (void) init()

Initialization

# (void) _prep()

# (void) _init()

# (void) size(width, height)

Update state and scales based on current size of the anchor div DOM element

Parameters:

width ( Number ) — Optional value to override the anchor width
height ( Number ) — Optional value to override the anchor height

# (void) _size()

# (void) update(origin)

Update DOM data bindings based on new or modified data set

# (void) _update()

# (void) draw(origin)

Actually place DOM elements based on current scales. This is separated from update() so resizing can update the DOM without needing to update data bindings.

Parameters:

origin ( String ) — The origin specifies the reason for this call to draw(), such as being initiated by a user call to redraw(), the initial render(), etc. This can be used for performance optimizations.

# (void) _draw()

# (void) style(style_new)

Set the DOM elements styles, classes, etc. This is separated from draw() so that users can update the styles of the visualization when the change doesn't need to rebind data and they know the change won't affect DOM element placement or size. instead of all of them, as a performance optimization. This is only a hint and is implementation specific.

Parameters:

style_new ( Boolean ) — A hint to the implementation if only the new elements should be updated,

# (void) _style()