billboard.js 1.1.0 release!
Today we released the new v1.1.0 of billboard.js. Yay~!
We received bunch of bug report and feature requests from the community since the last release, and we were working hard to fulfill those requests.
For the full release note, please check the release note.
https://github.com/naver/billboard.js/releases/tag/1.1.0
In this article, we want share the details of the newly added features to give a detailed information.
If you don’t know about billboard.js, please visit the github repo.https://github.com/naver/billboard.js
New features
legend.contents
Prior this feature, to make custom legend was quite tedious. It needed to generate nodes and bind events manually.
To get rid these tedious job, billboard.js introduced templating syntax to generate a simple and fast legend contents.
How to use
There’re two ways to implement.
a) via template string for each item
b) via a function returning each item’s string
To implement a customized legend, the first thing you needs is a wrapper. Wrapper is the element which will contain each legend item contents.
You can set the reference of the wrapper as selector string or just simply the reference of the wrapper’s node element.
For example, if you want set legend contents to below element, just simply set ‘#legend’ for ‘document.getElementById(“legend”)’.
The events for focusing (depending the desktop or mobile), will be automatically binded, so you don’t have to bind manually.
a) Template string
Define each item’s html content string.
Within template string, there’re special syntax which can be used to relocate data’s color and title text.
- {=COLOR}: will be replaced with the data’s color value.
- {=TITLE}: will be replaced with the data’s title text.
And as result, will get:
Note: for the items, `bb-legend-item bb-legend-item-DATA_NAME` classes will be set by default to be consistent with the non-customized legend class name settings.
b) Function
Useful to manipulate each item’s content. For this function, two parameters are passed: title and color.
Let’s assume that you want not display one of the items. The below example will omit ‘data2’.
Just returning a falsy value(in this case ‘’), will be omitted to being displayed.
And as result, will get:
tooltip.order
This option will let order displaying tooltip’s data.
The accepted values for this option are:
- asc: Ascending order
- desc: Descending order
- function: Array.sort compareFunction
- null: Keeps data bindings order
Note: for stacked data, the order is reverted than the normal. Is because stacked data are rendered from bottom to the top.What was the issue?
Ordering option was for data only, and as you can see on below result, the bars rendered according the order option, but the tooltips are quite confusing in terms of ordering.
Stacked bar
Non-stacked bar
Internally, tooltip order was attached with the data order value and behaved wrogly and buggy.
Being more clear
To get rid all of this confusion, added new option `tooltip.order`.
This will allow order tooltip apart of data ordering and user can focus just only for tooltip ordering.
Stacked bar
Non-stacked bar
donut.title
With the new added enhancement, it allows adding a line break. Wihch permits rendering multilined texts.
What was the issue?
To add a line break after ‘Petal’, there was no way for that before, unless you manipulate nodes manually adding svg’s text node.
How to use
With the new relase, added new enhancement on multilining donut title text.
Just add ‘\n’ character where you want to add a line break.
The texts is automatically vertically centered according the line breaks count.
onbeforeinit / onafterinit
These new options permit run function before and after the initialization.
How to use
Just set a function to be executed for each initialization moment.
clipPath
Normally the area where chart elements are drawn, is clipped with clip-path attribute.
What was the issue?
Generating a chart with following options.
As you can see in the example below, the data points where placed at the baseline aren’t fully displayed, they’re clipped.
How to use
Simply set ‘clipPath’ option to false.
As you can see, the line element is positioned over axis element without clip.
The change you probably might know
The ‘clipPath’ option removes ‘clip-path’ attribute from <g class=bb-chart> element and change the position of DOM node hierarchy, positioning after the axis element nodes to make chart area to be over the axis elements.
DOM hierarchy when clipPath is: true
DOM hierarchy when clipPath is: false
data.onmin / onmax
For those who wants customize chart UI, it’s usual dealing with the minimum or maximum data value.
The usual example of this is making some emphasis(setting different color, adding text/image, etc.) in the higher(or lower) data point.
How to use
Let say, you generated a chart with the following options.
And wants emphasize the maximun data points(this case 10) changing point color and size.
Set onmax callback and select point elements applying style and attribute.
As you can see, the two data points which has value 10, are emphasized. This similar approach can be done with the minimum data points with the ‘data.onmin’ option.
Note: onmin/onmax callbacks are executed just at the initialization time. If you want keep emphasized style as example above, you need to handle separately.
data.labels.position
This option allow change the position of the label text position.
What was the issue?
When generating a chart with data label, the label texts are shown above the data points(in case of line type). Sometimes texts aren’t properly shown because of the position, in this case data points with value 0.
To handle this issuel before, needed select text nodes and change each nodes’ attribute to change the position.
How to use
Just simply declaring the x/y coords value, releatively its original position.
The following example, will be positioning text from its original, x + 10 and y + 8.
inputType.touch.preventDefault
Permit adjust the way of preventing default action on touch event.
What was the issue?
Let’s take a two different situation.
The first one, with the rotated chart. To get the each data points value, the usual action is swiping across the chart area, but when the document has a long content which can be scrolled, the swiping action isn’t work properly as expected.
Is quite annoying document scrolling and interrupts focusing the chart interaction.
Now let’s see the second case. The chart isn’t rotate, but document has a scrolling content.
The user will siwpe horizontally to get the data points value, but when swipe is mixed with the vertical direction, as you can see the swiping action is also interrupted with the document scrolling.
How to use
To prevent this interference of interaction, preventing the document scorlling is needed while swipe is in action.
Set preventDefault option to true to prevent scrolling.
With this option enabled, you can see for both cases no longer documents are scrolling.
This option also allow setting numeric value. Then numeric value means the threshold to determine if user wants document scrolling or wants get data from swipe action. The threshold is the distance of ‘touchstart — touchmove’ pixels.
Let’s imagine that user just wants document scroll and do a short touch(swipe) over chart area.
If the preventDefault is set to true, the document scrolling is prevented, but when you set a numeric value(let say 5), it determine if the user swipe action has been occured within 5 pixels.
If is less than 5, it doesn’t prevent scrolling, but if is equal or greater than 5, it prevent scrolling.
Online playground!
Since this release, we’re announcing online playground which can help generating chart on the fly!
This is an innitiative to bring a way to facilitating of generating with a variety of option which billboard.js brings.
https://naver.github.io/billboard.js/playground/
Logo
We recently added a new logo. It’s the mixture of typo and the bar chart.
It’s provided as svg files, which can be useful for representing the library in variety of display.
Hope to be more enjoyable when see the logo :)
- Basic
- Basic with white typo
- The bar symbol
What’s next?
For the next release, we’re planning add new chart type and of course, fixing bugs.
We’re trying to keep a regular release period of each 2 ~ 3 months, so there will be one more release within this year.
Thank you
Thank you, the community and all who showed us a great interest on billboard.js!
Since the first release on June 8th(2017), the download numbers are gradually going up(which means users are growing continuously) and this is the source of going forward to make a better chart library.
Also thanks for those whom contributed and made third-party apps! Your contribution and opinions are always worth to take.
See you soon on the next release.
From the billboard.js team.
