Tutorial C3JS AngularJS Directives

Welcome to the tutorial for using the c3js angular directives. We created these directives to make it easier to integrate graphs in your AngularJS project.

Installation

If you want to run this tutorial you have to run this as a website. There are a few ways you can do this. For all means you have to get a copy from this github repository. You can download the zip/tar or clone the repository.

Setting up your project

Before you can show your graphs, you need to do the boilerplate stuff. You have to create an html page that loads the appropriate javascript libraries and stylesheets. The next code block shows this very basic html page.

Besides the html we also need a bit of JavaScript to initialize the application. The next code block shows initilizing the app and a controller.

That is it, before we move on to your first graph lets have a look at the different directives that are available. The main element is c3chart. All other directives are children of this element. This directive has a few attributes to configure the chart. The most important attribute is the bind-id, if you want multiple graphs on one page, this has to be unique. Other attributes are padding-top/right/left/bottom, show-labels, show-subchart and enable-zoom

Basic graphs

chart-column to provide the data

The first graph is just a line with a few data points. We start with the main element c3chart and configure it with the show-labels attribute. The second element is the chart-column. This is an important element, this element provides the data. It also configures how to present the data, the color of the line. The type of chart is specified by columns-type. The example uses line but feel free to play around with the column-type, see what happens when you change it to spline or bar for instance. The other two attributes in the example give the id to the data column-id, which is reused later on, and the name column-name.

chart-axes and chart-axis to configure the axes

Now there are a lot of options available to you to configure. We can add a second line of data, but we can also configure vertical axes. That is what we will do in the next example. We add a second chart-column element. This line1 and bar1 axis have a different scale, that is what we configure in the chart-axes element. The attributes y and y2 which columns use which y axis. If you have more than two chart-columns you can comma separate them to attach them to the two different vertical axes.

If you look at the horizontal bar, you see that the items are numbered. There is way to specify the values for the horizontal bar as well. You can use the attibute values-x. The value for this attribute should be the column-id of the chart-column element to use for the horizontal bar. In the next sample we demonstrate the use of text values for the horizontal button. Notice the chart-column with id x. To make this positioning work we have to introduce two other elements: chart-axis and chart-axis-x. The first element chart-axis has one attribute called axis-rotate. If you configure that, the axis are rotated, so x becomes vertical and y horizontal. The second element chart-axis-x has more attributes. The sample shows how to configure position, label and type. In our case the type is category since we are using textual labels. Other possible values are indexed and timeseries. Other attributes that you can configure are: axis-show, axis-localtime, axis-min and axis-max.

The same thing we did for the x-axis also exists for the y axis. Than you have to use the element chart-axis-y. The attibutes are almost the same, biggest difference is that we can have two of them. If you have two, you have to specify the id being y or y2. You cannot use the attribute localtime but you do have the additional attribute called exis-inverted to invert the y values.

chart-grid adds a grid to the graph

Another feature is that we can add a grid to the chart. We return to our one line of data chart and now add a horizontal grid. In the sample we add a horizontal grid, set show-y to true. But we also add two extra lines with a label. We have to configure the axis to use, the value to draw the line for and the label to place on top of the line.

chart-legend to configure the legend

You can hide the legend using the show-legend attribute. A more interesting property is the legend-position attribute. Legitimate values for this property are: bottom, right and inset. When inset is used you can also configure where to place the legend using one of the following values:top-left, top-right, bottom-left, bottom-right.

chart-tooltip

When moving you cursor over the chart points, you get a tooltip with the line name and the value. If you have multiple lines by default you see all the values for the same horizontal item. Using this directive you can hide the tooltip, but you can also disable the grouping of values. That way you only get the value for the line your cursor is on.

chart-size to change the dynamic nature of chart sizes

By default the chart fits within the space you give it. Maybe you have a good reason to explicitly set the size of a chart. This can be done with the chart-size directive. It has two attributes, chart-width and chart-height

chart-colors for more colors

With each chart-column you can speicfy a color. So why more color configuration. With this directive you can give a number of colors to use throughout the graph. That way you do not specify which color to take, but you do speify the colors to chose from.

chart-group to group data

If you have a bar chart with multiple chart-columns, the default behavior is to place the bars next to each other. You can also group the bars so that are stacked. That is what the following example shows. Using the chart-group directive we can use the group-values attribute. Give it a comma separated column id's that need to be grouped.

Chart specific configuration options

Gauge

You can create a gauge using column-type gauge. There are some specific configuration options that you can provide using the chart-gauge directive.

Pie

Creating a pie diagram is as easy as providing a number of chart-column elements. You can configure a few options using the chart-pie directive.

Donut

A donut is almost a pie, but without the middle. Threfore it has the same configuration options. One additional attribute is the title. This gives you a title in the middle of the donut.

And in the controller we than add the following format function

Point

When working with lines, you by default have points on the line. Sometimes you want to loose these points and sometimes you want to make them more expicit. That is what the chart-points directive is for. Using this directive you can make the points disappear or change the size. The following graph shows all options.

Interactive charts

There are a number of events available to interact with your charts. There are two different levels of events. There are events related to the complete chart like mouseover and mouseout, but also on initialize and on render. You can registere a callback to these events. But there are also events more related to the plotted data. You can respond to clicks on data points, but also on mouseovers and mouseout. All these callbacks are registered using the chart-events directive. In the example we show the on-data-click attribute. The other callback attribute are: on-init,on-mouseover,on-mouseout,on-resize,on-resized,on-rendered,on-click-data,on-mouseover-data and on-mouseout-data.

Data clicked: Name {{clicked.name}}, Value {{clicked.value}}

Time series data

The next chart is really different from all the other charts. Up till now we added the data using chart-column elements. In a lot of situations this is fine, but what if the data is dynamic of nature. Than we want to load the data using an angular controller. That is what this sample does. after clicking the button we generate 10 additional datapoints. Also the chart-columns are taken from a scope parameter. This is all taken care of using the attributes: chart-data, chart-columns and chart-x.