Getting Started

To use the Charts Control, include the following source files in your web page:

<!-- Dependencies --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/element/element-beta-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/datasource/datasource-beta-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/json/json-min.js"></script> <!-- OPTIONAL: Connection (enables XHR) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/connection/connection-min.js"></script> <!-- Source files --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/charts/charts-experimental-min.js"></script>

By default, the file charts.swf is expected in the assets directory relative to the location of the HTML page in which a Charts Control instance will appear. If you wish use charts.swf from yui.yahooapis.com, or if you'd like to place charts.swf in a different location on your own server, you may specify a path (relative to the page or absolute) by setting the following variable:

YAHOO.widget.Chart.SWFURL = "http://yui.yahooapis.com/2.5.2/build/charts/assets/charts.swf";

The Charts Control includes four different chart types. For the following example, we'll be using YAHOO.widget.ColumnChart.

Instantiating a DataSource

Just like the YUI DataTable Control, we use a DataSource object to structure the data that will populate the chart. In this example, the data for this chart lives in local memory within a JavaScript array:

YAHOO.example.puppies = [ { name: "Ashley", breed: "German Shepherd", age: 12 }, { name: "Dirty Harry", breed: "Norwich Terrier", age: 5 }, { name: "Emma", breed: "Labrador Retriever", age: 9 }, { name: "Oscar", breed: "Yorkshire Terrier", age: 6 }, { name: "Riley", breed: "Golden Retriever", age: 6 }, { name: "Shannon", breed: "Greyhound", age: 12 }, { name: "Washington" ,breed: "English Bulldog", age: 8 }, { name: "Zoe", breed: "Labrador Retriever", age: 3 } ];

Pass in the array reference YAHOO.example.puppies to the DataSource constructor and set the responseType to be JavaScript array. Next, define the known data fields for the puppy objects — these fields will map to the keys you define for the axes and optionally to the series that you define.

var myDataSource = new YAHOO.util.DataSource( YAHOO.example.puppies ); myDataSource.responseType = YAHOO.util.DataSource.TYPE_JSARRAY; myDataSource.responseSchema = { fields: [ "name","breed","age" ] };

Instantiating a ColumnChart

Now you are ready to instantiate your ColumnChart by passing in

1. the ID string or element reference of a container DIV element,
2. your DataSource instance, and
3. a set of configuration parameters, including the fields used by each axis to retrieve information from the DataSource.

Make sure the container DIV element is available in the DOM before instantiating your ColumnChart, either by placing the script in the HTML body after the markup has been rendered, or by using the Event Utility's onAvailable method to programmatically create your ColumnChart as soon as the container DIV element is available.

var myChart = new YAHOO.widget.ColumnChart( "myContainer", myDataSource, { xField: "name", yField: "age" });

Using Charts

The Charts Control provides many optional configuration parameters that help control how the your chart looks and behaves.

• Defining Multiple Series
• Specifying NumericAxis Bounds
• Customizing Axis Labels
• Custom Data Tip Text
• Basic Styling
• Styling Series and Markers
• Advanced Skinning

Defining Multiple Series

The first example above displayed a single series. Take a look at a more complex DataSource where we can extract more than one series to show in a chart.

YAHOO.example.monthlyExpenses = [ { month: "January", rent: 880.00, utilities: 894.68 }, { month: "February", rent: 880.00, utilities: 901.35 }, { month: "March", rent: 880.00, utilities: 889.32 }, { month: "April", rent: 880.00, utilities: 884.71 }, { month: "May", rent: 910.00, utilities: 879.811 }, { month: "June", rent: 910.00, utilities: 897.95 }, ]; var myDataSource = new YAHOO.util.DataSource(YAHOO.example.monthlyExpenses); myDataSource.responseType = YAHOO.util.DataSource.TYPE_JSARRAY; myDataSource.responseSchema = { fields: [ "month", "rent", "utilities" ] };

By creating a set of series definitions, you can display multiple series in a single chart; moreover, each series can be individually customized. In particular, the series type, display name, styles, and the keys it uses to access data from the DataSource can be modified.

var seriesDef = [ { displayName: "Rent", yField: "rent" }, { displayName: "Utilities", yField: "utilities" } ];

To pass a series definition to the chart, use the series attribute. Attributes may be set using the configuration hash in the constructor or by using the set() function.

new YAHOO.widget.LineChart( "myContainer", myDataSource, { xField: "month", series: seriesDef } );

Specifying NumericAxis Bounds

By default, charts with x and y axes automatically determine the minimum and maximum values based on the data that is being displayed. However, at times you might desire specific bounds on an axis. An axis object can be created and passed to the chart using either the xAxis or yAxis attributes, repectively.

var axisWithMinimum = new YAHOO.widget.NumericAxis(); axisWithMinimum.minimum = 800; myChart.set( "yAxis", axisWithMinimum );

Customizing Axis Labels

An axis exposes the ability to customize the text that appears in each label that appears along its length. This is exposed through the labelFunction property.

var currencyAxis = new YAHOO.widget.NumericAxis(); currencyAxis.labelFunction = "formatCurrencyAxisLabel"; function formatCurrencyAxisLabel( value ) { return YAHOO.util.Number.format( value, { prefix: "$", thousandsSeparator: ",", decimalPlaces: 2 }); } myChart.set("yAxis", currencyAxis);

Note: This function may be passed by name as a String or as a function reference.

Custom Data Tip Text

By default, the mouse-over data tip displays the name of the series the item appears within (if present), and the item data for each axis. Data tips on PieCharts also includes percentage information. If an axis has a labelFunction, the same function will be called to receive formatting.

With a dataTipFunction, developers have full control over the text that appears within the data tip.

function getDataTipText( item, index, series ) { var toolTipText = series.displayName + " for " + item.month; toolTipText += "\n" + formatCurrencyAxisLabel( item[series.yField] ); return toolTipText; } chart.set( "dataTipFunction", getDataTipText );

Note: This function may be passed by name as a String or as a function reference.

Basic Styling

Because the Charts Control is powered by Flash Player, standard browser CSS is not available for styling individual subcomponents of a chart. Instead, styleable properties are exposed through a style attribute on the chart itself. This hash accepts a standardized set of style values for things like border, background, fonts, padding, axis styles, and datatip styles.

new YAHOO.widget.LineChart( "myContainer", myDataSource, { xField: "month", series: seriesDef, style: { padding: 20, animationEnabled: false, border: { color: 0x995566, size: 2 }, font: { name: "Verdana", color: 0x995566, size: 12 } } });

The following section describes each of the top-level chart styles along with any substyles that may be available.

padding

A numeric value that specifies the spacing around the edge of the chart's contents. Unlike CSS padding in HTML, the chart's padding does not increase the dimensions of the chart.

animationEnabled

A Boolean value that specifies whether marker animations are enabled or not. The default value is true, meaning that markers will animate when data changes.

font

One may declare a font style to customize the default axis text, including the font name, size, color and more. It is represented as an Object value that contains several substyles.

name

Accepts a String that is either the name of the font or a list of comma-delimited font names, similar to the way font-family works in CSS.

color

A hex-formatted string or number value like "ff0000" or 0xff0000.

size

Accepts a numeric value for the point size. No other font size units are available.

bold

Boolean value to set if the font is displayed in bold.

italic

Boolean value to set if the font is displayed in italics.

underline

Boolean value to set if the font is displayed with an underline.

border

The border style allows a developer to add a colored border around the chart. The chart itself will decrease in dimensions to accomodate the border. It is represented as an Object value that contains several substyles.

color

A hex-formatted string or number value like "ff0000" or 0xff0000.

size

the border thickness in pixels

background

The background style allows one to customize the background color or image. It is represented as an Object value that contains several substyles.

color

Specifies the background fill color. If an image is present, this fill color will appear behind the image. Same accepted formats as color styles described above.

alpha

A value from 0.0 to 1.0 that refers to the transparency of the background color. This is most useful when used on the data tip background.

image

The URL of a JPG, PNG, GIF, or SWF image. May be relative or absolute. Relative URLs are relative to the HTML document in which the chart is embedded.

mode

The method used to display the background image. May be "repeat" (default), "repeat-x", "repeat-y", "no-repeat", or "stretch".

The mode value will be covered in more detail below in the Advanced Skinning section.

legend

The legend style lets a developer customize the appearance of the legend. It is represented as an Object value that contains several substyles.

display

Specifies the location where the legend will be drawn. Accepted values include "none", "left", "right", "top", and "bottom". The default value is "none".

spacing

A value that specifies the number of pixels between each of the items displayed in the legend.

padding

Same as the padding style described above.

border

Same as the border style described above.

background

Same as the background style described above.

font

Same as the font style described above.

dataTip

The dataTip style lets a developer customize the appearance of the data tip. It is represented as an Object value that contains several substyles.

padding

Same as the padding style described above.

border

Same as the border style described above.

background

Same as the background style described above.

font

Same as the font style described above.

xAxis and yAxis

The xAxis and yAxis styles allow one to customize the appearance of either axis. They are represented as Object values that contain several substyles.

color

The color of the axis itself. Same accepted formats as color styles described above.

size

A numeric value that represents the thickness of the axis itself. A value of 0 will hide the axis (but not the labels).

showLabels

If true, the labels are displayed. If false, they are hidden.

majorGridLines

Described below.

minorGridLines

Described below.

majorTicks

Described below.

minorTicks

Described below.

majorGridLines and minorGridLines

The majorGridLines and minorGridLines styles have a couple of substyles that need extra explanation. As shown above, majorGridLines and minorGridLines are substyles of the xAxis and yAxis styles.

color

The color of the grid lines. Same accepted formats as color styles described above.

size

A numeric value that represents the thickness of the grid lines. To hide the grid lines, set the size substyle to 0 (zero). If the grid lines are hidden by default, a thickness greater than zero must be specified to show them.

majorTicks and minorTicks

The majorTicks and minorTicks styles have a couple of substyles that need extra explanation. As shown above, majorTicks and minorTicks are substyles of the xAxis and yAxis styles.

color

The color of the ticks. Same accepted formats as color styles described above.

size

A numeric value that represents the thickness of the ticks. This style may need to be set to a valid numeric value greater than zero if the ticks are not shown by default.

length

The number of pixels the ticks extend from the axis. This style may need to be set to a valid numeric value greater than zero if the ticks are not shown by default.

display

Specifies how the ticks are drawn. Accepted values include "none", "inside", "outside", and "cross". In many cases, "none" is the default.

Note: Under certain conditions, even if the display substyle for minorTicks is a value other than "none", it is possible that no minor ticks will be drawn. The algorithm that calculates the minor divisions may determine that no minor divisions is the most ideal way to draw the chart.

Styling Series and Markers

Each individual series defined in the chart's series definition may be customized with a style attribute. The following example code expands the series definition created previously.

var seriesDef = [ { displayName: "Rent", yField: "rent", style: { color: 0xff0000, size: 20 } }, { displayName: "Utilities", yField: "utilities", style: { color: 0x0000ff, size: 30 } } ];

The styles defined above sets unique colors for each series, and the size of their markers.

Series Styles

The following styles are available for series definitions.

color

The color of the markers (and lines, where applicable) appear in the series. Same accepted formats as color styles described above.

colors

An Array of color values formatted as described by the color style. Used by the PieChart

size

A numeric value that represents the size of the markers in the series.

lineSize

A numeric value that represents the thickness of the lines in a line series. Available only on a series of type "line".

image

The URL of a JPG, PNG, GIF, or SWF image. May be relative or absolute. Relative URLs are relative to the HTML document in which the chart is embedded.

images

An Array of image URLs formatted as described by the image style. Used by the PieChart

mode

The method used to display the background image(s). May be "repeat" (default), "repeat-x", "repeat-y", "no-repeat", or "stretch".

connectPoints

A Boolean value that specifies whether lines are drawn between points on a line series. If false, a line series will only display markers, with no lines connecting those markers. Available only on a series of type "line".

connectDiscontinuousPoints

When true, a dashed line is drawn between points appearing before and after bad data (generally null or NaN values). Available only on a series of type "line".

discontinuousDashLength

A numeric value that represents the length of dashes on a discontinous line, in pixels. Available only on a series of type "line".

For more information about using the image-related styles, see the Advanced Skinning section below.

Advanced Skinning

The Charts Control accepts image URLs for background image styles (supported filetypes include JPG, PNG, GIF, and SWF). In an effort to mimic browser background image behavior, several image modes are available, including repeat, repeat-x, repeat-y, and no-repeat. An additional mode named stretch will increase the image dimensions to fill the entire background area.

style: { background: { image: "images/tile.png", mode: "repeat", color: 0xcc9900 } }

Note: Due to the cross-domain restrictions enforced by Adobe Flash Player, and the methods used to tile and layout background images, if you are loading the Charts Control from yui.yahooapis.com, the domain from which you load image assets must provide a crossdomain.xml to allow yui.yahooapis.com to load and manipulate image files. If no crossdomain.xml file is provided, your images will not be displayed. Again, this only applies if you are loading the Charts Control from yui.yahooapis.com. If the Charts Control is loaded from the same subdomain as the HTML page from which it is being used, cross-domain restrictions will not affect you.

The following is an example of the minimal crossdomain.xml file required to allow charts.swf to load images from your domain.

<?xml version="1.0"?> <!DOCTYPE cross-domain-policy SYSTEM "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd"> <cross-domain-policy> <allow-access-from domain="yui.yahooapis.com"/> </cross-domain-policy>

Image Modes

The following modes are accepted for background images used by the Charts control.

repeat

The image is tiled vertically and horizontally to cover the entire background area.

repeat-x

The image is tiled in one row horizontally.

repeat-y

The image is tiled in one column vertically.

no-repeat

The image is displayed once in the top-left corner.

stretch

The image is stretched to fill the entire background area. When using stretch, the image may distort if the aspect ratio of the Charts Control is different than that of the image.

If the image mode is set to repeat-x or repeat-y, or the background image contains transparency, the background color will be displayed through the areas that are not covered by the image.

For futher exploration of skinning the Charts control, please review the Charts Skinning Example.

Known Issues

• Charts appear on top of other content

  When other page content (such as Menu controls) overlap the Charts control, the Charts control may always appear on top in IE and Gecko-based browsers. To fix this problem, set the "wmode" of the Flash movie to either "transparent" or "opaque" using the wmode initialization attribute:

  var myChart = new YAHOO.widget.ColumnChart( "myContainer", myDataSource, { wmode: "opaque" });

• Hyphens cannot be used in DataSource field names

  Due to a bug in Adobe Flash Player's ExternalInterface, fields retrieved from the DataSource used by the chart may not contain hyphens. In the following example, the "dateofbirth" field is valid, but the "first-name" and "last-name" fields will cause errors.

  var myDataSource = new YAHOO.util.DataSource( YAHOO.example.employees ); myDataSource.responseType = YAHOO.util.DataSource.TYPE_JSARRAY; myDataSource.responseSchema = { fields: [ "first-name", "last-name", "dateofbirth" ] };

  If this bug is fixed in a future version of Flash Player, no modifications will be needed to the Charts Control to begin working with hyphenated field names, except to possibly change the minimum required version of Flash Player.

• Charts don't work inside a <form> tag with Internet Explorer

  SWFs embedded in HTML forms will not be initialized correctly when the page is viewed in Internet Explorer. When trying to embed a YUI chart into any descendant of a <form> tag, you may see an error that says yuigen0 not found and the chart will not be drawn. This problem has been fixed in Adobe Flash Player starting with version 9.0.115. If you must display a chart in an HTML form, you should override the version attribute to require a newer version of Flash Player:

  var myChart = new YAHOO.widget.ColumnChart( "myContainer", myDataSource, { version: "9.0.115" });

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.