1# amCharts Data Loader 2 3Version: 1.0.15 4 5 6## Description 7 8By default all amCharts libraries accept data in JSON format. It needs to be 9there when the web page loads, defined in-line or loaded via custom code. 10 11This plugin introduces are native wrapper that enables automatic loading of data 12from external data data sources in CSV and JSON formats. 13 14Most of the times you will just need to provide a URL of the external data 15source - static file or dynamically generated - and it will do the rest. 16 17 18## Important notice 19 20Due to security measures implemented in most of the browsers, the external data 21loader will work only when the page with the chart or map is loaded via web 22server. 23 24So, any of the examples loaded locally (file:///) will not work. 25 26The page needs to be loaded via web server (http://) in order to work properly. 27 28Loading data from another domain than the web page is loaded is possible but is 29a subject for `Access-Control-Allow-Origin` policies defined by the web server 30you are loading data from. 31 32For more about loading data across domains use the following thread: 33http://stackoverflow.com/questions/1653308/access-control-allow-origin-multiple-origin-domains 34 35 36## Usage 37 38### 1) Include the minified version of file of this plugin. I.e.: 39 40``` 41<script src="amcharts/plugins/dataloader/dataloader.min.js" type="text/javascript"></script> 42``` 43 44(this needs to go after all the other amCharts includes) 45 46### 2) Add data source properties to your chart configuration. 47 48Regular (Serial, Pie, etc.) charts: 49 50``` 51AmCharts.makeChart( "chartdiv", { 52 ..., 53 "dataLoader": { 54 "url": "data.json", 55 "format": "json" 56 } 57} ); 58``` 59 60Stock chart: 61 62``` 63AmCharts.makeChart( "chartdiv", { 64 ..., 65 "dataSets": [{ 66 ..., 67 "dataLoader": { 68 "url": "data.csv", 69 "format": "csv", 70 "delimiter": ",", // column separator 71 "useColumnNames": true, // use first row for column names 72 "skip": 1 // skip header row 73 } 74 }] 75} ); 76``` 77 78That's it. The plugin will make sure the files are loaded and dataProvider is 79populated with their content *before* the chart is built. 80 81Some formats, like CSV, will require additional parameters needed to parse the 82data, such as "separator". 83 84If the "format" is omitted, the plugin will assume JSON. 85 86 87## Complete list of available dataLoader settings 88 89Property | Default | Description 90-------- | ------- | ----------- 91async | true | If set to false (not recommended) everything will wait until data is fully loaded 92complete | | Callback function to execute when loader is done 93delimiter | , | [CSV only] a delimiter for columns (use \t for tab delimiters) 94emptyAs | undefined | [CSV only] replace empty columns with whatever is set here 95error | | Callback function to execute if file load fails 96init | | Callback function to execute when Data Loader is initialized, before any loading starts 97format | json | Type of data: json, csv 98headers | | An array of objects with two properties (key and value) to attach to HTTP request 99load | | Callback function to execute when file is successfully loaded (might be invoked multiple times) 100noStyles | false | If set to true no styles will be applied to "Data loading" curtain 101postProcess | | 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 options 102progress | | 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. 103showErrors | true | Show loading errors in a chart curtain 104showCurtain | true| Show curtain over the chart area when loading data 105reload | 0 | Reload data every X seconds 106reverse | false | [CSV only] add data points in revers order 107skip | 0 | [CSV only] skip X first rows in data (includes first row if useColumnNames is used) 108skipEmpty | true | [CSV only] Ignore empty lines in data 109timestamp | false | Add current timestamp to data URLs (to avoid caching) 110useColumnNames | false | [CSV only] Use first row in data as column names when parsing 111 112 113## Using in JavaScript Stock Chart 114 115In JavaScript Stock Chart it works exactly the same as in other chart types, 116with the exception that `dataLoader` is set as a property to the data set 117definition. I.e.: 118 119``` 120var chart = AmCharts.makeChart("chartdiv", { 121 "type": "stock", 122 ... 123 "dataSets": [{ 124 "title": "MSFT", 125 "fieldMappings": [{ 126 "fromField": "Open", 127 "toField": "open" 128 }, { 129 "fromField": "High", 130 "toField": "high" 131 }, { 132 "fromField": "Low", 133 "toField": "low" 134 }, { 135 "fromField": "Close", 136 "toField": "close" 137 }, { 138 "fromField": "Volume", 139 "toField": "volume" 140 }], 141 "compared": false, 142 "categoryField": "Date", 143 "dataLoader": { 144 "url": "data/MSFT.csv", 145 "format": "csv", 146 "showCurtain": true, 147 "showErrors": true, 148 "async": true, 149 "reverse": true, 150 "delimiter": ",", 151 "useColumnNames": true 152 } 153 } 154 }] 155}); 156``` 157 158### Can I also load event data the same way? 159 160Sure. You just add a `eventDataLoader` object to your data set. All the same 161settings apply. 162 163 164## Adding custom headers to HTTP requests 165 166If you want to add additional headers to your data load HTTP requests, use 167"headers" array. Each header is an object with two keys: "key" and "value": 168 169``` 170"dataLoader": { 171 "url": "data/serial.json", 172 "format": "json", 173 "headers": [{ 174 "key": "x-access-token", 175 "value": "123456789" 176 }] 177} 178``` 179 180 181## Manually triggering a reload of all data 182 183Once chart is initialized, you can trigger the reload of all data manually by 184calling `chart.dataLoader.loadData()` function. (replace "chart" with the actual 185variable that holds reference to your chart object) 186 187## Using callback functions 188 189Data Loader can call your own function when certain event happens, like data 190loading is complete, error occurs, etc. 191 192To set custom event handlers, use these config options: 193 194* "complete" 195* "init" 196* "load" 197* "error" 198* "progress" 199 200Example: 201 202``` 203AmCharts.makeChart( "chartdiv", { 204 ..., 205 "dataSets": [{ 206 ..., 207 "dataLoader": { 208 "url": "data.json", 209 "init": function ( options, chart ) { 210 console.log( 'Loading started' ); 211 }, 212 "load": function ( options, chart ) { 213 console.log( 'Loaded file: ' + options.url ); 214 }, 215 "complete": function ( chart ) { 216 console.log( 'Woohoo! Finished loading' ); 217 }, 218 "error": function ( options, chart ) { 219 console.log( 'Ummm something went wrong loading this file: ' + options.url ); 220 }, 221 "progress": function( totalPercent, filePercent, url ) { 222 console.log( 'Total percent loaded: ' + Math.round( totalPercent ) ); 223 } 224 } 225 }] 226} ); 227``` 228 229## Translating into other languages 230 231Depending on configuration options the plugin will display a small number of 232text prompts, like 'Data loading...'. 233 234Plugin will try matching chart's `language` property and display text prompts in 235a corresponding language. For that the plugin needs to have the translations. 236 237Some of the plugin translations are in **lang** subdirectory. Simply include the 238one you need. 239 240If there is no translation to your language readily available, just grab en.js, 241copy it and translate. 242 243The structure is simple: 244 245``` 246'The phrase in English': 'Translation' 247``` 248 249The phrase in English must be left intact. 250 251When you're done, you can include your language as a JavaScript file. 252 253P.S. send us your translation so we can include it for the benefits of other 254users. Thanks! 255 256 257## Requirements 258 259This plugin requires at least 3.13 version of JavaScript Charts, JavaScript 260Stock Chart or JavaScript Maps. 261 262 263## Demos 264 265They're all in subdirectory /examples. 266 267 268## Extending this plugin 269 270You're encouraged to modify, extend and make derivative plugins out of this 271plugin. 272 273You can modify files, included in this archive or, better yet, fork this project 274on GitHub: 275 276https://github.com/amcharts/dataloader 277 278We're curious types. Please let us know (contact@amcharts.com) if you do create 279something new out of this plugin. 280 281 282## License 283 284This plugin is licensed under Apache License 2.0. 285 286This basically means you're free to use or modify this plugin, even make your 287own versions or completely different products out of it. 288 289Please see attached file "license.txt" for the complete license or online here: 290 291http://www.apache.org/licenses/LICENSE-2.0 292 293 294## Contact us 295 296* Email:contact@amcharts.com 297* Web: http://www.amcharts.com/ 298* Facebook: https://www.facebook.com/amcharts 299* Twitter: https://twitter.com/amcharts 300 301 302## Changelog 303 304### 1.0.15 305* Added "emptyAs" config property. Empty CSV values will be set to this (default `undefined`) 306 307### 1.0.14 308* Added "init" event handler, which is called **before** loading starts 309 310### 1.0.13 311* Added "progress" handler, which can be used to monitor data load progress 312 313### 1.0.12 314* Better default options handling in external calls to AmCharts.loadFile 315* Fixed the latest version of Stock Chart not resetting to default pre-defined period 316* New example: Using Data Loader functions externally (map_json_external_function.html) 317 318### 1.0.11 319* New translation: Added French translation. Thanks Remy! 320* Tweaks to allow better animation after data load on Pie chart 321 322### 1.0.10 323* Fixed error related to headers not being set when using standalone data load functions 324 325### 1.0.9 326* Plugin will now ignore empty CSV lines by default (configurable with `skipEmpty` property) 327 328### 1.0.8 329* Added `headers` config variable which allows adding custom headers to HTTP requests 330 331### 1.0.7 332* Fixed an issue with the Pie chart when it is being loaded in inactive tab 333 334### 1.0.6 335* Added support for Gauge chart (loads `arrows` array) 336 337### 1.0.5 338* Fixed JS error if periodSelector was not defined in chart config 339* Now all callback functions (complete, error, load) receive additional parameter: chart 340* postProcess function will now have "this" context set to Data Loader object as well as receive chart reference as third paramater 341 342### 1.0.4 343* Added `chart.dataLoader.loadData()` function which can be used to manually trigger all data reload 344 345### 1.0.3 346* Fixed the bug where defaults were not being applied properly 347* Fixed the bug with translations not being applied properly 348* Cleaned up the code (to pass JSHint validation) 349 350### 1.0.2 351* Fixed the issue with modified Array prototypes 352 353### 1.0.1 354* 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 355* Fixed language container initialization bug 356* Fixed bug that was causing parse errors not be displayed 357 358### 1.0 359* Added GANTT chart support 360 361### 0.9.2 362* Added global data load methods that can be used to load and parse data by code outside plugin 363* Trim CSV column names 364* Translation added: Lithuanian 365 366### 0.9.1 367* Fix chart animations not playing after asynchronous load 368 369### 0.9 370* Initial release