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