Orson Charts for HTML5


Getting Started

Here you will find step-by-step instructions to put 3D charts on your web pages, letting Orson Charts for HTML5 take care of all the heavy lifting. We'll show you how to set up:

...and we'll point you in the direction of the detailed configuration docs that will tell you about all the options for your charts so you can get them looking the way you want them to.

Things You Will Need

You should first download the latest orson-charts-web-1.0.zip file. It contains the Javascript files you need, and also a complete running version of the demo charts that you can refer to if you need to.

Next, you should create a basic HTML file and put the following in the head section:

    <script type="application/dart" src="orsoncharts_web.dart"></script>
    <script src="packages/browser/dart.js"></script>
    <script src="packages/browser/interop.js"></script>

Orson Charts for HTML5 is written using Google's Dart programming language and compiled to Javascript. The elements above take care of including the required scripts. Although the first script referred to is 'orsoncharts_web.dart', you should note that we don't have this file...at runtime, the file 'orsoncharts_web.dart.js' will be substituted.

Creating a Pie Chart

We'll begin by creating a pie chart, since this is the easiest to set up. When we are done, it should look something like this:

No canvas support?

First, let's add a canvas element to the HTML page to define where the chart will be rendered:

        <canvas id="pie_chart_canvas" height='400' width='600'>
          This is displayed if your browser does not support HTML5 Canvas.
        </canvas>

Next, we'll define the dataset for the pie chart by writing some very simple Javascript, like this:

        var dataset={
          keys: ['Milk Products', 'Meat', 'Wood/Logs', 'Crude Oil', 'Machinery', 'Fruit', 'Fish', 'Wine', 'Other'],
          values: [11625, 5114, 3060, 2023, 1865, 1587, 1367, 1177, 18870]
        };

The dataset object has a keys property that defines the labels for the pie sections (in an array), and a matching values property defining the corresponding data values (another array which should have the same length as the previous one). You can put whatever values you want in here, and you can call the object whatever you want (you'll see how it is used shortly).

Next, we'll provide configuration information for the chart, including the title and subtitle, again using some simple Javascript. We'll take the default values for most items, so the configuration is small:

        var chartConfig={
          title: 'New Zealand Exports 2012',
          subtitle: 'http://www.stats.govt.nz/browse_for_stats/snapshots-of-nz/nz-in-profile-2013.aspx',
          legend: { visible: false },
          style: 'Orson 2'
        };

Here the title and subtitle attributes should not require explanation. The legend property is a separate object within the config, but we set only one property on it (to hide the legend). The style property is used to apply a predefined visual style to the chart (this is optional, if you don't specify the style you will get the default appearance for the charts).

Now that we have a dataset object and a config object, we'll pass these objects plus the id of the target canvas element to the standard initialisation function provided by Orson Charts for HTML5 to set up a pie chart (configureOrsonPieChart3D()). Here is the complete script, which you can place (almost) anywhere in your HTML file:

        <!-- script for the pie chart -->
        <script type="application/javascript">
          function initMyPieChart() {
            var dataset={
              keys: ['Milk Products', 'Meat', 'Wood/Logs', 'Crude Oil', 'Machinery', 'Fruit', 'Fish', 'Wine', 'Other'],
              values: [11625, 5114, 3060, 2023, 1865, 1587, 1367, 1177, 18870]
            };
            var chartConfig={
              title: 'New Zealand Exports 2012',
              subtitle: 'http://www.stats.govt.nz/browse_for_stats/snapshots-of-nz/nz-in-profile-2013.aspx',
              legend: { visible: false },
              style: 'Orson 2'
            };
            configureOrsonPieChart3D('#canvas_id_1', chartConfig, dataset);
          }
        </script>

All that remains is to trigger this script when the page loads, so we place a call to initMyPieChart() in the onload handler:

<body onload="initMyPieChart();">

And that's it!


Creating a Bar Chart

Next, we'll move on to creating a bar chart. The steps are more or less the same as for the pie chart, but there are a few additional details (for example, the dataset is more complex and the chart has axes to configure). Once we are complete, we should have a bar chart that looks like this:

No canvas support?

The dataset is again a Javascript object, this time having three properties (rowKeys, columnKeys and dataValues):

        var dataset = {
          rowKeys: ['London', 'Geneva', 'Bergerac', 'Christchurch', 'Wellington'],
          columnKeys: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
          dataValues: [
            { key: 'London', rowValues: [7, 7, 10, 13, 17, 20, 22, 21, 19, 15, 10, 8] },
            { key: 'Geneva', rowValues: [3, 5, 9, 14, 18, 22, 25, 24, 20, 14, 8, 4] },
            { key: 'Bergerac', rowValues: [9, 11, 13, 16, 20, 23, 26, 26, 24, 19, 13, 9] },
            { key: 'Christchurch', rowValues: [22, 22, 20, 17, 14, 11, 11, 12, 14, 17, 19, 21] },
            { key: 'Wellington', rowValues: [20, 20, 19, 17, 14, 12, 11, 12, 13, 15, 17, 19] }
          ]
        };

The row keys and the column keys provide labels for the axes and can be used to identify individual data items. The data values array should contain one or more data series which have a series key (this identifies the series and is used in the chart's legend) and some data values. In this example, we are supplying data by row so the number of data values should match the number of column keys supplied earlier.

Now we can move on to the chart configuration, which is very straightforward (because we rely on mostly default values):

            var chartConfig={
              title: 'Average Maximum Temperature',
              subtitle: 'http://www.worldclimateguide.co.uk/climateguides/',
              plot: {
                renderer: { type: 'bar' },
                valueAxis: { label: 'Temp deg C' }
              },
              style: 'Orson 1',
              backgroundColor: '#EEE'
            };

The plot is configured as a Javascript object, itself containing sub-objects for the renderer and axis config. Here we simply specify the renderer type ('bar') and leave all other properties to their defaults. For the value axis (or y-axis if you prefer) we supply a label. The row and column axes will not have a label, since the category labels (city names and month names coming from the dataset) will be self-explanatory without a label.

As before, we include a script to pass the id of the target canvas element, the chart config and the dataset to the initialisation function (createOrsonCategoryChart3D()):

    <!-- script for the bar chart -->
    <script type="application/javascript">
      function initMyBarChart() {
        var chartConfig={
          title: 'Average Maximum Temperature',
          subtitle: 'http://www.worldclimateguide.co.uk/climateguides/',
          plot: {
            renderer: { type: 'bar' },
            valueAxis: { label: 'Temp deg C' }
          },
          style: 'Orson 2'
        };
        var dataset = {
          rowKeys: ['London', 'Geneva', 'Bergerac', 'Christchurch', 'Wellington'],
          columnKeys: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
          dataValues: [
            { key: 'London', rowValues: [7, 7, 10, 13, 17, 20, 22, 21, 19, 15, 10, 8] },
            { key: 'Geneva', rowValues: [3, 5, 9, 14, 18, 22, 25, 24, 20, 14, 8, 4] },
            { key: 'Bergerac', rowValues: [9, 11, 13, 16, 20, 23, 26, 26, 24, 19, 13, 9] },
            { key: 'Christchurch', rowValues: [22, 22, 20, 17, 14, 11, 11, 12, 14, 17, 19, 21] },
            { key: 'Wellington', rowValues: [20, 20, 19, 17, 14, 12, 11, 12, 13, 15, 17, 19] }
          ]
        };
        configureOrsonCategoryChart3D('#canvas_id_2', chartConfig, dataset);
      }
    </script>

Once again we need to trigger this function from somewhere, such as the onload handler:

<body onload="initMyPieChart();initMyBarChart()">

As an exercise, try changing the renderer type from bar to area and see the effect.

Creating a Scatter Chart

In this section we'll create a scatter chart similar to this one:

No canvas support?

A scatter plot is built from a dataset that contains one or more series of (x, y, z) data items. Unlike the bar chart in the previous section, all the axes on the plot are numerical. We distinguish between these two types of chart by referring to the bar charts as category charts (because two of the axes display categories) and scatter charts as xyz charts.

To create a dataset for our scatter plot, we use the following Javascript code:

          function createDataset(seriesCount) {
            var dataset = new Array(seriesCount);
            for (var s = 0; s < seriesCount; s++) {
              var data = new Array(50);
              for (var i = 0; i < 50; i++) {
                data[i] = [Math.random() * 10,  Math.random() * 100, Math.random() * 10];
              }
              dataset[s] = { series: 'Series ' + s, values: data };
            }
            return dataset;
          };
          
          var dataset = createDataset(5);

This function creates an array containing the requested number of data series, with each series hard-coded to contain 50 random (x, y, z) values. Each series is represented as a Javascript object with a series property (a string containing the series name) and a values property (an array containing any number of (x, y, z) items each represented as an array of length 3). In our example, each series has the same number of data items but this is not required.

The chart configuration should look familiar by now:

            var chartConfig={
              title: 'Scatter Chart Demo',
              subtitle: 'http://www.object-refinery.com/orsoncharts/',
              plot: {
                xAxis: { label: 'X', gridlinesVisible: true },
                yAxis: { label: 'Y', gridlinesVisible: true },
                zAxis: { label: 'Z', gridlinesVisible: true },
                dimensions:[5, 3, 5]
              },
              style: 'Orson 1',
              backgroundColor: '#EEE'
            };

We give labels to the three axes and set a flag on each one to ensure that gridlines are drawn for the axes. You should note the difference in axis naming between the scatter chart (xAxis, yAxis and zAxis) and the bar chart in the previous section (rowAxis, columnAxis and valueAxis). This is intentional and reflects the differences between xyz charts such as this scatter plot and category charts such as the bar chart in the previous section.

In addition, we set the dimensions for the plot (in world coordinates), to avoid the default cube shape. The absolute dimensions don't matter all that much because the viewing point can be moved in and out to change the size of the chart on screen, but the relative dimensions determine the shape of the plotting space.

Finally we need to call the configureOrsonXYZChart3D() method to set up the chart for rendering on the canvas. The complete script is:

        <script type="application/javascript">
          function createDataset(seriesCount) {
            var dataset = new Array(seriesCount);
            for (var s = 0; s < seriesCount; s++) {
              var data = new Array(50);
              for (var i = 0; i < 50; i++) {
                data[i] = [Math.random() * 10,  Math.random() * 100, Math.random() * 10];
              }
              dataset[s] = { series: 'Series ' + s, values: data };
            }
            return dataset;
          };

          function initMyScatterChart() {
            var dataset = createDataset(5);
            var chartConfig={
              title: 'Scatter Chart Demo',
              subtitle: 'http://www.object-refinery.com/orsoncharts/',
              plot: {
                xAxis: { label: 'X', gridlinesVisible: true },
                yAxis: { label: 'Y', gridlinesVisible: true },
                zAxis: { label: 'Z', gridlinesVisible: true },
                dimensions:[5, 3, 5]
              },
              style: 'Orson 1',
              backgroundColor: '#EEE'
            };
            configureOrsonXYZChart3D('#scatter_chart_canvas', chartConfig, dataset);
          }
        </script>

As with the other charts, this script needs to be triggered from somewhere, such as from the onload event.

<body onload="initMyPieChart();initMyBarChart();initMyScatterChart()">

Creating a Surface Chart

The final chart that we'll create is a surface chart:

No canvas support

A surface chart uses an xyz plot just like the scatter chart in the previous section, but it does not use a dataset. Instead, the chart gets data values by sampling a function that you define in Javascript. The function must take the form y = f(x, z). So our first step is to create a Javascript function that takes two numerical inputs and calculates a return value. It can be as simple as this:

      function myFunction(x, z) {
        return Math.sin(x * x + z * z);
      }

Next, we set up our chart configuration object to tell Orson Charts what the chart should look like:

            var chartConfig={
              title: 'Surface Chart',
              subtitle: 'y = sin(x^2 + z^2)',
              plot: {
                xAxis: { label: 'X', range: [-2, 2] },
                yAxis: { label: 'Y', range: [-2, 2] },
                zAxis: { label: 'Z', range: [-2, 2] }
              },
              renderer: {
                xSamples: 25, zSamples: 25,
                colorScale: { type: 'rainbow', range: [-1, 1] }
              },
              style: 'Orson 1',
              backgroundColor: '#EEE'
            };

For the axes, we provide labels and default ranges. Note that for the scatter chart in the previous section, we did not specify the axis ranges. They were, in fact, auto-calculated based on the values in the dataset. However, that's not possible for the surface chart because the function being plotted doesn't give any information about the required range of x and z values...so we specify the axis ranges manually.

For the renderer we specify the number of samples to take from the function and the color scale to use for the data values. We'll use a rainbow scale because it looks interesting.

Finally, we need to call the Orson Charts API to setup the chart to be rendered on our chosen canvas element:

        configureOrsonSurfaceChart3D('#canvas_id_3', chartConfig, myFunction);

Here is the complete script which you can put in your HTML file:

    <!-- script for the surface chart -->
    <script type="application/javascript">
      function myFunction(x, z) {
        return Math.sin(x * x + z * z);
      }
      function initSurfaceChart() {
        var chartConfig={
          title: 'Surface Chart',
          subtitle: 'y = sin(x^2 + z^2)',
          plot: {
            xAxis: { label: 'X', range: [-2, 2] },
            yAxis: { label: 'Y', range: [-2, 2] },
            zAxis: { label: 'Z', range: [-2, 2] }
          },
          renderer: {
            xSamples: 25, zSamples: 25,
            colorScale: { type: 'rainbow', range: [-1, 1] }
          },
          style: 'Orson 1',
          backgroundColor: '#EEE'
        };
        configureOrsonSurfaceChart3D('#canvas_id_3', chartConfig, 'myFunction');
      }
    </script>

As usual, don't forget that you'll need to trigger this function from somewhere such as the onload handler:

<body onload="initMyPieChart();initMyBarChart();initMyScatterChart();initMySurfaceChart();">

Summary

We've covered the steps to create four different types of charts in Orson Charts for HTML5. Hopefully you now have a good understanding of how to embed charts into your web pages. There are many more configuration options that you can use to change the appearance and behaviour of your charts, so please take a look through the following sections where all the options are described in detail.

User feedback is very important to us so, if you encounter any problems, or have suggestions for enhancements, please contact us (drop an e-mail to info@object-refinery.com, or phone us).

Configuration Reference

This section contains tables listing the configuration options for Orson Charts for HTML5, starting with the top-level chart configuration. The configuration usually contains nested objects defining the configuration for sub-elements in the chart, such as the legend, the plot, the axes and the renderer.

  • Chart
    • Legend
    • Plot (Pie Plot, Category Plot and XYZ Plot)
      • Axes (not for Pie Plot)
      • Renderer (not for Pie Plot)

Chart

There are many properties that can be defined for the chart. We've split them into two tables, with the first table containing content properties and the second table containing style properties.

Property:Description:
interactiveA flag that controls whether or not the user can zoom and rotate the chart. Set this to false for static charts.
legendConfiguration details for the chart's legend, specified as a Javascript object. See the legend property reference for details.
plotConfiguration details for the plot, specified as a Javascript object. See the plot property reference for details.
subtitleThe chart subtitle.
titleThe chart title.
titleAnchorThe anchor for the chart title (note that the subtitle automatically appears below the title, so this property affects the position of the subtitle also). Valid options are: 'top left', 'top center', 'top right', 'center left', 'center', 'center right', 'bottom left', 'bottom center' and 'bottom right'.
viewpointThe viewing point, specified as an array of four values [theta, phi, rho, orientation]. The first three values specify the viewing point in polar coordinates, where theta and phi are angles specified in radians. The viewer looks towards the origin (0, 0, 0) from the viewing point---bear in mind that the chart is centered on the origin. The orientation is another angle specified in radians and controls the rotation of the viewer about the axis from the viewpoint to the origin.

If no viewpoint is specified, the default setting has the viewer looking at the chart from directly in front and slightly above the chart (values [-PI / 2, 9 * PI / 8, 10, 0]).

The following table lists additional properties which only impact the style of the chart. There are some axis properties here that will be applied to all axes, but be aware that the same properties can be changed on a per-axis basis in the axis configuration.


Property:Description:
styleThe name of a predefined style to apply to the chart (valid options are 'Orson 1', 'Orson 2' and 'Pastel', more will be added later). This style is applied BEFORE any other style properties are applied (so that the additional style settings will override the defaults).
axisLabelColorThe foreground color used to display axis labels.
axisLabelFontThe font used to display axis labels.
axisTickLabelColorThe foreground color used to display axis tick labels.
axisTickLabelFontThe font used to display axis tick labels.
backgroundColorThe background color for the chart.
chartBoxColorThe color for the walls drawn by the chart box for a chart. Note that there is no chart box for a pie chart.
colorsAn array containing the standard colors for the chart. For example:

colors: ['#39618D', '#903A38', '#748B42', '#5F497A', '#368196']

Colors can be specified in the form '#RGB', '#RRGGBB' or '#RRGGBBAA'.
gridlineColorThe color to use for drawing gridlines.
gridlineStrokeThe line style to use for drawing gridlines.
subtitleBackgroundColorThe background color used to display the chart subtitle.
subtitleColorThe foreground color used to display the chart subtitle.
subtitleFontThe font used to display the chart subtitle.
titleBackgroundColorThe background color used to display the chart title.
titleColorThe foreground color used to display the chart title.
titleFontThe font used to display the chart title.

Legend

The following properties can be defined within a legend object in the chart configuration.

Property:Description:
visibleIf set to false, no legend will be shown for the chart.
anchorThe anchor point for the legend. Valid options are: 'top left', 'top center', 'top right', 'center left', 'center', 'center right', 'bottom left', 'bottom center' and 'bottom right'.
orientationThe orientation of the legend. Valid options are 'horizontal' and 'vertical'.
templateThe template string for the legend item text. Any occurrences of {0} in the string will be replaced with the series key, any occurrences of {1} will be replaced by the number of non-null data items in the series and occurrences of {2} will be replaced by the total of the non-null data items in the series.

Plot

The plot object in the chart configuration specifies properties for the plot. The available options depend on the type of chart. For area charts, bar charts and stacked bar charts, see the category plot reference. For pie charts, see the pie plot reference. For scatter charts and surface charts, see the xyz plot reference.


Category Plot

The following properties, which you can define within the plot object in the chart configuration, apply to category plots (area, bar and stacked bar charts) specifically.

Property:Description:
columnAxisConfiguration for the column-axis. The Axis and Category Axis tables list the available properties.
rendererConfiguration for the renderer used by the plot. It is mandatory to specify the renderer type for a category plot.
rowAxisConfiguration for the row-axis. The axis and Category Axis tables list the available properties.
valueAxisConfiguration for the value-axis. The Axis and Number Axis tables list the available properties.

Pie Plot

The following properties are defined within the 'plot' object in the 'chart' configuration, but apply only in the case of pie charts:

Property:Description:
radiusThe radius of the pie plot, specified in world units. The default value is 5.0.
depthThe depth of the pie plot, specified in world units. The default value is 0.6.
labelTemplateA string that is used as the template for creating pie section labels. Any occurrence of {0} in the string is replaced by the section label, any occurrence of {1} is replaced by the section value, and any occurrence of {2} in the template is replaced by the section percentage.
labelColorThe foreground color used to display pie chart section labels.
labelFontThe font used to display pie chart section labels.

XYZPlot

The following property applies to the XYZPlot specifically.

Property:Description:
dimensionsThe dimensions of the plot, specified in world units.
xAxisConfiguration for the x-axis. The Axis and Number Axis tables list the available properties.
yAxisConfiguration for the y-axis. The Axis and Number Axis tables list the available properties.
zAxisConfiguration for the z-axis. The Axis and Number Axis tables list the available properties.

Axis

This table presents the general configuration options that apply to all axes. These options can be applied in one of the axis configuration objects ('columnAxis', 'rowAxis', 'valueAxis', 'xAxis', 'yAxis' and 'zAxis') in the 'plot' configuration. There follow two additional tables that list options that are specific to category axes and numerical axes.

Property:Description:
labelThe axis label.
labelColorThe axis label foreground color. This is specified as a string in the form '#RGB', '#RRGGBB' or '#RRGGBBAA'. You can specify the color for all axis labels using the axisLabelColor property in the 'chart' config, so you would only use this property here if you want a different color for this axis.
labelFontThe axis label font. This is specified as an array containing two items, the font family string and the point size. For example: ['Courier', 12].
tickLabelFontThe axis tick label font. This is specified as an array containing two items, the font family string and the point size. For example: ['Courier', 12].
lineStrokeThe axis line stroke. This is specified as a Javascript object, refer to the Stroke reference for details.
lowerMarginThe lower margin for the axis, specified as a percentage of the axis length (the default value is 0.05 or five percent). When the axis range is auto-calculated to fit the current data, this margin is added to the lower end of the range.
rangeThe axis range. Specified using a Javascript array containing two items (the lower bound and the upper bound). For example: [-5.0, 10].
tickLabelColorThe axis label foreground color. This is specified as a string in the form '#RGB', '#RRGGBB' or '#RRGGBBAA'.
tickMarkColorThe color used to draw tick marks for the axis. This is specified as a string in the form '#RGB', '#RRGGBB' or '#RRGGBBAA'.
tickMarkLengthThe length for tick marks.
tickMarkStrokeThe stroke used to draw tick marks. This is specified as a Javascript object, refer to the Stroke reference for details.
upperMarginThe upper margin for the axis, specified as a percentage of the axis length (the default value is 0.05 or five percent). When the axis range is auto-calculated to fit the current data, this margin is added to the upper end of the range.
visibleA boolean flag that controls whether or not the axis is displayed.

Category Axis

The following properties apply only to category axes (the row and column axes on bar charts, stacked bar charts and area charts). These properties can be used in addition to those listed in the Axis section.

Property:Description:
gridlinesVisibleA boolean flag that controls whether or not grid lines are displayed for this axis.
isFirstCategoryHalfWidthA flag that controls whether the first category is a full or half width. By default it is a full width, but for some charts the appearance is better if the first category is just half the normal width.
isLastCategoryHalfWidthA flag that controls whether the last category is a full or half width. By default it is a full width, but for some charts the appearance is better if the last category is just half the normal width.
labelTemplateThe template used to generate axis labels. Any occurrence of {0} in the template is replaced by the category label, and occurrence of {1} is replaced by the count of the items in the category, and any occurrence of {2} is replaced by the sum of the non-null values for the category.

Number Axis

The following properties apply only to numerical axes (the value axis on bar charts, stacked bar charts and area charts, or any axis on an XYZPlot). These properties can be used in addition to those listed in the Axis section.

Property:Description:
gridlinesVisibleA boolean flag that controls whether or not grid lines are displayed for this axis.

Renderer

This table lists the properties that can be used to configure a renderer. This object is defined within the plot object in a chart configuration.

Property:Description:
typeThe type of renderer. Valid options are 'area', 'bar' and 'stacked bar'.

Surface Renderer

This table lists the properties that can be used to configure a surface renderer. The properties are added within the renderer configuration which is defined within the plot configuration.

Property:Description:
colorScaleConfiguration for the color scale used by the renderer, specified as a Javascript object. See the color scale reference for the properties that can be defined within this object.
xSamplesThe number of function samples taken along the x-axis. The default value is 25. Higher values give smoother plots, but take longer to render.
zSamplesThe number of function samples taken along the z-axis. The default value is 25. Higher values give smoother plots, but take longer to render.
drawFaceOutlinesA flag that controls whether or not the outlines of faces are drawn (in addition to filling the face). Outlines generally improve the quality of the rendering, but take longer to render.

Color Scale

This table lists the properties that can be used to configure a color scale (from within the surface renderer configuration).

Property:Description:
typeThe type of color scale ('fixed' or 'rainbow').
colorThe color for a fixed color scale.
rangeThe range for a rainbow color scale.