index.mustache revision 0fdefaa9ca017edfb76b736c825b34186f33045a
124N/A <img src="{{componentAssets}}/img/chart-01.png" alt="Screenshot of the Charts widget" style="border: 1px solid #bfbfbf; float:right; height:150px; margin: 0 0 8px 8px; width:275px;">
124N/A The Charts module provides a JavaScript API for visualizing data in a variety of formats across a <a href="http://developer.yahoo.com/yui/articles/gbs">browser test baseline</a>. Based on device and browser capabilities, Charts leverages SVG, HTML Canvas and VML to render its graphical elements.
124N/A The Charts module features a `Chart` class that allows you to easily create a chart from a set of data. `Chart` extends `Widget` and includes configurable attributes that enable you to customize a Chart. Currently, the `Chart` widget can be used to create different variations and combinations of line, marker, area, spline, column, bar and pie charts.
3069N/A <p>By default, `Chart` creates a graph with lines and markers. This can be changed through the `type` attribute. Available values are listed below:
3878N/A <td>Visualizes quantitative data with a fill between an axis and relevant data points.</td></tr>
765N/A <td>Visualizes bars positioned vertically along a category or time axis. The bars' lengths are proportional to the values they represent along a horizontal axis.</td>
1792N/A <td>Visualizes bars positioned vertically along a category or time axis. The bars' lengths are proportional to the values they represent along a horizontal axis.</td>
765N/A <td>Combination of line, marker and area chart. By default, there is no area fill. This is the default type for a `Chart`.</td>
3817N/A <td>A circular chart divided into wedges which represent data as a percentage of a whole.</td>
3817N/A <td>Visualizes quantitative data on a graph by connecting relevant data points with a curve.</td>
<dt>CartesianChart</dt><dd>An application used to render multiple series to a graph with x and y axes. Many series can be rendered in a CartesianChart.</dd>
<p>When `Chart` is instantiated, the `type` attribute determines which class instance will be returned. A value of `pie` will return an instance of
`PieChart`. All other values will return an instance of `CartesianChart`. For the most part, this is a distinction that only occurs under the hood. As a
<p>The `Chart` widget adds the following key attributes, in addition to the attributes provided by the base <a href="../widget/index.html#attributes">Widget</a> class:</p>
<td>Axes to appear in the chart. This can be an object of axis instances or object literals used to construct the appropriate axes.</td>
<td>Indicates the key value used to identify a category axis in the `axes` hash. If not specified, the categoryKey attribute value will be used.</td>
<td>Indicates whether to use a `CategoryAxis` or `TimeAxis` for the `Chart` instance's category axis. The default value is category.</td>
<td>Direction of chart's category axis when there is no series collection specified. Charts can be horizontal or vertical. When the chart type is column, the chart is horizontal.
<td>Indicates the the `Chart` instance will fire `marker` or `planar` events. The default value is marker.</td>
<td>`Array`</td><td>Collection of series to appear on the chart. This can be an array of Series instances or object literals used to construct the appropriate series.
<td>A collection of keys that map to the series axes. If no keys are set, they will be generated automatically depending on the data structure passed into the chart.</td>
<p>The only required attributes for instantiating a `Chart` instance are `dataProvider` and `render`. The `render` attribute can be included
mychart.render("#mychart");
<p>The `Chart` widget requires an array for its source of data. The `Chart` widget will accept an array of object literals or arrays. When an array of arrays
is received, the values in the first index will be used for the category axis and all subsequent indices will be used for the value axis/axes. When an array of object literals is
received, all records with a key matching the `categoryKey` attribute will be used for the category axis with all other records used for the value axis/axes.</p>
<p>The underlying structure of the `dataProvider` is an array of object literals. If a `Chart` receives a multi-dimensional array for its
<p>The `Chart` class comes with a built-in simple tooltip. This tooltip can be customized or disabled with the `tooltip` attribute which contains the following
<tr><td>`hideEvent`</td><td>`String`/`Array`</td><td>Event that hides the tooltip. This allows you to specify which mouse event(s) hides the tooltip. You can also pass this an array of events and each event in the array will hide the tooltip. The default value is `mouseout`.</td></tr>
<tr><td>`markerEventHandler`</td><td>`Function`</td><td>Displays and hides a tooltip based on marker events.</td></tr>
<tr><td>`markerLabelFunction`</td><td>`Function`</td><td>Reference to the function used to format a marker event triggered tooltip's text. The markerLabelFunction has the following arguments:
<tr><td>`node`</td><td>`HTMLElement`</td><td>Reference (read-only) to the actual dom node of the tooltip.</td></tr>
<tr><td>`planarEventHandler`</td><td>`Function`</td><td>Displays and hides a tooltip based on planar events.</td></tr>
<tr><td>`planarLabelFunction`</td><td>`Function`</td><td>Reference to the function used to format a planar event triggered tooltip's text. The `planarLabelFunction` has the following arguments:
<dt>valueItems</dt><dd>Array of objects for each series that has a data point in the coordinate plane of the event. Each object contains the following data:
<tr><td>`showEvent`</td><td>`String`</td><td>Event that triggers the tooltip. This allows you to specify which mouse event will cause the tooltip to display. The default value is `mouseover`</td></tr>
<tr><td>`styles`</td><td>`Object`</td><td>Hash of CSS styles that are applied to the tooltip's node.</td></tr>
<p>The `styles` attribute can be used to update the properties of different chart components in a `CartesianChart`.
<tr><td>`axes`</td><td>`Object`</td><td>An object containing references to the `styles` attribute for each `Axis` instance in the chart.</td></tr>
<tr><td>`graph`</td><td>`Object`</td><td>A reference to the `styles` attribute of the chart applications's `Graph`.</td></tr>
<tr><td>`series`</td><td>`Object`</td><td>An object containing references to the `styles` attribute for each `CartesianSeries` instance in the chart.</td></tr>
<p>The `axes` attribute allows you to specify axes to be used in the chart. The `axes` attribute contains a hash of either `Axis` instances or
object literals containing information that the `Chart` will use to create axes. The most common use case is to use object literals. Below are the attributes available:
<tr><td>`alwaysShowZero`</td><td>`Boolean`</td><td>Ensures that zero appears on a `NumericAxis` when `minimum` and `maximum` are not explicitly set.</td></tr>
<tr><td>`keys`</td><td>`Array`</td><td>An array keys used to bind data from the `dataProvider` to the axis.</td></tr>
<tr><td>`labelFormat`</td><td>`Object`</td><td>Template for formatting labels. Used by `labelFunction` in `NumericAxis` and `TimeAxis` instances. For `TimeAxis` instances the `labelFormat` is an `STRFTime` string. For `NumericAxis` instances the `labelFormat` is an object literal containing the following properties:
<tr><td>`labelFunction`</td><td>`Function`</td><td>Function used to format label for display.</td></tr>
<tr><td>`maximum`</td><td>`Object`</td><td>The maximum value to display on an axis. (`TimeAxis` and `NumericAxis` only)</td></tr>
<tr><td>`minimum`</td><td>`Object`</td><td>The minimum value to display on an axis. (`TimeAxis` and `NumericAxis` only)</td></tr>
<tr><td>`position`</td><td>`String`</td><td>Position in relationship to the graph in which to place the axis. (top, right, bottom, left)</td></tr>
<tr><td>`roundingMethod`</td><td>`String`</td><td>Algorithm used for rounding units on a `NumericAxis` when `minimum` and `maximum` are not explicitly set.</td></tr>
<p>Sometimes you'll want to update an axis or a series after a chart has been instantiatied. This can be done with the `Chart`'s `getAxisByKey` and
`getSeries` methods. The `getAxisByKey` method looks up and returns an `Axis` instance based on its a key reference.</h4>
var leftAxis = mychart.getAxisByKey("values");
leftAxis.set("styles", {label:{rotation:-45}});
var mySeries = mychart.getSeries("category");
mySeries.set("visible", false);
var mySeries = mychart.getSeries(0);
mySeries.set("visible", false);
Charts load slowly in android devices. Performance optimizations will need to be added in a future release.
Planar interaction with chart types that do not include markers can be confusing. It is not readily apparent where to mouseover to display tooltips. This will be addressed in a future release.
Default mouse interactions are not intuitive for touch devices. For example, tooltips show and hide on `mouseover` and `mouseout` events. Analysis needs to be done to determine