Class Garmin.DeviceDisplay

Garmin.DeviceDisplay requires Prototype
Defined in: GarminDeviceDisplay.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Garmin.DeviceDisplay(mainElement, options) Provides the easiest avenue for getting a working instance of the plug-in onto your page.

Field Summary
Field Attributes	Field Name and Description
<static>	Garmin.DeviceDisplay.LINKS Constant defining links referenced in the DeviceDisplay

Method Summary
Method Attributes	Method Name and Description
	cancelFindDevices() Entry point for cancelling search for connected devices.
	clearActivityQueue() Empties the activity queue if it has any entries.
	clearMapDisplay() Clears overlays from map.
	currentActivityStatusElement() Returns status element for current activity in queue
	defaultExceptionHandler(error) Default exception handler method handles plug-in support/downloads/upgrades.
	displayTrack() Draws a simple line on the map using the Garmin.MapController.
	displayWaypoint() Draws a point (usualy as a thumb tack) on the map using the Garmin.MapController.
	evaluateTemplate(String, Hash) Helper method.
	getController(Boolean) Sets up the device control which handles most of the work that isn't user interface related.
	getUploadProgressJson() Returns the current status of the upload progress based on the activity queue.
	handleException(error) Central exception dispatch method will delegate to options.customExceptionHandler if defined or call defaultExceptionHandler otherwise.
	hideProgressBar() Hides progress bar.
	isUnlocked() Plugin unlock status
	onActivitySelect(String, Array) Callback for enforcing upload selection limit.
	onCancelReadFromDevice(json) Call-back for device read cancelled.
	onFinishReadFromDevice(json) Call-back for device read.
	postToServer(callback) Post data to an external server.
	readFilteredActivities() Read the filtered activities.
	readFromDevice(readDataTypes) Initiation call for reading from a device.
	readSpecificTypeFromDevice(readDataType, fileListingOptions) Generic read method, supporting GPX, TCX, Courses, Workouts, User Profiles, TCX activity directory, and TCX course directory reads.
	resetUI() Resets UI widgets based on state of application.
	setOptions(Object) Sets options for this display object.
	setStatus(String) Set status text if showStatusElement is visible.
	showProgressBar() Makes progress bar visible.
	startFindDevices() Entry point for searching for connected devices.
	stopQueuedUploads() Stop uploading activities in the queue, and go on to finished screen.
	updateProgressBar(progressBarDisplay, int) Update percentage representation of progress bar.
	updateProgressBarText(progressBarText, String) Update the progress text of the progress bar.
	writeToDevice() Writes any supported data to the device.

Event Summary
Event Attributes	Event Name and Description
	onCancelFindDevices(json) Call-back for find device cancelled.
	onCancelWriteToDevice(json) Call-back triggered when write has been cancelled.
	onException(json) Call-back for asynchronous method exceptions.
	onFinishFindDevices(json) Call-back triggered after plugin has completed its search for devices.
	onFinishUploads(the) Callback when all uploads are finished.
	onFinishWriteToDevice(json)
	onProgressReadFromDevice(json) Call-back for device read progress.
	onProgressUpload(json) As uploads continue processing, this method will be called.
	onProgressWriteToDevice(json)
	onStartFindDevices(json) Call-back triggered before plugin searches for connected devices.
	onStartWriteToDevice(json) Call-back triggered before writing to a device.
	onWaitingWriteToDevice(json) Call-back when the device already has a file with this name on it.

Class Detail

Garmin.DeviceDisplay(mainElement, options)

Provides the easiest avenue for getting a working instance of the plug-in onto your page. Generates the UI elements and places them on the page.

Parameters:
{String|Element} mainElement: - id of the element (or DOM element itself) in which to generate the contents
{Object} options: - Object with options (see Garmin.DeviceDisplayDefaultOptions for descriptions of possible options).

Requires:: Garmin.DeviceControl

Field Detail

<static> Garmin.DeviceDisplay.LINKS

Constant defining links referenced in the DeviceDisplay

Method Detail

cancelFindDevices()

Entry point for cancelling search for connected devices.

See:: Garmin.DeviceDisplay#event:onCancelFindDevices

clearActivityQueue()

Empties the activity queue if it has any entries.

clearMapDisplay()

Clears overlays from map.

{Element} currentActivityStatusElement()

Returns status element for current activity in queue

Returns:: {Element}

defaultExceptionHandler(error)

Default exception handler method handles plug-in support/downloads/upgrades. If options.showStatusElement is true then put error messages in the status div otherwise put it in a alert popup.

Parameters:
{Error} error: - error to process.

displayTrack()

Draws a simple line on the map using the Garmin.MapController.

Parameters:
Garmin.Series: series - that contains a track.

displayWaypoint()

Draws a point (usualy as a thumb tack) on the map using the Garmin.MapController.

Parameters:
Garmin.Series: series - that contains the lat/lon position of the point.

evaluateTemplate(String, Hash)

Helper method. Evaluates Prototype's Template object, and returns the evaluated string. Templates should contain fields as in the following format: 'My cow has #{numSpots}' spots!' Fields are in the following format: {numSpots: 22}

Parameters:
String: template - the template to evaluate
Hash: fields - the fields referenced in template

Returns:: the evaluated template string

getController(Boolean)

Sets up the device control which handles most of the work that isn't user interface related. The controller is lazy loaded the first time it is called. Early calls must specify the unlock parameter, but read and write methods should not because they should follow a call to findDevice. Also initializes the RemoteTransfer object used to transfer data to remote servers.

Parameters:
Boolean: optional request to unlock the plugin if not already done.

{JSON, , String, String, String, String, Garmin.DeviceDisplay} getUploadProgressJson()

Returns the current status of the upload progress based on the activity queue. If there is no upload in progress, all values will be 0.

Returns:: {JSON} json object with report values and current DeviceDisplay instance; json.progress; {String} json.progress.current the current upload index from the activity queue; {String} json.progress.total whole number of uploads finished; {String} json.progress.percentage percentage value of uploads finished; {String} json.progress.text upload progress text to display to user; {Garmin.DeviceDisplay} json.display the current DeviceDisplay instance for UI purposes

handleException(error)

Central exception dispatch method will delegate to options.customExceptionHandler if defined or call defaultExceptionHandler otherwise.

Parameters:
{Error} error: to process.

hideProgressBar()

Hides progress bar.

isUnlocked()

Plugin unlock status

Returns:: Boolean

onActivitySelect(String, Array)

Callback for enforcing upload selection limit. Called each time the user modifies selection.

Parameters:
String: elementId - the ID of the input element selected to trigger this callback
Array: activityDirectory - array of all activity IDs listed in the activity directory

See:: Garmin.DeviceDisplayDefaultOptions.uploadMaximum

onCancelReadFromDevice(json)

Call-back for device read cancelled.

Parameters:
{JSON} json: the progress report in JSON format

See:: Garmin.DeviceControl

onFinishReadFromDevice(json)

Call-back for device read.

Parameters:
{JSON} json: the progress report in JSON format

See:: Garmin.DeviceControl

postToServer(callback)

Post data to an external server. Request options should be provided by the parameters element in Garmin.DeviceDisplayDefaultOptions.sendDataOptions

Parameters:
{function} callback: function executed after onSuccess of the AJAX request. If failure, exception is thrown Garmin.DeviceDisplay#handleException

See:: Garmin.DeviceDisplayDefaultOptions.sendDataOptions; Garmin.DeviceDisplay#handleException

readFilteredActivities()

Read the filtered activities. Filtered activities are those picked by the API as well as any user-selected activities, if applicable. Activities may be uploaded after being read. Filtered activities are detected before the activities themselves are read, and data filters filter the data after the activities are read.

See:: Garmin.DeviceDisplay#event:onFinishUploads

readFromDevice(readDataTypes)

Initiation call for reading from a device. If a fitness device is detected reads TCX otherwise reads GPX. Upon completion if the afterFinishReadFromDevice method is defined it will be called. At this time you may also obtain location data using the getTracks and getWaypoints methods.

Parameters:
{Array} readDataTypes: list of read data types

See:: Garmin.DeviceControl.FILE_TYPES

readSpecificTypeFromDevice(readDataType, fileListingOptions)

Generic read method, supporting GPX, TCX, Courses, Workouts, User Profiles, TCX activity directory, and TCX course directory reads.

Upon completion if the afterFinishReadFromDevice method is defined it will be called. At this time you may also obtain location data using the getTracks and getWaypoints methods.

Fitness detail reading (one specific activity) is not supported by this read method, refer to readDetailFromDevice for that.

Parameters:
{String} readDataType: - type of data to read.
{Object} fileListingOptions: - additional read options

See:: Garmin.DeviceControl.FILE_TYPES; Garmin.DeviceDisplayDefaultOptions.afterFinishReadFromDevice; Garmin.DeviceDisplayDefaultOptions.fileListingOptions

resetUI()

Resets UI widgets based on state of application.

setOptions(Object)

Sets options for this display object. Any options that are set will override the default values.

Parameters:
Object: options - Object with options.

Throws:
: InvalidOptionException

See:: Garmin.DeviceDisplayDefaultOptions for possible options and default values.

setStatus(String)

Set status text if showStatusElement is visible.

Parameters:
String: text to display.

showProgressBar()

Makes progress bar visible.

startFindDevices()

Entry point for searching for connected devices. Will attempt to unlock the plugin if necessary.

See:: Garmin.DeviceDisplay#cancelFindDevices; Garmin.DeviceDisplay#event:onStartFindDevices

stopQueuedUploads()

Stop uploading activities in the queue, and go on to finished screen. Useful for certain error cases.

See:: Garmin.DeviceDisplay#event:onFinishUploads

updateProgressBar(progressBarDisplay, int)

Update percentage representation of progress bar. The progress bar starts out as full and then resets to empty. This is to take care of extremely short transfers.

Parameters:
{Element} progressBarDisplay: - the progress bar display DOM element to update.
int: percentage completion: 0-100

updateProgressBarText(progressBarText, String)

Update the progress text of the progress bar.

Parameters:
{Element} progressBarText: - the progress bar text DOM element to update.
String: the progress text to display near the progress bar

writeToDevice()

Writes any supported data to the device. Requires that the option writeDataType field be set correctly to any of the following values located in Garmin.DeviceControl.FILE_TYPES: gpx, crs, binary, goals

Throws:
: InvalidTypeException

See:: Garmin.DeviceDisplayDefaultOptions.writeDataType; Garmin.DeviceControl.FILE_TYPES

Event Detail

onCancelFindDevices(json)

Call-back for find device cancelled.

Parameters:
{JSON} json

See:: Garmin.DeviceControl; Garmin.DeviceDisplay#cancelFindDevices

onCancelWriteToDevice(json)

Call-back triggered when write has been cancelled.

Parameters:
json

See:: Garmin.DeviceControl

onException(json)

Call-back for asynchronous method exceptions.

Parameters:
json

See:: Garmin.DeviceControl

onFinishFindDevices(json)

Call-back triggered after plugin has completed its search for devices.

Parameters:
{JSON} json

See:: Garmin.DeviceControl; Garmin.DeviceDisplay#startFindDevices

onFinishUploads(the)

Callback when all uploads are finished. The display is passed in as the single param.

Parameters:
{Garmin.DeviceDisplay} the: current DeviceDisplay instance

See:: Garmin.DeviceDisplayDefaultOptions.afterFinishUploads

onFinishWriteToDevice(json)

Parameters:
json

onProgressReadFromDevice(json)

Call-back for device read progress.

Parameters:
{JSON} json: the progress report in JSON format

See:: Garmin.DeviceDisplay#onFinishReadFromDevice

onProgressUpload(json)

As uploads continue processing, this method will be called. This is called once per upload item. This does not track byte-progress of a single upload.

Parameters:
{JSON} json: the progress report in JSON format

See:: Garmin.DeviceDisplay#event:onFinishUploads

onProgressWriteToDevice(json)

Parameters:
json

onStartFindDevices(json)

Call-back triggered before plugin searches for connected devices.

Parameters:
{JSON} json

See:: Garmin.DeviceControl; Garmin.DeviceDisplay#startFindDevices

onStartWriteToDevice(json)

Call-back triggered before writing to a device.

Parameters:
json

See:: Garmin.DeviceControl

onWaitingWriteToDevice(json)

Call-back when the device already has a file with this name on it. Do we want to override? 1 is yes, 2 is no

Parameters:
json

See:: Garmin.DeviceControl

Communicator Plugin API Version 1.9

Classes

Class Garmin.DeviceDisplay