ember-c3

Ember-C3

Ember component library for C3, a D3-based reusable chart library.

Live Demo: http://glavin001.github.io/ember-c3/

Alternatively take a look at Ember-NVD3 for your charting needs.

Ember Versions

Ember 2.18 and above

---

Installation

ember install ember-c3

Usage

For a complete set of examples, see the dummy app in tests/dummy/app/

Combination

Timeseries

Gauge	Pie	Donut

Basic

Where model is your C3 data:

{{c3-chart data=model}}

Using angle bracket invocation (see note below):

<C3Chart @data={{model}} />

Note: Angle brackets were available in Ember 3.4. An Ember bug prevented use of numbers in component names so will generate an error. The bug was fixed with PR #17552 which was merged into Ember 3.8. Ember-C3 can use angle brackets only with ember source 3.8 and later

Advanced

See http://c3js.org/examples.html for examples of how to use C3.

{{c3-chart
  c3chart=chart
  data=model
  axis=axis
  regions=regions
  bar=bar
  pie=pie
  donut=donut
  gauge=gauge
  line=line
  area=area
  grid=grid
  legend=legend
  tooltip=tooltip
  interaction=interaction
  subchart=subchart
  zoom=zoom
  point=point
  size=size
  padding=padding
  title=title
  color=color
  dtitle=dtitle
  transition=transition
  unloadDataBeforeChange=true
  oninit
  onrendered
  onmouseover
  onmouseout
  onresize
  onresized
}}

Component Properties

The properties match the corresponding C3 objects found in the C3 Documentation. As documented, most C3 settings (i.e. bar, axis, size, etc) can be included in the data object.

The component properties break out the settings to simplify chart configuration. Note: The chart type is always assigned in the chart data object.

The properties with an asterisk are the only ones updated on the chart when a property change is triggered when notifyPropertyChange is called. See examples in the dummy app.

Property	Description	Example
c3chart	Points to the C3 chart generated by the component. Any C3 api method can be executed using this property. See the methods section below, chart object and drill down examples	chart.hide("data1")
data*	C3 data object. Chart data is mutable after the chart is created
axis*	C3 axis object. See C3 examples for combining with data object. Chart axis are mutable after the chart is created
regions	need to test may need to be with data
bar	Used to assign bar chart properties
pie	Used to assign pie chart properties
donut	Used to assign donut chart properties
gauge	Used to assign gauge chart properties
line	Used to assign line chart properties
area	Used to assign area chart properties
point	Used to assign data point properties
grid	Used to show, hide and modify the graph grid. See docs
legend	Show, hide and modify the legend position. See docs
tooltip	Show, hide and modify the tooltip. See docs
interaction	Enable or disable interactions	interaction: { enabled: false }
subchart	Show, hide and modify C3 sub charts. See docs
zoom	Set C3 zoom features. See docs
size	Control chart size see docs	size: {width: 640 }
padding	Set padding around graph. See docs(https://c3js.org/reference.html#padding-top)	padding: { top: 20}
title	Set chart title	title: { text: "This is my chart" }
color*	Used to assign color properties. The chart colors are mutable after chart creation
dtitle	Use to dynamically change the chart title, which isn't supported natively by C3. See details below	{text: "My New Title", refresh: false}
transition	Equivalent to transition.duration. Default duration is 350ms. Transition times less than 300ms may not render properly. Use chart.load() and .unload() if shorter times are required
unloadDataBeforeChange	When set to true the data will be unloaded before new data is loaded with didUpdateAttrs(). Useful for pie and donut chart data changes. Also do data changes with .load() and .unload()
oninit	C3 chart event, see events section below	oninit=(action "init")
onrendered	C3 chart event, see events section below	onrendered=(action "render")
onmouseover	C3 chart event, see events section below	onmouseover=(action "mouseover")
onmouseout	C3 chart event, see events section below	onmouseout=(action "mouseout")
onresize	C3 chart event, see events section below	onresize=(action "resize")
onresized	C3 chart event, see events section below	onresized=(action "resized")

dtitle

The dtitle property is used to dynamically change a chart's title. C3 doesn't natively support this without forcing a chart redraw (.flush()) which can cause side effects. This especially true if the graph data is being dynamically changed using the api.

The title can be set using the .c3-title class but that doesn't provide abstraction from c3 internals.

dtitle gives you some control over side effects using a parameter to control how the graph is refreshed. An object is passed into dtitle and the second parameter refresh indicates whether all properties should be refreshed or only the chart title. Setting refresh to false will only refresh the title and ignore changes to the data, colors and axis properties. A short example is below. See the drill down example to see how dttile is used and potential side effects.

The chart's initial title is set using the title parameter.

{{c3-chart data=data title=title dtitle=dtitle}}

import Controller from "@ember/controller";
/* eslint ember/avoid-leaking-state-in-ember-objects: "off" */

export default Controller.extend({

  tile: { text: "Orignal title" },

  actions: {
    changeTitle() {
      this.set("dtitle", { text: "Updated title", refresh: false });
    }
  }
})

C3 Methods

If you assign a controller property to the c3chart property, you can use most of C3's api methods. Not all the methods have been tested.

templates/my-route.hbs

{{c3-chart data=mydata c3chart=chart}}

<button onclick={{action "loadUS"}}>US Cars</button>
<button onclikc={{action "loadGerman"}}>German Cars</button>
<button onclikc={{action "resetData"}}>Reset</button>

controllers/my-route.js

import { later } from "@ember/runloop";
import Controller from "@ember/controller";
/* eslint ember/avoid-leaking-state-in-ember-objects: "off" */

export default Controller.extend({
 chart: null,

 baseData:   
    { 
      columns: [
        ["US", 64],
        ["German", 36]
      ],
      type: "donut"
    },
 
 modelsGerman: [
        ["Mercedes", 12],
        ["Volkswagon", 54],
        ["BMW", 34]
      ],

  modelsUS: [
    ["Ford", 35],
    ["Chevy", 26],
    ["Tesla", 2],
    ["Buick", 10],
    ["Dodge", 27]
  ],

  actions: {
     resetData() {
      this.chart.load({ columns: this.baseData });
      this.chart.unload("Mercedes", "Volkswagon", 
      "BMW", "Ford", "Chevy", "Tesla", "Buick", "Dodge");
    },

    loadUS() {
      this.chart.load({ columns: this.modelsUS});
      this.chart.unload("US", "German");
    },
       
    loadGerman() {
      this.chart.load({ columns: this.modelsGerman});
      this.chart.unload("US", "German");
    }
  }
});

C3 Events

C3 emits two types of events - chart and data events. Chart events can be assigned to a closure action via a property. Data events must be assigned an action in the data object.

For connivence, the chart object is passed, with the exception of oninit to chart events. An example of a chart and data event is shown below. Note the use of bind for tying actions to data events. See the dummy app for more examples

templates/application.hbs

{{c3-chart 
  data=data
  oninit=(action 'init')
  }}

controllers/application.js

import Controller from "@ember/controller";
import { computed } from "@ember/object";
import { bind } from "@ember/runloop";

export default Controller.extend({
 data: computed(function() {
    // iris data from R
    return {
      columns: [
        ["data1", 30],
        ["data2", 120],
        ["data3", 10],
        ["data4", 45],
        ["data5", 90]
      ],
      type: "pie",
      onclick: bind(this, this.actions.onClick)
    };
  }),

 actions: {
    // oninit chart event
    init(chart){
      console.log("chart inited")
    },

    // data event - triggered when data point clicked
    onClick(d, i) {
      alert(`Data ${d.name} has a value of ${d.value}`)
    },
  }
});

Accessing D3

You can use the D3 library in your application by importing it where needed

import d3 from "d3";

Helpful Links

• Extending ember-c3 charts using base-component approach

Development

• git clone this repository
• npm install or yarn install
• ember server
• Visit your app at http://localhost:4200.
• npm run lint:hbs
• npm run lint:js
• npm run lint:js -- --fix

Running tests

• ember test – Runs the test suite on the current Ember version
• ember test --server – Runs the test suite in "watch mode"
• ember try:each – Runs the test suite against multiple Ember versions

Note: C3 chart events onresize and onresized are not tested

For more information on using ember-cli, visit https://ember-cli.com/.

Dummy app on gh-pages

Use npm run deploy to build and deploy dummy app to the gh-pages branch using ember-cli-github-pages

License

This project is licensed under the MIT License.

Changelog

v2.0.1

28 July 2019

• Document angle-bracket and Ember bug 6879294