Maps API for JavaScript Developer's Guide

H.data.kml.Reader

Class Summary

This class is responsible for fetching and interpreting KML data. It creates an instance of H.map.Object that can be displayed on the map, from KML features and geometries as described by OGC.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods
`getLayer () : {H.map.layer.ObjectLayer}` This method retrieves an object layer (H.map.layer.ObjectLayer) that contains parsed data and can be added directly to the map. The method gets a new instance of `ObjectLayer` with every invocation. If the data has not been parsed, the method returns an `ObjectLayer` that contains partial information, and the reader adds any new parsed objects to the provider associated with the layer later on.
`getParsedObjects () : {Array<H.map.Object>}` This method retrieves a collection of objects representing parsed data converted to data objects. Note that the method returns only currently parsed objects if parsing is ongoing.
`getUrl () : {(string \| undefined)}` This method retrieves the URL of the current file, which is either a file being fetched/parsed or a file that has been already parsed.
`setUrl (url) : {H.data.AbstractReader}` This method sets the URL for the `Reader`. It resets the current state of the `Reader` to its initial values (clears data about last parsed objects, etc.), and throws `InvalidState` exception if the state of the `Reader` is not `READY` or `ERROR`.
`getState () : {H.data.AbstractReader.State}` This method retrieves the processing state of the `Reader`. For possible states see H.data.AbstractReader.State.
`parse ()` This method launches parsing of the data file at the current URL (see H.data.AbstractReader#setUrl or H.data.AbstractReader). The method uses XHR as a transport, therefore the same origin policy applies, or the server should respond with the appropriate CORS headers.

Events Summary

Table 2. Events
Events
`statechange : {H.data.AbstractReader.Event}` Event fired when the reader state changes, see H.data.AbstractReader#getState.

Class Description

This class is responsible for fetching and interpreting KML data. It creates an instance of H.map.Object that can be displayed on the map, from KML features and geometries as described by OGC.

Auxiliary data that accompanies geometries (such as name, description, the KML node itself, etc.) is bound to the map object and can be fetched by calling the method H.map.Object#getData on the map object.

Note that you can load a KML file even from a different domain if that domain supports Cross-Origin Resource Sharing (see http://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS).

Example

var reader = new H.data.kml.Reader('/path/to/kml/file.kml');
reader.parse();
// Assumption: map already exists
map.addLayer(reader.getLayer());

Constructor Details

H.data.kml.Reader(url)

Parameters:
url:: {string}
: A URL from which to get KML data

Method Details

getLayer () : {H.map.layer.ObjectLayer}

This method retrieves an object layer (H.map.layer.ObjectLayer) that contains parsed data and can be added directly to the map. The method gets a new instance of ObjectLayer with every invocation. If the data has not been parsed, the method returns an ObjectLayer that contains partial information, and the reader adds any new parsed objects to the provider associated with the layer later on.

Returns:
: {H.map.layer.ObjectLayer}

getParsedObjects () : {Array<H.map.Object>}

This method retrieves a collection of objects representing parsed data converted to data objects. Note that the method returns only currently parsed objects if parsing is ongoing.

Returns:
: {Array<H.map.Object>}
: An array of objects representing parsed data

getUrl () : {(string | undefined)}

This method retrieves the URL of the current file, which is either a file being fetched/parsed or a file that has been already parsed.

Returns:
: {(string | undefined)}
: url A string containing the URL or undefined

setUrl (url) : {H.data.AbstractReader}

This method sets the URL for the Reader. It resets the current state of the Reader to its initial values (clears data about last parsed objects, etc.), and throws InvalidState exception if the state of the Reader is not READY or ERROR.

Parameters:
url:: {string}
: The new URL

Returns:
: {H.data.AbstractReader}
: An object reflecting the Reader after modification

getState () : {H.data.AbstractReader.State}

This method retrieves the processing state of the Reader. For possible states see H.data.AbstractReader.State.

Returns:
: {H.data.AbstractReader.State}
: A value indicating the state of the Reader

parse ()

This method launches parsing of the data file at the current URL (see H.data.AbstractReader#setUrl or H.data.AbstractReader). The method uses XHR as a transport, therefore the same origin policy applies, or the server should respond with the appropriate CORS headers.

Event Details

statechange: {H.data.AbstractReader.Event}

Event fired when the reader state changes, see H.data.AbstractReader#getState.