Introduction

Envision.js is a library for creating fast, dynamic and interactive visualizations. The library is rewrite of HumbleFinance, a library for HTML5 canvas finance visualization.

Features:

  • Modern Browsers, IE 6+
  • Touch / Mobile Support
  • HTML5 Finance Chart
  • HTML5 Time Series Chart
  • API for Custom Visualizations
  • Framework Agnostic
  • Adapted to Flotr2
  • Adaptable to Others

Usage

To use Envision.js, include envision.min.js and envision.min.css in your page. To display a visualization, either use a Template or create a custom visualization with the Envision.js API.

Templates

Templates are easy to use pre-made visualizations for common use-cases. Current templates include:

  • Finance - An HTML5 finance chart.
  • TimeSeries - A summary chart and a detail chart sharing an axis.

Template Example (view standalone)

Customization

This section is for people with a working knowledge of javascript, allowing the creation of custom visualizations using the Envision.js APIs. The existing templates are a good reference.

Further customization is possible using the Component config option. These are options passed to the underlying adapter/API (Flotr2 by default).

Custom Example (view standalone)

Data Format

The most basic data is a single series. This is an array of axes, each axis an array of points:

var data = [ // X Axis: [ 1, // x0 2, // x1 4.5 // x2 ], // Y Axis: [ 1, // y0 2, // y1 3 // y2 ] ];

Multiple series are represented by an array of series:

var data = [ // First series: [ [1, 2, 4.5], // X Axis [1, 2, 3] // Y Axis ], // Second Series: [ [1, 3, 4], // X Axis [2, 4, 1] // Y Axis ] ];

Per-series flotr configuration can be given as an object with a data member.

var data = [ // Points series: { points : { show : true }, data : [ [0,1,2,3,4,5,6,7,8,9,10], [0,1,2,1,0,1,2,1,0,1,2] ] } ];

Why this format?

Flotr (and many graphing libraries) use data that looks different. Usually, data is an array of points where each point is an array: (x, y) => [x, y] The data format in Envision has a couple advantages:

  • Compactness: the data is smaller to store, transfer and parse.
  • Memory: when animating or interacting with charts, data is created and destroyed in real time. Using just a couple arrays has a much smaller footprint than using an array for each point.
  • Processing: it is possible to use native array functions on individual axes

It is still possible to use a library's original data format. Simply add skipPreprocess : true in a components configuration to pass the data directly to the adapter. An example of this can be seen in the Ajax Demo.

Development

This section is for developers who wish to contribute to the project or create custom visualizations.

API

Classenvision.Component: Defines a visualization component.

Components are the building blocks of a visualization, representing one typically graphical piece of the vis. This class manages the options, DOM and API construction for an adapter which handles the actual drawing of the visualization piece.

Adapters can take the form of an actual object, a constructor function or a function returning an object. Only one of these will be used. If none is submitted, the default adapter Flotr2 is used.

Configuration:

An object is submitted to the constructor for configuration.

  • nameA name for the component.
  • elementA container element for the component.
  • heightAn explicit component height.
  • widthAn explicit component width.
  • dataAn array of data. Data may be formatted for envision or for the adapter itself, in which case skipPreprocess will also need to be submitted.
  • skipPreprocessSkip data preprocessing. This is useful when using the native data format for an adapter.
  • adapterAn adapter object.
  • adapterConstructorAn adapter constructor to be instantiated by the component.
  • adapterCallbackAn callback invoked by the component returning an adapter.
  • configConfiguration for the adapter.
Methods:
render([element])

Render the component.

If no element is submitted, the component will render in the element configured in the constructor.

draw([data], [options])

Draw the component.

trigger()

Trigger an event on the component's API.

Arguments are passed through to the API.

attach()

Attach to an event on the component's API.

Arguments are passed through to the API.

detach()

Detach a listener from an event on the component's API.

Arguments are passed through to the API.

destroy()

Destroy the component.

Empties the container and calls the destroy method on the component's API.

Classenvision.Visualization: Defines a visualization of componenents.

This class manages the rendering of a visualization. It provides convenience methods for adding, removing, and reordered components dynamically as well as convenience methods for working with a logical group of components.

Configuration:

An object is submitted to the constructor for configuration.

  • nameA name for the visualization.
  • elementA container element for the visualization.
Methods:
render([element])

Render the visualization.

If no element is submitted, the visualization will render in the element configured in the constructor.

This method is chainable.

add(component)

Add a component to the visualization.

If the visualization has already been rendered, it will render the new component.

This method is chainable.

remove()

Remove a component from the visualization.

This removes the components from the list of components in the visualization and removes its container from the DOM. It does not destroy the component.

This method is chainable.

setPosition(component, newIndex)

Reorders a component.

This method is chainable.

indexOf(component)

Gets the position of a component.

getComponent(component)

Gets the component at a position.

isFirst(component)

Gets whether or not the component is the first component in the visualization.

isLast(component)

Gets whether or not the component is the last component in the visualization.

destroy()

Destroys the visualization.

This empties the container and destroys all the components which are part of the visualization.

Classenvision.Preprocessor: Data preprocessor.

Data can be preprocessed before it is rendered by an adapter.

This has several important performance considerations. If data will be rendered repeatedly or on slower browsers, it will be faster after being optimized.

First, data outside the boundaries does not need to be rendered. Second, the resolution of the data only needs to be at most the number of pixels in the width of the visualization.

Performing these optimizations will limit memory overhead, important for garbage collection and performance on old browsers, as well as drawing overhead, important for mobile devices, old browsers and large data sets.

Configuration:

An object is submitted to the constructor for configuration.

  • dataThe data for processing.
Methods:
getData()

Returns data.

setData()

Set the data object.

length()

Returns the length of the data set.

bound(min, max)

Bounds the data set at within a range.

subsampleMinMax(resolution)

Subsample data using MinMax.

MinMax will display the extrema of the subsample intervals. This is slower than regular interval subsampling but necessary for data that is very non-homogenous.

subsample(resolution)

Subsample data at a regular interval for resolution.

This is the fastest subsampling and good for monotonic data and fairly homogenous data (not a lot of up and down).

Classenvision.Interaction: Defines an interaction between components.

This class defines interactions in which actions are triggered by leader components and reacted to by follower components. These actions are defined as configurable mappings of trigger events and event consumers. It is up to the adapter to implement the triggers and consumers.

A component may be both a leader and a follower. A leader which is a follower will react to actions triggered by other leaders, but will safely not react to its own. This allows for groups of components to perform a common action.

Optionally, actions may be supplied with a callback executed before the action is consumed. This allows for quick custom functionality to be added and is how advanced data management (ie. live Ajax data) may be implemented.

This class follow an observer mediator pattern.

Configuration:

An object is submitted to the constructor for configuration.

  • leaderComponent(s) to lead the interaction
Methods:
leader(component)

Add a component as an interaction leader.

follower(component)

Add a component as an interaction leader.

group(components)

Adds an array of components as both followers and leaders.

add(action, [options])

Adds an action to the interaction.

The action may be optionally configured with the options argument. Currently the accepts a callback member, invoked after an action is triggered and before it is consumed by followers.

Adapters

Envision is written to a particular interface. Other graphing libraries can be adapted to it or written specifically for it. For now, the best references are the code itself. The Flotr2 adapter is in js/adapters/flotr/ and a sample concrete object is in js/components/

Resources

Google Groups
Envision.js on Google groups

Issues

Please submit issues and pull requests on github at http://github.com/HumbleSoftware/envisionjs/issues.

Source

The source is available on github at http://github.com/HumbleSoftware/envisionjs.