Chart Sharing

The library includes a way to share the users chart as an image file with the CIQ.Share plugin. To use this plugin you will need the thirdparty HTML2Canvas script included with application. It can be found here. There are two main ways CIQ.Share can be used; either as a button the will share an image with the default parameters, or open a dialog to create a custom image.

Since the image is generated by HTML2Canvas it can be helpful to understand how the script works. Instead of taking a screenshot of your chart, HTML2Canvas will take a DOM element and scan it, rendering all of the elements down the DOM tree as an image via HTML5 Canvas's toDataURL method. By using HTML2Canvas the engine is able to draw dynamically added elements to the picture.

This approach does have some limitations however. HTML2Canvas will not render browser plugins like Java or Flash and does not work on iFrames. HTML2Canvas will render most common CSS properties but may encounter some it does not recognize. Because it relies upon a canvas to render it will have the same CORS limitations of any other canvas element. If you wish to host the script outside of your origin it will require a proxy. Additionally canvas security features like not allowing a tainted canvas to draw are enforced by default.

At its most basic functionality creating a shareable image consists of two actions. First the image is rendered by HTML2Canvas. Second a user may upload their image to a server to be shared. CIQ.Share.createImage handles instantiating the image of the chart. As a callback it commonly takes CIQ.Share.uploadImage. This decoupled functionality allows for the ability to create a dialog box to take custom parameters so an image can be customized. It is recommended that uploadImage creates a unique ID from the sever which can be passed back to the user and then shared. Each of these is handled by their own function while CIQ.Share.shareChart serves as a wrapper and will handle both parts in one function.

It is possible to create an image without using HTML2Canvas. To do this you would need to create a canvas and image like below:

CIQ.Share.createAlternateImage=function(stx,cb) {
    var image=document.createElement("img");
    var canvas=document.createElement("canvas");
    var context=canvas.getContext("2d");
    context.drawImage(image, 0, 0, stx.chart.canvas.width, stx.chart.canvas.height);
    return cb(null,canvas);

and call it with like this:

CIQ.Share.createAlternateImage(stxx, function(err, canvas){

Creating an image like this relies on an HTML5 Canvas's built in drawImage method. By setting the source of an image equal to your chart container, a canvas can export an image of the chart. By default the image will be a PNG but other image types can be specified. For more information on how to draw with a canvas visit MDN or W3Schools.