Documentation

DataSource

Type class

Represents a single data source - external file with all of its settings, such as format, data parsing, etc.

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

{
  // ...
  "dataSource": {
    "url": "http://www.myweb.com/data.json",
    "parser": "JSONParser"
  },
  // ...
}

IDataSourceEvents for a list of available events
IDataSourceAdapters for a list of available Adapters

Sources

DataSource can be used (imported) via one of the following packages.

/**
 * --------------------------------------------------------
 * Import from: "core.ts"
 * Use like: am4core.DataSource
 * --------------------------------------------------------
 */
import * as am4core from "@amcharts/amcharts4/core";


/**
 * --------------------------------------------------------
 * Include via: <script src="core.js"></script>
 * Access items like: am4.DataSource
 * --------------------------------------------------------
 */

Inheritance

DataSource extends BaseObjectEvents.

DataSource is not extended by any other symbol.

Properties

adapter
#

Type Adapter < DataSource, IDataSourceAdapters >

Default new Adapter<DataSource,
IDataSourceAdapters>(this)

Adapter.
clonedFrom
#

Type $type.Optional < this >

Inherited from BaseObject

Reference to the original object this object was cloned from. We need to keep this so we can disassociate it from source object when this object is disposed.
component
#

Type Component

A Component recipient of the data.
config
#

Type object

Inherited from BaseObject

Use this property to set JSON-based config. When set, triggers processing routine, which will go through all properties, and try to apply values, create instances, etc.

Use this with caution, as it is a time-consuming process. It's used for initialchart setup only, not routine operations.
data
#

Type any

Loaded and parsed data.
dateFormatter
#

Type DateFormatter

A DateFormatter to use when parsing dates from string formats.

Will inherit and use chart's DateFormatter if not ser.
disableCache
#

Type boolean

If set to true it will timestamp all requested URLs to work around browser cache.
events
#

Type EventDispatcher < AMEvent < this, IDataSourceEvents > >

Inherited from BaseObjectEvents

An EventDispatcher instance
id
#

Type $type.Optional < string >

Inherited from BaseObject

Sets the user-defined id of the element.
incremental
#

Type boolean

Default false

Should subsequent reloads be treated as incremental?

Incremental loads will assume that they contain only new data items since the last load.

If incremental = false the loader will replace all of the target's data with each load.

This setting does not have any effect trhe first time data is loaded.

NOTE: this setting works only with element's data property. It won't work with any other externally-loadable data property.
incrementalParams
#

Type object

An object consisting of key/value pairs to apply to an URL when data source is making an incremental request.
keepCount
#

Type boolean

Default false

This setting is used only when incremental = true. If set to true, it will try to retain the same number of data items across each load.

E.g. if incremental load yeilded 5 new records, then 5 items from the beginning of data will be removed so that we end up with the same number of data items.
language
#

Type Language

Language instance to use.

Will inherit and use chart's language, if not set.
lastLoad
#

Type Date

Holds the date of the last load.
parser
#

Type DataParser

Default JSONParser

A parser to be used to parse data.

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

{
  // ...
  "dataSource": {
    "url": "http://www.myweb.com/data.json",
    "parser": {
      "type": "JSONParser"
    }
  },
  // ...
}

reloadFrequency
#

Type number

Data source reload frequency.

If set, it will reload the same URL every X milliseconds.
requestOptions
#

Type INetRequestOptions

Custom options for HTTP(S) request.

At this moment the only option supported is: requestHeaders, which holds an array of objects for custom request headers, e.g.:

chart.dataSource.requestOptions.requestHeaders = [{
  "key": "x-access-token",
  "value": "123456789"
}];

chart.dataSource.requestOptions.requestHeaders = [{
  "key": "x-access-token",
  "value": "123456789"
}];

{
  // ...
  "dataSource": {
    // ...
    "requestOptions": {
      "requestHeaders": [{
        "key": "x-access-token",
        "value": "123456789"
      }]
    }
  }
}

NOTE: setting this options on an-already loaded DataSource will not trigger a reload.
showPreloader
#

Type boolean

Default true

Will show loading indicator when loading files.
uid
#

Type string

Inherited from BaseObject

Returns object's internal unique ID.
updateCurrentData
#

Type boolean

Default false

If set to true, each subsequent load will be treated as an update to currently loaded data, meaning that it will try to update values on existing data items, not overwrite the whole data.

This will work faster than complete update, and also will animate the values to their new positions.

Data sources across loads must contain the same number of data items.

Loader will not truncate the data set if loaded data has fewer data items, and if it is longer, the excess data items will be ignored.

NOTE: this setting is ignored if incremental = true.

@since 2.5.5

url
#

Type string

URL of the data source.
There are 5 inherited items currently hidden from this list.

Methods

addUrlParams(

url: string,
params: object

)

#

Returns string

Adds parameters to url as query strings. Will take care of proper separators.

clone(

cloneId?: string

)

#

Returns this

Inherited from BaseObject

Makes a copy of this object and returns the clone. Try to avoid cloning complex objects like chart, create new instances if you need them.

constructor(

url?: string,
parser?: string | DataParser

)

#

Returns DataSource

Constructor

copyFrom(

source: this

)

#

Returns void

Inherited from BaseObjectEvents

Copies all parameters from another Sprite.

dispatch(

eventType: Key,
data?: any

)

#

Returns void

Inherited from BaseObjectEvents

Dispatches an event using own event dispatcher. Will automatically populate event data object with event type and target (this element).

It also checks if there are any handlers registered for this sepecific event.

dispatchImmediately(

eventType: Key,
data?: any

)

#

Returns void

Inherited from BaseObjectEvents

Works like dispatch, except event is triggered immediately, without waiting for the next frame cycle.

dispose()

#

Returns void

Disposes of this object.

getCurrentThemes()

#

Returns ITheme[]

Inherited from BaseObject

Returns a list of themes that should be applied to this element. It could either be a list of themes set explicitly on this element, or system-wide.

isDisposed()

#

Returns boolean

Inherited from BaseObject

Returns if this object has been already been disposed.

load()

#

Returns void

Initiate the load.

All loading in JavaScript is asynchronous. This function will trigger the load and will exit immediately.

Use DataSource's events to watch for loaded data and errors.

timestampUrl(

url: string

)

#

Returns string

Adds current timestamp to the URL.
There are 6 inherited items currently hidden from this list.

Events

#done

Param { data: any,
  type: "done",
  target: this }

Invoked when data source was successfully loaded and parsed.
#ended

Param { type: "ended",
  target: this }

Invoked when loading and parsing finishes.
#error

Param { code: number,
  message: string,
  type: "error",
  target: this }

Invoked when data source encounters a loading error.
#loadended

Param { type: "loadended",
  target: this }

Invoked when the loading of the data finishes.
#loadstarted

Param { type: "loadstarted",
  target: this }

Invoked when loading of the data starts.
#parseended

Param { type: "parseended",
  target: this }

Invoked when parsing of the loaded data finishes.
#parseerror

Param { message: string,
  type: "parseerror",
  target: this }

Invoked when data source encounters a parsing error.
#parsestarted

Param { type: "parsestarted",
  target: this }

Invoked when parsing of the loaded data starts.
#started

Param { type: "started",
  target: this }

Invoked when loading of the data starts.

Adapters

#dateFields

Param string[]

Applied to the array that lists fields in data that hold date-based values.
#incremental

Param boolean

Applied to incremental setting.
#incrementalParams

Param object

Applied to incrementalParams setting.
#keepCount

Param boolean

Applied to keepCount setting.
#numberFields

Param string[]

Applied to the array that lists fields in data that hold numeric values.
#parsedData

Param any

Applied to the loaded data after it was parsed by a parser.
#parser

Param DataParser

Applied to a parser type, before parsing starts.

Can be used to supply different parser than the one set/determined by Data Loader.
#parserOptions

Param any

Applied to parser options.
#reloadTimeout

Param number

Applied to the timeout setting.
#requestOptions

Param INetRequestOptions

Applied to the custom request options object.
#unparsedData

Param string

Applied to the loaded data before it is passed to parser.
#updateCurrentData

Param boolean

Applied to updateCurrentData setting.
#url

Param string

Applied to a data source URL before it is loaded.