This project contains the most advanced data visualization functionality available for Keen IO, and will soon be built directly into keen-js, replacing and upgrading the current visualization capabilities of that library.
What's new:
- Visualizations are powered by C3.js; a D3.js-based reusable chart library: check out what's available!
- Breaking changes from keen-js: learn more about upgrading
- Lightweight and blazing fast, with dramatic performance improvements
- Create custom cohort analysis and visualizations
Upgrading from keen-js? Read this.
This example setup demonstrates how to put this library to work.
Getting started:
If you haven't done so already, login to Keen IO to create a project. The Project ID and API Keys are available on the Project Overview page. You will need these for the next steps.
- Install the library and dependencies
- Create and configure a new Dataviz instance
- Load and parse data
- Render into the page
Advanced usage:
- Create custom cohort visualizations
- Create and visualize custom Dataset instances
- Create custom themes
- Create custom visualizations
There are several breaking changes and deprecations from keen-js.
- client.draw() is not part of this SDK – check out keen-analysis.js for fetching query results
- Method removal: the following methods are no longer necessary, and so they have been removed entirely:
.parseRequest(): this is now handled by.data()(learn more).dataType().adapter().initialize()
- Method deprecations: the following method names have been changed, but are still available as aliases:
.parseRawData()is now handled by.data().chartType()is now.type()(new).error()is now.message()(new)
- Internal architecture: the internals for each
Datavizinstance have changed dramatically. Please review the source if you have built something referencing these properties directly. - Dataset: the
Datasetinstance prototype and internal architecture have been heavily refactored:.input()has been removed, as instances no longer maintain the original raw input data.output()has been renamed to.data()(no alias)Dataset.parser()returns parsing functions for all standard API response types. These functions will correctly parse a given response and return a new Dataset instance. Learn more about these parsers
- Example setup demonstrates how to put all of this to work
- Contributing is awesome and we hope you do!
- Custom builds are encouraged as well - have fun!
Need a hand with something? Shoot us an email at [email protected]. We're always happy to help, or just hear what you're building! Here are a few other resources worth checking out:
Include keen-dataviz.js and keen-dataviz.css within your page or project. Visualizations are powered by the C3.js library, which itself requires D3.js. These dependencies are already included.
<html>
<head>
<meta charset="utf-8">
<!-- Use keen-analysis.js to fetch query results -->
<script src="//d26b395fwzu5fz.cloudfront.net/keen-analysis-1.1.0.js"></script>
<!-- Dataviz dependencies -->
<link href="//d26b395fwzu5fz.cloudfront.net/keen-dataviz-1.0.4.css" rel="stylesheet" />
<script src="//d26b395fwzu5fz.cloudfront.net/keen-dataviz-1.0.4.js"></script>
</head>
<body>
<!-- DOM Element -->
<div id='my-chart-div'></div>
<!-- Create and Render -->
<script>
var chart = new Dataviz()
.el('#my-chart-div')
.colors(['red', 'orange', 'green'])
.height(500)
.title('New Customers per Week')
.type('metric')
.prepare();
// Use keen-analysis.js to run a query
// and pass the result into your chart:
var client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
client
.query('count', {
event_collection: 'pageviews',
timeframe: 'this_14_days',
interval: 'daily'
})
.then(function(res){
// Handle the result
chart
.data(res)
.render();
})
.catch(function(err){
// Handle the error
chart
.message(err.message);
});
</script>
</body>
</html>This library can also be installed via npm or bower:
# via npm
$ npm install keen-dataviz
# or bower
$ bower install keen-dataviz
Create a new Dataviz instance. This chart variable will be used throughout this guide as a reference to a Dataviz instance.
var chart = new Keen.Dataviz()
.el('#dom-selector')
.height(280)
.title('Signups this week')
.type('metric')
.prepare();
// Fetch data from the API:
// Imaginary callback ...
chart
.data({ result: 621 })
.render();Learn more about the Dataviz API
This is an open source project and we love involvement from the community! Hit us up with pull requests and issues. The more contributions the better!
Learn about contributing to this project.
Run the following commands to install and build this project:
# Clone the repo
$ git clone https://github.com/keen/keen-dataviz.js.git && cd keen-dataviz.js
# Install project dependencies
$ npm install
# Build project with gulp
# npm install -g gulp
$ gulp
# Build and launch to view demo page
$ gulp
$ open http://localhost:9002/demo