Javascript Chart

Description

Adds a Javascript Chart to the component. Javascript Charts use client-side data and can be created and viewed in an offline environment.

 Contrasting Javascript Charts with the Chart Control

The Chart controls is a server-side control. The chart is rendered as a bitmap on the server and then the client-displays the bitmap image. Because the Chart control is a server-side control, it is not suited for disconnected applications. Also, since the Chart control is a server-side control, it will be slower than Javascript Charts.

To add a Javascript Chart to a UX component, select the [Javascript Chart] control in the Other Controls section of the UX toolbox.

The Chart control (i.e. the server-side charting control) is available in the Data Controls section of the UX toolbox.

After you add a Javascript Chart to your UX, you can then edit the Javascript Chart properties by clicking the smart field for the Chart properties property.

This will open the Javascript Chart builder, as shown below.

The top half of the screen is where you enter the Javascript code that generates the chart and the bottom half of the screen allows you to get a quick preview of the Chart.

In most cases you will get a quick start by selecting one of the Sample Charts. This will enter the Javascript for the selected chart and you can then tweak the Javascript to get the chart appearance that you want. You will likely also want to base the chart on real data, not the sample data shown in the sample chart.

To select a sample chart, click the Select Sample Chart button. This will open up a dialog showing the available sample charts:

Select the sample chart that you want. It will then fill in the Javascript for that chart into the builder. For example:

The Javascript shown in the window is the Javascript used by the RGraph charting library to render the Javascript chart.

 Understanding the Pattern Used for the Chart Javascript

All of the sample charts insert Javascript that follows the same pattern.

var _settings = function() {
    //function that returns an RGraph settings object
}

var _chart = new RGraph.SVG.Bar(_settings()).draw()

{dialog.object}._jsCharts['{chartName}'] = {};
{dialog.object}._jsCharts['{chartName}'].settings = [_settings];
{dialog.object}._jsCharts['{chartName}'].object = [_chart];

Depending the RGraph chart type (e.g. Pie, Line, Bar, etc.), the appropriate RGraph function is called to render the chart.

A settings object is passed to the RGraph function. This settings object is created by calling the _settings() function.

You do not need to include the RGraph charting Javascript libraries yourself in your UX component. The libraries are automatically loaded by Alpha Anywhere.

The Chart settings are stored in the _jsCharts object in the UX component object. These settings are stored to enable the chart to be refreshed with new data, to be changed on the fly by changing any of the chart properties, or to be dynamically resized. Notice that the settings object and the object object are arrays. This is because a chart can actually be composed of multiple charts each drawn on the same DIV.

The Javascript for the chart uses two special placeholders:

Placeholder
Description
{chartDiv}

The id of the div where the chart will be rendered.

{chartName}

The name of the chart. This resolves to the Chart Id shown in the Javascript Chart property sheet.

 Using Real Data in a Chart

When you select a Sample Chart, the Javascript that is inserted into the Javascript window in the Javascript Chart builder uses static data. This is fine initially when you are designing a chart, but at some point you will want to replace the static sample data with 'real' data.

The source of this 'real' data must be client-side data. For example, it might be data from a column in a List control. You will need to create a Javascript function that gets the data from the List and then set the data property in the Chart settings to the this function.

In many cases the 'real' data will be data that you want to get by querying a database, calling a service (REST, SOAP, etc.), or running some custom server-side code. In the case where the data you want to use in your chart originates on the server, you will need to define a Data Series that retrieves the necessary data. (When you define the Data Series you will need to specify that the Data Series data should be 'published' to the client-side.)

For example, here are the settings for a simple bar chart that uses static sample data:

var _settings = function() {
    var settings = {
        id: '{chartDiv}',
        data: [8,5,9,3,5,2,4],
        options: {
            gutterTop: 50,
            hmargin: 20,
            xaxisLabels: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
            tooltips: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],                
            title: 'A basic Bar chart',
            titleSubtitle: 'A chart showing daily values for a week',
            titleSubtitleItalic: true,                
            colors: ['#7e9cf6'],
            shadow: true,
            shadowOpacity: 0.2,
            attribution: false
        }
    };
    return settings;
}
var _chart = new RGraph.SVG.Bar(_settings()).draw();

Notice that the chart data is defined by the data property in the settings object.

Say we have a Javascript function that returns an array of values and we want to use the data returned by this function in the Chart. For example, the function that return an array of values could be defined as follows:

function getData() {
    return [1,2,3,4,5,6,7];
}

To base the Javascript Chart on the data returned by this function, we simply change the data property in the Chart settings to:

....
id: '{chartDiv}',
data: getData(),
options: {....

In the case where the data comes from a column in a List control, the Javascript function that gets the data would be something like this (assuming that the column in the List that contains the data is called 'Sales'):

function getData() {
    var lObj = {dialog.object}.getControl('myList');
    var _d = lObj._data //get list data
    var _a = []; //make empty array
    for(var i = 0; i < _d.length; i++) {
        _a.push(_d[i].Sales); //push data from the 'Sales' column onto the array
    };
    return _a;
}

If the data you want to use in your chart originates server-side, then you will need to create a Data Series. Assume you have created a Data Series called Sales, with two sub-series, Amount and Month.

The data in the Sales Data Series might look something like this:

MonthAmount
Jan200
Feb220
Mar190
Apr250
May270
Jun210
Jul300
Aug320
Sep290
Oct330
Nov300
Dec350

You can reference data from Amount column in the above Data Series using this syntax:

{dialog.object}._dataSeriesData.Sales.Amount

Using this syntax, you could change the settings object for the example bar chart to:

var _settings = function() { 
    var settings = {
        id: '{chartDiv}',
        data: {dialog.object}._dataSeriesData.Sales.Amount,
        options: {
            gutterTop: 50,
            hmargin: 20,
            xaxisLabels: {dialog.object}._dataSeriesData.Sales.Month,
            tooltips: {dialog.object}._dataSeriesData.Sales.Month,
            title: 'A basic Bar chart',
            titleSubtitle: 'A chart showing sales by month',
            titleSubtitleItalic: true,
            colors: ['#7e9cf6'],
            shadow: true,
            shadowOpacity: 0.2,
            attribution: false
        }
    };
    return settings;
}
var _chart = new RGraph.SVG.Bar(_settings()).draw();

Notice that the chart data, X axis labels and tooltips are all based on Data Series data.

 Any Property in the Chart Can Be Dynamic

In the above examples we have set the Chart's data property to the result of a Javascript function call (first example), or to the value in a Data Series (second example). However, it is not just the Chart's data property that can be dynamic. Any property in the Chart settings can be set to a Javascript function, or Data Series value.

For example, in the above example, the Chart Title is defined using this settings:

titleSubtitle: 'A chart showing sales by month'

This could be changed to:

titleSubtitle: getChartTitle()

 Working in the Javascript Chart Builder

When you are working in the Javascript Chart builder, the dialog has these buttons and hyperlinks.

The purpose of each of these tools is:

Tool
Action
Select Sample Chart

Opens a window showing sample charts. You can select a chart and the Javascript for the selected chart will be entered into the builder.

Preview Chart

Previews the chart in the bottom half of the window.

Define Chart CSS

In some cases your Chart settings will use CSS classes for some aspect of the Chart (for example, formatting tooltips). You can define the CSS classes here.

Color

Allows you to insert the value of a color into the Javascript code. If you highlight an existing color in the Javascript code before you click on the Color hyperlink, the highlighted color will be shown in the color picker. The color you select will be inserted into the Chart Javascript.

Property name

The Javascript shown in the code window after you select a Sample Chart typically only sets a small number of the available properties for the Chart. If you click the hyperlink you get a list of some of the other available properties. Note: This list may include properties that are not appropriate for the type of chart you are designing. To read documentation about the available properties, please refer to the RGraph web site. (http://RGraph.net)

Validate Javascript

The code you enter into the Code window in the Javascript Chart builder is Javascript. It must, of course, be valid Javascript. This hyperlink lets you validate the Javascript so you can check that you have not made any syntax errors when editing the sample code.

Select Data Series

If you want to set the value of any property in the Chart Settings to data in a Data Series you can click this hyperlink to insert the Javascript to reference a Data Series. When you click the hyperlink, a window showing all of the available Data Series will be shown. You can define new Data Series in this window. When you select a Data Series (and sub-series if the selected Data Series has sub-series) the appropriate Javascript is entered into the code.

 Setting a Chart's Background Color or Border

In some cases, you will want to set the background color or border of a chart. For example, the Chart shown below has a black background.

You can set the Chart background color and border using the Javascript Chart's Style property.

 Setting Javascript Chart Size to 100%

You can set the Javascript Chart width to 100% (useful when the Chart is shown in a Panel Card). However, setting the Chart's height to 100% is not supported. You must specify an explicit height for the Chart. Also, unlike many other UX controls, Javascript Charts do not have a Fill Container property.

If you set the Javascript Chart width to 100% and the Javascript Chart is contained inside a Panel Card, the Javascript Chart will automatically be resized when the device orientation is changed.

 Action Javascript Javascript Chart Actions

The Javascript Chart Action in Action Javascript allows you to:

Action
Description
Refresh Data in Chart(s)

Allows you to refresh the data in one or more Charts. If any of the selected Charts have any properties that are set to a Data Series, this action makes an Ajax callback to the server and refreshes the data in all of the referenced Data Series.

Resize a Chart

Resizes a chart. You can specify a new height and width for the Chart using CSS syntax. e.g. '500px'. You can use percentages for the width property, but not the height property. When the Chart is redrawn at its new size, by default, it will use the same draw method that was defined in the Chart settings. For example if the Chart is set to use animation when it is rendered, the Chart's 'draw method' will be 'grow' (or one of the other animation methods supported by RGraph). You might want the Chart to render at its new size without using animation. You can override the default draw method and specify an explicit draw method. For example, if the Chart was defined to use the 'grow' method, you can specify 'draw' to redraw the Chart without using animation.

Redraw a chart

Redraws a Chart. Like the Resize a Chart action, you can override the default 'draw method' when the Chart is redrawn. Typically used when one or more properties in the Chart settings are based on Javascript functions to re-render the Chart with new settings values returned by the Javascript functions.

Set Chart Properties

Allows you to explicitly set any of the Chart's properties and then redraw the Chart. Like the Resize a Chart action, you can override the default 'draw method' when the Chart is redrawn after its properties have been set.

 Methods

The following methods are available for working with Javascript charts:

 Building Dashboard Applications

Javascript Charts are ideal for 'dashboard' applications. You can design a UX component with multiple Javascript Charts each of which displays data on one of the metrics your dashboard is designed to monitor.

In situations where a large number of users are connected to the dashboard, and where you want to update the dashboards frequently, you can use Alpha Anywhere's Web-sockets feature to create an efficient application. Instead of having the UX component make periodic callbacks to the server to refresh the data shown in the dashboard charts, a scheduled CRON job on the server can update data for the dashboard, then broadcast the data to all of the connected UX components.

 Videos

Introduction

Javascript Charts allow you to create a variety of different chart types using Javascript. Because the charts are created client-side, using Javascript, these types of charts are ideal for disconnected applications where the Chart control cannot be used (as this control type produces charts server-side).

In this video we show how to set up a basic Javascript Charts.

2017-03-26

Binding Chart Data to a Javascript Function

The data shown in a Javascript Chart can be obtained by calling a Javascript function.

In this video show show how to bind the Chart data to a Javascript function.

Download Component

2017-03-26

Binding Chart Data to Data From a SQL Database - Using a Data Series for Chart Data

The data shown in a Javascript Chart can be obtained by querying a SQL database.

In this video show show how to bind the Chart data to data from a SQL database table by binding the Chart data to the data in a Data Series. The Data Series is populated with data from a SQL database table.

2017-03-26

Binding Chart Properties to a Javascript Function

Any property of a chart can be made dynamic by binding the property to the result of a Javascript function.

In this video we show how properties of the Chart (in addition to the Chart data) can be made dynamic.

Download Component

2017-03-26

Action Scripting Methods for Working With Javascript Charts

Action Scripting exposes several methods for working with Javascript Charts.

In this video we show how you can use Action Scripting to resize a Javascript Chart.

Download Component

2017-03-26

Action Scripting - Setting a Chart Property Using Action Scripting vs. Binding a Chart Property to a Javascript Function

Action Scripting allows you to dynamically change properties (such as the Chart colors, or title) after the Chart has been rendered. However, you can also achieve the same result by binding the Chart properties to Javascript functions.

In this video we contrast the two methods for setting Chart properties.

Download Component

2017-03-26

Using Action Scripting to Refresh Chart Data

Action Scripting allows you to refresh the data shown in a Chart. If the Chart data is based on a Data Series, an Ajax callback to the server will be made to refresh the data in the Data Series on which the Chart depends and then the Chart will be redrawn, showing the new data.

In this video we show how Action Scripting is used to refresh the Chart data.

2017-03-26

In Depth Example - Chart Based on SQL Data

This example shows a pie chart whose data is obtained from a multi-table SQL query against the sample Northwind database. The Chart is based on a custom Data Series to generate the Chart data. The user can select the country for which the Chart should be shown from a dropdownbox control.

In this video we show how this Chart is set up.

Download Component

2017-03-26

Understanding the Structure of the Javascript that Defines a Javascript Chart

The Javascript used to define a Javascript Chart has a well defined structure, described in this video.

2017-03-26

Javascript Chart Events

In this example we show a Chart with a Tooltip event. After the Chart is resized, the Tooltip events must be re-registered.

Download Component

2017-03-26

See Also