DEVELOPERS BLOG

Charts for BlackBerry 10 Apps

http://www.jafed.xyz

Adding charts to apps has always been a problem for developers. There isn’t an easy solution that allows for simple integration of charts in a BlackBerry 10 app. To solve this problem I have developed, and added to the Cascades examples on GitHub, a project that shows how to insert a chart with a few simple steps, allowing the possibility of reusing existing code. The type of charts available are:

  • Bar
  • Line
  • Radar
  • Polar Area
  • Pie & Doughnut
  • Bubble

The system is based on the integration of a web page inside a QML page in which the chart will be shown using a WebView component. You create the datasets, the labels and the options of the charts inside a Javascript function in the QML page which is sent to the HTML page. In that HTML page, another Javascript function catches, evaluates, and uses them using the ChartJS library. Then it creates and shows the final chart inside the app. The HTML page can return a response message to the WebView that you could use for a several purposes: one of them is to encode the chart to Base64, to save the image of the chart.

charts-for-bb10-process

The Javascript library used is ChartJS. The library is simple to integrate and to use. See the link for the complete documentation and all relative examples: (www.chartjs.org).

Using ChartJS is simple and the official documentation of the library is very rich. The only modification that you must do to your HTML page is adding code to get the messages that the WebView sends (see this link: https://developer.blackberry.com/native/documentation/ui/webview/javascript.html to understand how the WebView communicates with a HTML page).

To catch the message containing all the data for the creation of the chart, we should insert the following Javascript function inside the HTML page. The body of this function will contain the code for the display of the chart.

1
2
3
navigator.cascades.onmessage = function onmessage(message) {
   /** create the chart here **/
}

In practice, we see that the HTML page will always remain the same, except some modifications for specific uses (for example, the settings of the tooltips, the visualization of the axis, and for the labels). The Javascript code included in the QML for the generation of the parameters that build the chart will change relative to our chart settings.

To generate these parameters you must insert a WebView component in the QML page with the path to the HTML file assigned to the URL property (it’s necessary to add local: at the path. Ex: “local:///assets/html/crazyCharts.html”). You must create a Javascript function (inside the project that is named as example: createChart) which has the task of generating the parameters for the chart. They’re the datasets that you want to display, the labels to visualize on the horizontal axis, and the options that you want to assign to the chart. This function will convert the created object into a JSON string, which is sent to the HTML page.

In the WebView event onLoadingChanged the function just created will be called to generate the chart when the HTML page loads.

To summarize:

  1. The createChart function generates everything necessary for the creation of the chart (datasets, labels, and options), converts the Javascript objects in a JSON string, and sends it to HTML page with the WebView postMessage event.
  2. The HTML page catches the event from the attached function with navigator.cascades.onmessage and creates the chart with the data decoded from the received JSON string.
  3. Optionally, the HTML page can return a Base64 format string that encodes the image of the chart.

We mentioned how the HTML page response sent back to the WebView may have several uses. Indeed, in some situations, it’s necessary to get the image of the chart just created to save or use it inside the app. For this we can use toBase64Image() a method, available from the ChartJS library, that encodes the image in a Base64 string.

After the creation of the chart, the Javascript function of the HTML page converts the chart into a Base64 string and sends it as the response to the WebView using the function navigator.cascades.postMessage(base64string); The WebView receives the response in the event onMessageReceived and passes the obtained string to a C++ method for the conversion and saving of the image in PNG format. This function takes the Base64 string and the path where the image will be saved as input parameters, and it returns true or false in case of successful or not.

In this way, it’s possible to use the image inside the app or to share it.

I’ve created an example project in the Cascades-Community-Samples on GitHub with the name ChartsForBB10. The app is composed of 7 Tabs, 6 of them for the creation of each supported chart type, and the seventh Tab for viewing custom charts and the optional saving function for each chart.

 

Jacopo Federici

About Jacopo Federici

Jacopo Federici has been a BlackBerry 10 developer since 2011. He is a young Italian software engineer and spends much of his spare time developing code.