Logi JavaScript API for Chart Canvas Charts

The Logi JavaScript API for Chart Canvas Charts is a library that developers can use to work with Chart Canvas Charts. This topic provides information needed to work with the API.

 


About the API

The Logi JavaScript API allows you to interact with Chart Canvas Charts using JavaScript in order to customize them and/or refresh them periodically as needed. Data can be retrieved from the Info application server or directly from JSON sources and the visualization updated without redrawing the entire report page.

Scripts including the API functions can be executed by user interface actions, by using a timer, or by "listening" for data broadcast from an outside source. These are all discussed in the following sections.
 

Showing Initial Data

To show some initial data in a chart that will be updated automatically, use a datalayer under the chart or series as you normally would. This datalayer will run and provide data for the chart when the page is first loaded, or when its refreshed, but will not interfere with data delivered using this API.
 

Restrictions

 Logi Info licenses the underlying code for Chart Canvas Charts from a 3rd-party. However, we only license the part of their code library that we need, not the entire library, and our license does not include the right to allow developers to independently access the library. Developers who access the library directly in their Logi Info applications using the Logi API do so at their own risk, as we cannot guarantee that the library and/or our implementation of it will not change in future Logi Info releases.

Back to top

Getting the Chart Object

The API library is automatically included in your Logi Info v12+ application when you use Chart Canvas Charts; you do not need to take any special steps to include it in your definition. The first thing you need to do is get the chart object, using this function:

    rdGetChartCanvasObject(chartId)

Here's an example that assumes you have a Chart Canvas Chart element with the ID "myChartCanvas1":

var myChartObject = rdGetChartCanvasObject('myChartCanvas1');

 

With the chart object in hand, you can proceed to manipulate the chart data.  

Back to top

Updating Chart Data

To request new data from the Info application server and replace the data, if any, in the chart, use this chart object method:

    rdUpdateChartData([requestParams])
where requestParams is:
  • An optional JavaScript object,
  • Provided to the report definition as Request variables when the function is called,
  • Where the property name is the Request variable name and the property value is Request variable value.

Here's an example using the chart object from the previous section:

var requestParams = {};
requestParams.OrderDate = "01/01/2015";
requestParams.ProductCategory = "Seafood";
myChartObject.rdUpdateChartData(requestParams);

In a hypothetical report definition using this script, the Chart Canvas Chart element would have a child datalayer that made use of the request variables by using tokens. For example, using DataLayer.SQL, they might be used in a query like this: 

SELECT * FROM Orders WHERE OrderDate = '@Request.OrderDate~' AND Category = '@Request.ProductCategory~'

The query would return a result set in which the OrderDate column value = "01/01/2015" and the Category column value = "Seafood". The chart series would be updated with that result set. The same behavior applies whether the datalayer is a child of the Chart Canvas Chart element or a child of one of the Series elements.

Back to top

Appending Chart Data

To request new data from the Info application server and append it to existing data, if any, in the chart, use this chart object method:

    rdAppendChartData([requestParams], maxVisiblePoints)

where requestParams is:

  • An optional JavaScript object,
  • Provided to the report definition as Request variables when the function is called,
  • Where the property name is the Request variable name and the property value is Request variable value.

and maxVisiblePoints is:

  • A positive integer,
  • The threshold of total chart data points. The chart will delete old data points if the number of total points is greater than this value.
Here's an example using the chart object from the previous section:

var requestParams = {};
requestParams.OrderDate = "01/01/2015";
requestParams.ProductCategory = "Seafood";
myChartObject.rdUpdateChartData(requestParams, 100);

See the Updating Chart Data section for an explanation of how the requestParams can be used as Request tokens in retrieving data.

Back to top

Setting JSON Chart Data

To get the chart data directly from a JSON data source, without going to the application server, use this chart object method:

    rdSetChartData(chartOptions, [updateType], [maxVisiblePoints])

where chartOptions is:

  • A required JSON data object,
  • Containing chart options, using the standard Logi Info server chart data structure.

and updateType is:

  • An optional value,
  • Either 'UpdateData' (the default, which replaces the chart data) or 'AppendData', which appends the data.

and maxVisiblePoints is:

  • A positive integer,
  • Used only when updateType = 'AppendData',
  • The threshold of total chart data points. The chart will delete old data points if the number of total points is greater than this value.

Here's an example using the chart object from the previous section:

var chartOptions = {
   chart: {},
   series: [{
       id: 'mySeriesId',
       data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
   }]
};
myChartObject.rdSetChartData(chartOptions, 'UpdateData');  

Back to top

Using a Timer

If you want to update your chart at regular intervals, you can using the functions previously discussed with the JavaScript window.setInterval function:

 

var myPieChart = rdGetChartCanvasObject('pieChart');
window.setInterval(function () {
   myPieChart.rdUpdateChartData();
}, 3000); The numeric value (3000 in our example) is the interval, which is expressed in milliseconds. A script like this would be included using an Include Script element.

Back to top

Using "Pushed" Data

You can also refresh charts using data that's "pushed" to the browser. This type of update is ideal for a use case in which many users receive very frequent data updates while avoiding web server performance degradation and negative network bandwidth impacts.

This technique relies on a 3rd party service, like Pusher.com, to transmit the data to the application. These services essentially broadcast data received from a (Logi or non-Logi) data source application to your Logi application in the browser, using a protocol like Web Sockets. You Logi application in the browser listens for these broadcasts and uses the Real-Time Chart API to update your charts.

Here's an example:

An external PHP application (not shown) generates data periodically and sends it to Pusher.com.

The Pusher.com API library is included in our Logi definition using an Include Script File element, with its Script File attribute set to //js.pusher.com/2.2/pusher.min.js.

The following JavaScript code is included in the definition using an Include Script element:
 

// init the pusher API channel and bind the updates.
var pusher = new Pusher('yourPusherID');
var channel = pusher.subscribe('live_data');

channel.bind('new_data', function(data) {
    // when a message has been sent to the pusher API, it will enact this code block
    var dataObj = data.feed;

    // target and capture the line chart object
    var chartCanvasObject = rdGetChartCanvasObject('RealtimeDataChart');

    for($i = 0; $i < dataObj.length; $i++){
        // load the data records to the data array
        var myData = [];
        myData.push({
            x: new Date(dataObj[$i].datetime),
            y: parseInt(dataObj[$i].value)
        });
        
        // create the new chartOptions object
        var chartOptions = {
            chart:{},
            series: [{
                id: 'RealtimeLine',
                data: myData
            }]
        };
        
        // update the line chart
        if(chartCanvasObject != null){
            // append the new data to the existing chart series
            chartCanvasObject.rdSetChartData(chartOptions, 'AppendData', 100);
        }
     }
});
 

Whenever Pusher.com broadcasts new data, our Logi application will receive it and update the chart, without making a request to the Logi application web server or refreshing the web page.

Back to top

Events: beforeCreateChart and afterCreateChart

These two events can be used to customize Chart Canvas Chart options and properties. As you can guess, one event fires just before the chart is created and one just after it's created. The events include these parameters:
 

ParameterDescription
idThe Chart Canvas Chart element ID.
optionsThe chart options object: the options structure for the chart.
chartCanvas The Chart Canvas Chart container object.
chartThe chart object.

  Here's an example that uses the beforeCreateChart event to cause the text "n/a" to appear on two charts when there are null data values. First, here's the Logi element source code (note that the JavaScript code is follows separately):
 

<Division ID="divNewAPI_Events" >
  <ChartCanvas ID="verticalBarChart" >
    <DataLayer Type="Static" ID="StaticDataLayer1" >
      <StaticDataRow x="1" y="1" />
      <StaticDataRow x="2" y="2" />
      <StaticDataRow x="3" y="" />
      <StaticDataRow x="4" y="4" />
      <StaticDataRow x="5" y="" />
      <StaticDataRow x="6" y="6" />
      <StaticDataRow x="7" y="7" />
      <StaticDataRow x="8" y="8" />
      <StaticDataRow x="9" y="9" />
      <StaticDataRow x="10" y="10" />
    </DataLayer>
    <Series Type="Bar" ChartYDataColumn="y" ChartXDataColumn="x" >
    </Series>
  </ChartCanvas>
  <LineBreak />
  <ChartCanvas ID="horizontalBarChart" ChartOrientation="SwapAxes" >
    <DataLayer Type="Static" ID="StaticDataLayer2" >
      <StaticDataRow x="1" y="1" />
      <StaticDataRow x="2" y="2" />
      <StaticDataRow x="3" y="" />
      <StaticDataRow x="4" y="4" />
      <StaticDataRow x="5" y="" />
      <StaticDataRow x="6" y="6" />
      <StaticDataRow x="7" y="7" />
      <StaticDataRow x="8" y="8" />
      <StaticDataRow x="9" y="9" />
      <StaticDataRow x="10" y="10" />
    </DataLayer>
    <Series Type="Bar" ChartYDataColumn="y" ChartXDataColumn="x" >
    </Series>
  </ChartCanvas>
  <IncludeScript IncludedScript="(see the JavaScript code that follows)" />
</Division>  

And here's JavaScript code:

var verticalBarChartContainer = Y.one('#verticalBarChart');
verticalBarChartContainer.on('beforeCreateChart', function(e) {
    setNAFormatter(e);
});

var horizontalBarChartContainer = Y.one('#horizontalBarChart');
horizontalBarChartContainer.on('beforeCreateChart', function(e) {
    setNAFormatter(e);
});

function setNAFormatter (e) {
    if (e.options.series == null) {
        return;
    }

    if (!e.options.plotOptions) {
        e.options.plotOptions = {};
    }
    if (!e.options.plotOptions.column) {
        e.options.plotOptions.column = {};
    }
    e.options.plotOptions.column.dataLabels = {
        enabled: true,
        formatter: function () {
            var str;
            if (this.y !== null) {
                return this.y;
            } else {
                if (e.options.chart.inverted) {
                    var chart = this.series.chart,
                    offset = this.point.barX + 3;
                    chart.renderer.text('n/a', chart.plotLeft, chart.plotTop + chart.plotHeight - offset).add();
                } else {
                    var chart = this.series.chart,
                    offset = this.point.barX + this.point.pointWidth / 2 - 8;
                    chart.renderer.text('n/a', chart.plotLeft + offset, chart.plotTop + chart.plotHeight).add();
                }
            }
            return false;
        },
        crop: false,
        overflow: 'none'
    }
}

And the resulting charts look like this:
 

You can see, as shown above, that where there are no data values, the text "n/a" has been inserted.

Back to top

keyword: realtime