Getting Started

To include the source files for Charts and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('charts', function (Y) {
    // Charts is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using the charts widget

This section describes how to use the charts widget in further detail. It contains these subsections:

Instantiating A Chart

All you need to instantiate a chart is

1. A div container to render the chart.
2. An array to provide data for the chart.

*NOTE: By default, the chart will size itself to the dimensions of its container div. Be sure to include a width and height as demonstrated below:

CSS

#mychart {
    width: 600px;
    height: 400px;
}

HTML

<div id="mychart"></div>

JavaScript

// Data for the chart
var myDataValues = [
    {category:"5/1/2010", values:2000},
    {category:"5/2/2010", values:50},
    {category:"5/3/2010", values:400},
    {category:"5/4/2010", values:200},
    {category:"5/5/2010", values:5000}
];

// Instantiate and render the chart
var mychart = new Y.Chart({
    dataProvider: myDataValues,
    render: "#mychart"
});

By default, Chart creates a graph with lines and markers. This can be changed through the type attribute. Available values are listed below:

Chart Application

The Chart class acts as a facade for two underlying application classes:

CartesianChart

An application used to render multiple series to a graph with x and y axes. Many series can be rendered in a CartesianChart.

PieChart

An application used to render Pie Charts.

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 developer, this can be viewed as a single API.

Attributes

The Chart widget adds the following key attributes, in addition to the attributes provided by the base Widget class:

The dataProvider Attribute

The only required attributes for instantiating a Chart instance are dataProvider and render. The render attribute can be included in the configuration argument or called explicitly after instantiation.

mychart.render("#mychart");

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.

Multi-dimensional Array

var myDataValues = [
    ["5/1/2010", "5/2/2010", "5/3/2010", "5/4/2010", "5/5/2010"],
    [2000, 50, 400, 200, 5000]
];

Object Literal Array

var myDataValues = [
    {category:"5/1/2010", values:2000},
    {category:"5/2/2010", values:50},
    {category:"5/3/2010", values:400},
    {category:"5/4/2010", values:200},
    {category:"5/5/2010", values:5000}
];

The underlying structure of the dataProvider is an array of object literals. If a Chart receives a multi-dimensional array for its dataProvider, it will convert the array to an array of object literals.

Using the tooltip Attribute

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 properties:

tooltip: {
    setTextFunction: function(textField, val) {
        textField.setHTML(val);
    }
}

tooltip: {
    setTextFunction: function(textField, val) {
        textField.setHTML(val);
    }
}

Styling a CartesianChart with the styles Attribute

The styles attribute can be used to update the properties of different chart components in a CartesianChart.

Using the axes Attribute

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:

appendLabelFunction: function(textField, val) {
    textField.innerHTML = val;
}

appendTitleFunction: function(textField, val) {
    textField.innerHTML = val;
}

Referencing Series and Axis Instances

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.

Using getAxisByKey

var leftAxis = mychart.getAxisByKey("values");
leftAxis.set("styles", {label:{rotation:-45}});

The getSeries method will accept either an index or a key reference and return a series.

Using getSeries with a Key

var mySeries = mychart.getSeries("category");
mySeries.set("visible", false);

Using getSeries with an Index

var mySeries = mychart.getSeries(0);
mySeries.set("visible", false);

Using the legend Attribute

The legend attribute allows you to define a legend for your Chart instance. The legend is an object containing the attributes necessary for defining and styling the legend. You must include the 'charts-legend' module if you want have legends in your chart.

YUI().use('charts-legend', function (Y) {
    // Charts is available and ready for use. Add implementation
    // code here.
});

To see how to create a chart with a legend, check out the example. Below is a list of the available attributes.

Known Issues

• Custom formatting for tooltip's and axis title and labels has been updated for 3.5.0 and higher to prevent potential security vectors. This may cause backward compatibility issues when upgrading from 3.4.x and below under the following circumstances:

  • If you have written a custom labelFunction for your axis that is dependent upon innerHTML for formatting, the current implementation will need to be changed so that it will work with appendChild. Alternatively, there is a newly created appendLabelFunction attribute that can be overridden to use innerHTML. More information can be found under the labelFunction section here.
  • If you are dependent on innerHTML to format the value of an Axis title, you will need to pass in an HTMLElement that can be added using appendChild. Alternatively, there is a newly created appendTitleFunction attribute that can be overridden to use innerHTML. More information can be found under the title section here.
  • If you are using the tooltip attribute's markerLabelFunction or planarLabelFunction to add custom formatting to a chart's tooltip. You will need to update it so that is not dependent on innerHTML. The Customize a Chart's Tooltip example has been updated to demonstrate the correct way to construct a custom tooltip function. Alternatively, there is a newly created setTextFunction property of the tooltip attribute that can be overridden to use innerHTML. More information can be found under the markerLabelFunction and planarLabelFunction sections here.

• 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 the appropriate default events for touch devices. See the Using the tooltip Attribute section to see how to customize mouse events for the chart.