# amCharts Export
Version: 1.3.3
## Description
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.
## Important notice
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.
## Usage
### 1) Include the minified version of file of this plugin as well as the
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)
### 2) Enable `export` with default options:
```
AmCharts.makeChart( "chartdiv", {
...,
"export": {
"enabled": true
}
} );
```
### ... OR set your own custom options:
```
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" ]
} ]
} ]
} ]
}
} );
```
## Loading external libraries needed for operation of this plugin
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:
### 1) Automatic (preferred)
All libraries required for plugin operation are included withing plugins */libs*
subdirectory.
The plugin will automatically try to look in chart's [`path`](http://docs.amcharts.com/3/javascriptcharts/AmSerialChart#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/" }`
### 2) Manual
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
## Complete list of available export settings
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](#adding-external-legend))
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](#delay-the-capturing-before-export))
exportTitles | false | Exchanges the data field names with it's dedicated title ( data export only )
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 chaper](#annotation-settings))
## Configuring export menu
Plugin includes a way to completely control what is displayed on export menu.
You can set up menus, sub-menus, down to any level. You can even add custom
items there that execute your arbitrary code on click. It's so configurable
it makes us sick with power ;)
The top-level menu is configured via `menu` property under `export`. It should
always be an array, even if you have a single item in it.
The array items could be either objects or format codes. Objects will allow you
to specify labels, action, icon, child items and even custom code to be executed
on click.
Simple format codes will assume you need an export to that format.
### Simple menu setup
Here's a sample of the simple menu setup that allows export to PNG, JPG and CSV:
```
"export": {
"enabled": true,
"menu": [ {
"class": "export-main",
"menu": [ "PNG", "JPG", "CSV" ]
} ]
}
```
The above will display a menu out of three options when you hover on export
icon:
* PNG
* JPG
* CSV
When clicked the plugin will trigger export to a respective format.
If that is all you need, you're all set.
Please note that we have wrapped out menu into another menu item, so that only
the icon is displayed until we roll over the icon. This means that technically
we have a two-level hierarchical menu.
If we opmitted that first step, the chart would simply display a format list
right there on the chart.
### Advanced menu setup
However, you can do so much more with the menu.
Let's add more formats and organize image and data formats into separate
submenus.
To add a submenu to a menu item, simply add a `menu` array as its own property:
```
"export": {
"enabled": true,
"menu": [ {
"class": "export-main",
"menu": [ {
"label": "Download as image",
"menu": [ "PNG", "JPG", "SVG" ]
}, {
"label": "Download data",
"menu": [ "CSV", "XLSX" ]
} ]
} ]
}
```
Now we have a hierarchical menu with the following topology:
* Download as image
* PNG
* JPG
* SVG
* Download data
* CSV
* XLSX
We can mix "string" and "object" formats the way we see fit, i.e.:
```
"export": {
"menu": [
"PNG",
{ "label": "JPEG",
"format": "JPG" },
"SVG"
]
}
```
The magic does not end here, though.
### Adding custom click events to menu items
Just like we set `label` and `format` properties for menu item, we can set
`click` as well.
This needs to be a function reference. I.e.:
```
"ex