Rev 23 | Blame | Compare with Previous | Last modification | View Log | RSS feed
# amCharts Data LoaderVersion: 1.0.15## DescriptionBy default all amCharts libraries accept data in JSON format. It needs to bethere when the web page loads, defined in-line or loaded via custom code.This plugin introduces are native wrapper that enables automatic loading of datafrom external data data sources in CSV and JSON formats.Most of the times you will just need to provide a URL of the external datasource - static file or dynamically generated - and it will do the rest.## Important noticeDue to security measures implemented in most of the browsers, the external dataloader will work only when the page with the chart or map is loaded via webserver.So, any of the examples loaded locally (file:///) will not work.The page needs to be loaded via web server (http://) in order to work properly.Loading data from another domain than the web page is loaded is possible but isa subject for `Access-Control-Allow-Origin` policies defined by the web serveryou are loading data from.For more about loading data across domains use the following thread:http://stackoverflow.com/questions/1653308/access-control-allow-origin-multiple-origin-domains## Usage### 1) Include the minified version of file of this plugin. I.e.:```<script src="amcharts/plugins/dataloader/dataloader.min.js" type="text/javascript"></script>```(this needs to go after all the other amCharts includes)### 2) Add data source properties to your chart configuration.Regular (Serial, Pie, etc.) charts:```AmCharts.makeChart( "chartdiv", {...,"dataLoader": {"url": "data.json","format": "json"}} );```Stock chart:```AmCharts.makeChart( "chartdiv", {...,"dataSets": [{...,"dataLoader": {"url": "data.csv","format": "csv","delimiter": ",", // column separator"useColumnNames": true, // use first row for column names"skip": 1 // skip header row}}]} );```That's it. The plugin will make sure the files are loaded and dataProvider ispopulated with their content *before* the chart is built.Some formats, like CSV, will require additional parameters needed to parse thedata, such as "separator".If the "format" is omitted, the plugin will assume JSON.## Complete list of available dataLoader settingsProperty | Default | Description-------- | ------- | -----------async | true | If set to false (not recommended) everything will wait until data is fully loadedcomplete | | Callback function to execute when loader is donedelimiter | , | [CSV only] a delimiter for columns (use \t for tab delimiters)emptyAs | undefined | [CSV only] replace empty columns with whatever is set hereerror | | Callback function to execute if file load failsinit | | Callback function to execute when Data Loader is initialized, before any loading startsformat | json | Type of data: json, csvheaders | | An array of objects with two properties (key and value) to attach to HTTP requestload | | Callback function to execute when file is successfully loaded (might be invoked multiple times)noStyles | false | If set to true no styles will be applied to "Data loading" curtainpostProcess | | If set to function reference, that function will be called to "post-process" loaded data before passing it on to chart. The handler function will receive two parameters: loaded data, Data Loader optionsprogress | | Set this to function reference to track progress of the load. The function will be passed in three parameters: global progress, individual file progress, file URL.showErrors | true | Show loading errors in a chart curtainshowCurtain | true| Show curtain over the chart area when loading datareload | 0 | Reload data every X secondsreverse | false | [CSV only] add data points in revers orderskip | 0 | [CSV only] skip X first rows in data (includes first row if useColumnNames is used)skipEmpty | true | [CSV only] Ignore empty lines in datatimestamp | false | Add current timestamp to data URLs (to avoid caching)useColumnNames | false | [CSV only] Use first row in data as column names when parsing## Using in JavaScript Stock ChartIn JavaScript Stock Chart it works exactly the same as in other chart types,with the exception that `dataLoader` is set as a property to the data setdefinition. I.e.:```var chart = AmCharts.makeChart("chartdiv", {"type": "stock",..."dataSets": [{"title": "MSFT","fieldMappings": [{"fromField": "Open","toField": "open"}, {"fromField": "High","toField": "high"}, {"fromField": "Low","toField": "low"}, {"fromField": "Close","toField": "close"}, {"fromField": "Volume","toField": "volume"}],"compared": false,"categoryField": "Date","dataLoader": {"url": "data/MSFT.csv","format": "csv","showCurtain": true,"showErrors": true,"async": true,"reverse": true,"delimiter": ",","useColumnNames": true}}}]});```### Can I also load event data the same way?Sure. You just add a `eventDataLoader` object to your data set. All the samesettings apply.## Adding custom headers to HTTP requestsIf you want to add additional headers to your data load HTTP requests, use"headers" array. Each header is an object with two keys: "key" and "value":```"dataLoader": {"url": "data/serial.json","format": "json","headers": [{"key": "x-access-token","value": "123456789"}]}```## Manually triggering a reload of all dataOnce chart is initialized, you can trigger the reload of all data manually bycalling `chart.dataLoader.loadData()` function. (replace "chart" with the actualvariable that holds reference to your chart object)## Using callback functionsData Loader can call your own function when certain event happens, like dataloading is complete, error occurs, etc.To set custom event handlers, use these config options:* "complete"* "init"* "load"* "error"* "progress"Example:```AmCharts.makeChart( "chartdiv", {...,"dataSets": [{...,"dataLoader": {"url": "data.json","init": function ( options, chart ) {console.log( 'Loading started' );},"load": function ( options, chart ) {console.log( 'Loaded file: ' + options.url );},"complete": function ( chart ) {console.log( 'Woohoo! Finished loading' );},"error": function ( options, chart ) {console.log( 'Ummm something went wrong loading this file: ' + options.url );},"progress": function( totalPercent, filePercent, url ) {console.log( 'Total percent loaded: ' + Math.round( totalPercent ) );}}}]} );```## Translating into other languagesDepending on configuration options the plugin will display a small number oftext prompts, like 'Data loading...'.Plugin will try matching chart's `language` property and display text prompts ina corresponding language. For that the plugin needs to have the translations.Some of the plugin translations are in **lang** subdirectory. Simply include theone you need.If there is no translation to your language readily available, just grab en.js,copy it and translate.The structure is simple:```'The phrase in English': 'Translation'```The phrase in English must be left intact.When you're done, you can include your language as a JavaScript file.P.S. send us your translation so we can include it for the benefits of otherusers. Thanks!## RequirementsThis plugin requires at least 3.13 version of JavaScript Charts, JavaScriptStock Chart or JavaScript Maps.## DemosThey're all in subdirectory /examples.## Extending this pluginYou're encouraged to modify, extend and make derivative plugins out of thisplugin.You can modify files, included in this archive or, better yet, fork this projecton GitHub:https://github.com/amcharts/dataloaderWe're curious types. Please let us know (contact@amcharts.com) if you do createsomething new out of this plugin.## LicenseThis plugin is licensed under Apache License 2.0.This basically means you're free to use or modify this plugin, even make yourown versions or completely different products out of it.Please see attached file "license.txt" for the complete license or online here:http://www.apache.org/licenses/LICENSE-2.0## Contact us* Email:contact@amcharts.com* Web: http://www.amcharts.com/* Facebook: https://www.facebook.com/amcharts* Twitter: https://twitter.com/amcharts## Changelog### 1.0.15* Added "emptyAs" config property. Empty CSV values will be set to this (default `undefined`)### 1.0.14* Added "init" event handler, which is called **before** loading starts### 1.0.13* Added "progress" handler, which can be used to monitor data load progress### 1.0.12* Better default options handling in external calls to AmCharts.loadFile* Fixed the latest version of Stock Chart not resetting to default pre-defined period* New example: Using Data Loader functions externally (map_json_external_function.html)### 1.0.11* New translation: Added French translation. Thanks Remy!* Tweaks to allow better animation after data load on Pie chart### 1.0.10* Fixed error related to headers not being set when using standalone data load functions### 1.0.9* Plugin will now ignore empty CSV lines by default (configurable with `skipEmpty` property)### 1.0.8* Added `headers` config variable which allows adding custom headers to HTTP requests### 1.0.7* Fixed an issue with the Pie chart when it is being loaded in inactive tab### 1.0.6* Added support for Gauge chart (loads `arrows` array)### 1.0.5* Fixed JS error if periodSelector was not defined in chart config* Now all callback functions (complete, error, load) receive additional parameter: chart* postProcess function will now have "this" context set to Data Loader object as well as receive chart reference as third paramater### 1.0.4* Added `chart.dataLoader.loadData()` function which can be used to manually trigger all data reload### 1.0.3* Fixed the bug where defaults were not being applied properly* Fixed the bug with translations not being applied properly* Cleaned up the code (to pass JSHint validation)### 1.0.2* Fixed the issue with modified Array prototypes### 1.0.1* Added `complete`, `load` and `error` properties that can be set with function handlers to be invoked on load completion, successful file load or failed load respectively* Fixed language container initialization bug* Fixed bug that was causing parse errors not be displayed### 1.0* Added GANTT chart support### 0.9.2* Added global data load methods that can be used to load and parse data by code outside plugin* Trim CSV column names* Translation added: Lithuanian### 0.9.1* Fix chart animations not playing after asynchronous load### 0.9* Initial release