Version: 1.4.33
This plugin adds export capabilities to all amCharts products - charts and maps.
It allows annotating and exporting chart or related data to various bitmap, vector, document or data formats, such as PNG, JPG, PDF, SVG, JSON, XLSX and many more.
Please note that due to security measures implemented in modern browsers, some or all export options might not work if the web page is loaded locally (via file:///) or contain images loaded from different host than the web page itself.
bundled CSS file. I.e.:
<script src="amcharts/plugins/export/export.min.js"></script>
<link type="text/css" href="amcharts/plugins/export/export.css" rel="stylesheet">Or if you’d rather use amCharts CDN:
<script src="//cdn.amcharts.com/lib/3/plugins/export/export.min.js"></script>
<link type="text/css" href="//cdn.amcharts.com/lib/3/plugins/export/export.css" rel="stylesheet">(this needs to go after all the other amCharts includes)
export with default options:AmCharts.makeChart( "chartdiv", {
...,
"export": {
"enabled": true
}
} );AmCharts.makeChart( "chartdiv", {
...,
"export": {
"enabled": true,
"menu": [ {
"class": "export-main",
"menu": [ {
"label": "Download",
"menu": [ "PNG", "JPG", "CSV" ]
}, {
"label": "Annotate",
"action": "draw",
"menu": [ {
"class": "export-drawing",
"menu": [ "PNG", "JPG" ]
} ]
} ]
} ]
}
} );The plugin relies on a number of different libraries, to export images, draw annotations or generate download files.
Those libraries need to be loaded for the plugin to work properly.
There are two ways to load them. Choose the one that is right:
All libraries required for plugin operation are included withing plugins /libs subdirectory.
The plugin will automatically try to look in chart’s path property. If your plugin files are located within plugins folder under amcharts (as is the case with the default distributions), you don’t need to do anything - the libraries will load on-demand.
If you are using relative url, note that it is relative to the web page you are displaying your chart on, not the export.js library.
In case you’ve moved the libs folder you need to tell the plugin where it is "libs": { "path": "../libs/" }
You can also load all those JavaScript libraries by <script> tags. Since loading of libraries is on by default you will need to turn it off by setting "libs": { "autoLoad": false }
Here is a full list of the files that need to be loaded for each operation:
| File | Located in | Required for |
|---|---|---|
| fabric.min.js | libs/fabric.js/ | Any export operation |
| FileSaver.js | libs/FileSaver.js/ | Used to offer download files |
| pdfmake.min.js | libs/pdfmake/ | Export to PDF format |
| vfs_fonts.js | libs/pdfmake/ | Export to PDF format |
| jszip.js | libs/jszip/ | Export to XLSX format |
| xlsx.js | libs/xlsx/ | Export to XLSX format |
| Property | Default | Description |
|---|---|---|
| backgroundColor | #FFFFFF | RGB code of the color for the background of the exported image |
| enabled | true | Enables or disables export functionality |
| divId | ID or a reference to div object in case you want the menu in a separate container. | |
| fabric | {} | Overwrites the default drawing settings (fabricJS library) |
| fallback | {} | Holds the messages to guide the user to copy the generated output; false will disable the fallback feature |
| fileName | amCharts | A file name to use for generated export files (an extension will be appended to it based on the export format) |
| legend | {} | Places the legend in case it is within an external container (skip to chapter) |
| libs | 3rd party required library settings (see the above section) | |
| menu | [] | A list of menu or submenu items (see the next chapter for details) |
| pdfMake | {} | Overwrites the default settings for PDF export (pdfMake library) |
| position | top-right | A position of export icon. Possible values: “top-left”, “top-right” (default), “bottom-left”, “bottom-right” |
| removeImages | true | If true export checks for and removes “tainted” images that area lodead from different domains |
| delay | General setting to delay the capturing of the chart (skip to chapter) | |
| exportFields | [] | If set, only fields in this array will be exported ( data export only ) |
| exportTitles | false | Exchanges the data field names with it’s dedicated title ( data export only ) |
| columnNames | {} | An object of key/value pairs to use as column names when exporting to data formats. exportTitles needs to be set for this to work as well. |
| exportSelection | false | Exports the current data selection only ( data export only ) |
| dataDateFormat | Format to convert date strings to date objects, uses by default charts dataDateFormat ( data export only ) | |
| dateFormat | YYYY-MM-DD | Formats the category field in given date format ( data export only ) |
| keyListener | false | If true it observes the pressed keys to undo/redo the annotations |
| fileListener | false | If true it observes the drag and drop feature and loads the dropped image file into the annotation |
| drawing | {} | Object which holds all possible settings for the annotation mode (skip to chapter) |
| overflow | true | Flag to overwrite the css attribute ‘overflow’ of the chart container to avoid cropping the menu on small container |
| border | {} | An object of key/value pairs to define the overlaying border |
| processData | A function which can be used to change the dataProvider when exporting to CSV, XLSX, or JSON | |
| pageOrigin | true | A flag to show / hide the origin of the generated PDF ( pdf export only ) |
| forceRemoveImages | false | If true export removes all images |
We explained how you can define custom functions to be executed on click on export menu items.
Those functions can tap into plugin’s methods to augment it with some custom functionality.
Here’s an example:
"export": {
menu: [ {
label: "JPG",
click: function() {
this.capture({},function() {
this.toJPG( {}, function( data ) {
this.download( data, "image/jpg", "amCharts.jpg" );
});
});
}
} ]
}The above will use plugin’s internal capture method to capture it’s current state and toJPG() method to export the chart to JPEG format.
Yes, you’re right, it’s the exact equivalent of just including “JPG” string. The code is here for the explanatory purposes.
Here’s a full list of API functions available for your consumption:
| Function | Parameters | Description |
|---|---|---|
| toJPG | (object) options, (function) callback | Prepares a JPEG representation of the chart and passes the binary data to the callback function |
| toPNG | (object) options, (function) callback | Prepares a PNG representation of the chart and passes the binary data to the callback function |
| toSVG | (object) options, (function) callback | Prepares a SVG representation of the chart and passes the binary data to the callback function |
| toPDF | (object) options, (function) callback | Prepares a PDF representation of the chart and passes the binary data to the callback function |
| toJSON | (object) options, (function) callback | Prepares a JSON and passes the plain data to the callback function |
| toCSV | (object) options, (function) callback | Prepares a CSV and passes the plain data to the callback function |
| toXLSX | (object) options, (function) callback | Prepares a XLSX representation of the chart and passes the binary data to the callback function |
| toBlob | (object) options, (function) callback | Prepares a BLOB and passes the instance to the callback function |
| toCanvas | (object) options, (function) callback | Prepares a Canvas and passes the element to the callback function |
| toArray | (object) options, (function) callback | Prepares an Array and passes the data to the callback function |
| toImage | (object) options, (function) callback | Generates an image element which holds the output in an embedded base64 data url |
Since version 1.4.27 we’ve introduced the functionality to manage the annotations on the fly. The setter returns an array of objects, where each element represents an annotation. On the other hand the setter processes the given annotations within options (options.data). Both methods support the reviver callback which allows you to modify the annotations if needed.
| Function | Parameters | Description |
|---|---|---|
| getAnnotations | (object) options, (function) callback | Returns an array of objects where each element represents an annotation. |
| setAnnotations | (object) options, (function) callback | Draws the given annotations (options.data). |
Here’s an example how to insert annotations, please ensure your chart is in annotation mode:
chart.export.setAnnotations({
// Array of annotations, accepts this simple handwritten format or the detailed output of the getter
data: [{
top: 200,
left: 200,
text: "Test annotation",
type: "text"
}],
// Allows you to modify the annotation before it's being added into the canvas.
reviver: function(obj,index) {
obj.fill = "#FF00FF";
}
},function() {
// Callback when finished
});Unfortunately, Internet Explorer 9 has restrictions in place that prevent the download of locally-generated files. In this case the plugin will place the generated image along download instructions directly over the chart area.
To avoid having a bigger payload by including senseless polyfills to your site, you may need to add following metatag in your <head> of your HTML document.
<meta http-equiv="X-UA-Compatible" content="IE=edge" />This feature will kick in by default. If you want to disable it simply pass false to the fallback parameter.
"export": {
fallback: false
}In case you want to change our default messages you can modify it like following.
"export": {
fallback: {
text: "CTRL + C to copy the data into the clipboard.",
image: "Rightclick -> Save picture as... to save the image."
}
}This plugin requires at least 3.13 version of JavaScript Charts, JavaScript Stock Chart or JavaScript Maps.
The export will also need relatively recent browsers.
IE10 and up are supported.
Partial support for IE9; Fallback mechanism.
IE8 and older are not supported I’m afraid. Hey, it’s time to upgrade!
They’re all in subdirectory /examples.
You’re encouraged to modify, extend and make derivative plugins out of this plugin.
You can modify files, included in this archive or, better yet, fork this project on GitHub:
https://github.com/amcharts/export
We’re curious types. Please let us know (contact@amcharts.com) if you do create something new out of this plugin.
This plugin is licensed under Apache License 2.0.
This basically means you’re free to use or modify this plugin, even make your own versions or completely different products out of it.
Please see attached file “license.txt” for the complete license or online here:
libs.loadTimeout dependency namespace timeout used within onReady handlerfabric.loadTimeout loading image timeout to avoid blocking the export processexport.config.advanced.js sample config issue with drawing callbacksdelay property reset issue, did not get considered after first usagedrawing.enabled propery issue after first usage, stayed on true1.6.2forceRemoveImages in local enviroment (includes all “:" and”file://" sources)forceRemoveImages in local enviromentforceRemoveImages to remove images regardless if they are tainted or notclip-path issue on XY serial charts which exposed the drawn line beyond the plotarea.multiplier setting to scale the output image.exportFields option which is an array of fields to export in data formats (if you want to export just some fields as opposed to all fields)overflow flag to overwrite the css attribute ‘overflow’ of the chart containercolumnNames property, which allows overriding column names when expoerting chart dataexport.css which showed the canvasgatherClassName checking element typegetChartData which ignored given data array ( affected API usage only )reviver method to toSVG; converts by default RGBA to HEX colors codes and places it’s dedicated opacity propertyexportSelection exports the current data selectiondataDateFormat converts the date-strings to date objects with given formatdateFormat converts the date in given formatprocessData to format date fields and translate fieldsgatherChartData collects data, fields and titles only and uses processData to formatdrawing.menu individual menu items get prioritisedfileListener: truekeyListener: truetoArrayexportTitles available in general or individual setup which exchanges the data field names with it’s dedicated titletext/plain and image/* mime types (CSS has been modified)toImage method; returns img element with embedded base64 imagerygetBase64 option in toSVGtoImage usage in toPRINT to be able to choose the image type + settings.lossless option in toPRINT (experimental)