dojox/charting/DataChart (version 1.10)

dojox/charting/Chart2D

Summary

Extension to the 2D chart that connects to a data store in a simple manner. Convenience methods have been added for connecting store item labels to the chart labels.

This code should be considered very experimental and the APIs subject to change. This is currently an alpha version and will need some testing and review.

The main reason for this extension is to create animated charts, generally available with scroll=true, and a property field that gets continually updated. The previous property settings are kept in memory and displayed until scrolled off the chart.

Although great effort was made to maintain the integrity of the current charting APIs, some things have been added or modified in order to get the store to connect and also to get the data to scroll/animate. "displayRange" in particular is used to force the xaxis to a specific size and keep the chart from stretching or squashing to fit the data.

Currently, plot lines can only be set at initialization. Setting a new store query will have no effect (although using setStore may work but its untested).

Usage

var foo = new DataChart(node,kwArgs);
dojox/charting/DataChart
Parameter Type Description
node DomNode

The node to attach the chart to.
kwArgs Object
  • xaxis: Object: optional parameters for xaxis (see above)
  • yaxis: Object: optional parameters for yaxis (see above)
  • store: Object: dojo.data store (currently nly supports Persevere)
  • xaxis: Object: First query for store
  • grid: Object: Options for the grid plot
  • chartPlot: Object: Options for chart elements (lines, bars, etc)

See the dojox/charting/DataChart reference documentation for more information.

Examples

Example 1

var chart = new dojox.charting.DataChart("myNode", {
    displayRange:8,
    store:dataStore,
    query:{symbol:"*"},
    fieldName:"price"
    type: dojox.charting.plot2d.Columns
});

Property Summary

  • chartThemeThe theme to style the chart.
  • comparativeIf false, all items are each their own series.
  • displayRangeThe number of major ticks to show on the xaxis
  • fieldNameThe field in the store item that is getting charted
  • labelThe name field of the store item DO NOT SET: Set from store.labelAttribute
  • minHeightThe the smallest the chart height can be
  • minWidthThe the smallest the chart width can be
  • queryUsed for fetching items.
  • queryOptionsOption used for fetching items
  • scrollWhether live data updates and changes display, like columns moving up and down, or whether it scrolls to the left as data is added
  • showingWhether the chart is showing (default) on initialization or hidden.
  • stretchToFitIf true, chart is sized to data.

Method Summary

  • _invalidateDependentPlots(plotName,verticalAxis)
  • _makeClean()
  • _makeDirty()
  • _renderChartBackground(dim,offsets)
  • _renderPlotBackground(dim,offsets,w,h)
  • _resetLeftBottom(axis)
  • addAxis(name,kwArgs) Add an axis to the chart, for rendering.
  • addPlot(name,kwArgs) Add a new plot to the chart, defined by name and using the optional keyword arguments object.
  • addSeries(name,data,kwArgs) Add a data series to the chart for rendering.
  • calculateGeometry() Calculate the geometry of the chart based on the defined axes of a chart.
  • connectToPlot(name,object,method) A convenience method to connect a function to a plot.
  • convertLabels(axis) Convenience method to convert a label array of strings into an array of objects
  • delayedRender() Delayed render, which is used to collect multiple updates within a delayInMs time window.
  • destroy()
  • fetch() Fetches initial data.
  • fireEvent(seriesName,eventName,index) Fires a synthetic event for a series item.
  • formatTruncatedLabel(element,label,labelType)
  • fullGeometry() Calculate the full geometry of the chart.
  • fullRender() Force a full rendering of the chart, including full resets on the chart itself.
  • getAxis(name) Get the given axis, by name.
  • getCoords() Get the coordinates and dimensions of the containing DOMNode, as returned by dojo.coords.
  • getGeometry() Returns a map of information about all axes in a chart and what they represent in terms of scaling (see dojox.charting.axis2d.Default.getScaler).
  • getPlot(name) Get the given plot, by name.
  • getPlotOrder() Returns an array of plot names in the current order (the top-most plot is the first).
  • getProperty(item,prop) The main use of this function is to determine between a single value and an array of values.
  • getSeries(name) Get the given series, by name.
  • getSeriesOrder(plotName) Returns an array of series names in the current order (the top-most series is the first) within a plot.
  • hide() If chart is showing, hide it Prevents rendering while hidden
  • movePlotToBack(name) Moves a given plot to back.
  • movePlotToFront(name) Moves a given plot to front.
  • moveSeriesToBack(name) Moves a given series to back of a plot.
  • moveSeriesToFront(name) Moves a given series to front of a plot.
  • removeAxis(name) Remove the axis that was defined using name.
  • removePlot(name) Remove the plot defined using name from the chart's plot stack.
  • removeSeries(name) Remove the series defined by name from the chart.
  • render() Render the chart according to the current information defined.
  • resize(width,height) Resize the chart to the dimensions of width and height.
  • resizeChart(dim) Call this function to change the chart size.
  • seriesLabels(val) Convenience method that sets series labels based on item labels.
  • setAxisWindow(name,scale,offset,zoom) Zooms an axis and all dependent plots.
  • setDir(dir)
  • setPlotOrder(newOrder) Sets new order of plots. newOrder cannot add or remove plots.
  • setSeriesOrder(newOrder) Sets new order of series within a plot. newOrder cannot add or remove series.
  • setStore(store,query,fieldName,queryOptions) Sets the chart store and query then does the first fetch and connects to subsequent changes.
  • setTheme(theme) Set a theme of the chart.
  • setWindow(sx,sy,dx,dy,zoom) Zooms in or out any plots in two dimensions.
  • show() If chart is hidden, show it
  • updateSeries(name,data,offsets) Update the given series with a new set of data points.
  • zoomIn(name,range,delayed) Zoom the chart to a specific range on one axis.

Event Summary

  • onData(items) Called after a completed fetch or when store items change.
  • onDataReceived(items) stub.
  • onError(err)
  • onSet(item) Fired when a store item changes.

Properties

chartTheme
Defined by: dojox/charting/DataChart

The theme to style the chart. Defaults to PlotKit.blue.

comparative
Defined by: dojox/charting/DataChart

If false, all items are each their own series. If true, the items are combined into one series so that their charted properties can be compared.

displayRange
Defined by: dojox/charting/DataChart

The number of major ticks to show on the xaxis

fieldName
Defined by: dojox/charting/DataChart

The field in the store item that is getting charted

label
Defined by: dojox/charting/DataChart

The name field of the store item DO NOT SET: Set from store.labelAttribute

minHeight
Defined by: dojox/charting/DataChart

The the smallest the chart height can be

minWidth
Defined by: dojox/charting/DataChart

The the smallest the chart width can be

query
Defined by: dojox/charting/DataChart

Used for fetching items. Will vary depending upon store.

queryOptions
Defined by: dojox/charting/DataChart

Option used for fetching items

scroll
Defined by: dojox/charting/DataChart

Whether live data updates and changes display, like columns moving up and down, or whether it scrolls to the left as data is added

showing
Defined by: dojox/charting/DataChart

Whether the chart is showing (default) on initialization or hidden.

stretchToFit
Defined by: dojox/charting/DataChart

If true, chart is sized to data. If false, chart is a fixed size. Note, is overridden by displayRange. TODO: Stretch for the y-axis?

Methods

_invalidateDependentPlots(plotName,verticalAxis)
Defined by dojox/charting/Chart
Parameter Type Description
plotName undefined
verticalAxis Boolean
_makeClean()
Defined by dojox/charting/Chart
_makeDirty()
Defined by dojox/charting/Chart
_renderChartBackground(dim,offsets)
Defined by dojox/charting/Chart
Parameter Type Description
dim undefined
offsets undefined
_renderPlotBackground(dim,offsets,w,h)
Defined by dojox/charting/Chart
Parameter Type Description
dim undefined
offsets undefined
w undefined
h undefined
_resetLeftBottom(axis)
Defined by dojox/charting/Chart
Parameter Type Description
axis undefined
addAxis(name,kwArgs)
Defined by dojox/charting/Chart

Add an axis to the chart, for rendering.

Parameter Type Description
name String

The name of the axis.
kwArgs Object
Optional

An optional keyword arguments object for use in defining details of an axis.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

addPlot(name,kwArgs)
Defined by dojox/charting/Chart

Add a new plot to the chart, defined by name and using the optional keyword arguments object. Note that dojox.charting assumes the main plot to be called "default"; if you do not have a plot called "default" and attempt to add data series to the chart without specifying the plot to be rendered on, you WILL get errors.

Parameter Type Description
name String

The name of the plot to be added to the chart. If you only plan on using one plot, call it "default".
kwArgs dojox.charting.plot2d.__PlotCtorArgs

An object with optional parameters for the plot in question.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

addSeries(name,data,kwArgs)
Defined by dojox/charting/Chart

Add a data series to the chart for rendering.

Parameter Type Description
name String

The name of the data series to be plotted.
data Array | Object

The array of data points (either numbers or objects) that represents the data to be drawn. Or it can be an object. In the latter case, it should have a property "data" (an array), destroy(), and setSeriesObject().
kwArgs Object
Optional

An optional keyword arguments object that will be mixed into the resultant series object.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

calculateGeometry()
Defined by dojox/charting/Chart

Calculate the geometry of the chart based on the defined axes of a chart.

Returns:dojox/charting/Chart | undefined | function

A reference to the current chart for functional chaining.

connectToPlot(name,object,method)
Defined by dojox/charting/Chart

A convenience method to connect a function to a plot.

Parameter Type Description
name String

The name of the plot as defined by addPlot.
object Object

The object to be connected.
method Function

The function to be executed.
Returns:Array | null

A handle to the connection, as defined by dojo.connect (see dojo.connect).

convertLabels(axis)
Defined by dojox/charting/DataChart

Convenience method to convert a label array of strings into an array of objects

Parameter Type Description
axis undefined
Returns:null
delayedRender()
Defined by dojox/charting/Chart

Delayed render, which is used to collect multiple updates within a delayInMs time window.

Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

destroy()
Defined by dojox/charting/DataChart
fetch()
Defined by dojox/charting/DataChart

Fetches initial data. Subsequent changes are received via onSet in data store.

fireEvent(seriesName,eventName,index)
Defined by dojox/charting/Chart

Fires a synthetic event for a series item.

Parameter Type Description
seriesName String

Series name.
eventName String

Event name to simulate: onmouseover, onmouseout, onclick.
index Number

Valid data value index for the event.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

formatTruncatedLabel(element,label,labelType)
Defined by dojox/charting/Chart
Parameter Type Description
element undefined
label undefined
labelType undefined
fullGeometry()
Defined by dojox/charting/Chart

Calculate the full geometry of the chart. This includes passing over all major elements of a chart (plots, axes, series, container) in order to ensure proper rendering.

Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

fullRender()
Defined by dojox/charting/Chart

Force a full rendering of the chart, including full resets on the chart itself. You should not call this method directly unless absolutely necessary.

Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

getAxis(name)
Defined by dojox/charting/Chart

Get the given axis, by name.

Parameter Type Description
name String

The name the axis was defined by.
Returns:dojox/charting/axis2d/Default | undefined

The axis as stored in the chart's axis map.

getCoords()
Defined by dojox/charting/Chart

Get the coordinates and dimensions of the containing DOMNode, as returned by dojo.coords.

Returns:Object | undefined

The resulting coordinates of the chart. See dojo.coords for details.

getGeometry()
Defined by dojox/charting/Chart

Returns a map of information about all axes in a chart and what they represent in terms of scaling (see dojox.charting.axis2d.Default.getScaler).

Returns:Object | object

An map of geometry objects, a one-to-one mapping of axes.

getPlot(name)
Defined by dojox/charting/Chart

Get the given plot, by name.

Parameter Type Description
name String

The name the plot was defined by.
Returns:dojox/charting/plot2d/Base | undefined

The plot.

getPlotOrder()
Defined by dojox/charting/Chart

Returns an array of plot names in the current order (the top-most plot is the first).

Returns:Array | undefined
getProperty(item,prop)
Defined by dojox/charting/DataChart

The main use of this function is to determine between a single value and an array of values. Other property types included for convenience.

Parameter Type Description
item storeObject
prop undefined
Returns:undefined
getSeries(name)
Defined by dojox/charting/Chart

Get the given series, by name.

Parameter Type Description
name String

The name the series was defined by.
Returns:dojox/charting/Series | undefined

The series.

getSeriesOrder(plotName)
Defined by dojox/charting/Chart

Returns an array of series names in the current order (the top-most series is the first) within a plot.

Parameter Type Description
plotName String

Plot's name.
Returns:Array | undefined
hide()
Defined by dojox/charting/DataChart

If chart is showing, hide it Prevents rendering while hidden

movePlotToBack(name)
Defined by dojox/charting/Chart

Moves a given plot to back.

Parameter Type Description
name String

Plot's name to move.
Returns:dojox/charting/Chart | undefined | function

A reference to the current chart for functional chaining.

movePlotToFront(name)
Defined by dojox/charting/Chart

Moves a given plot to front.

Parameter Type Description
name String

Plot's name to move.
Returns:dojox/charting/Chart | undefined | function

A reference to the current chart for functional chaining.

moveSeriesToBack(name)
Defined by dojox/charting/Chart

Moves a given series to back of a plot.

Parameter Type Description
name String

Series' name to move.
Returns:dojox/charting/Chart | undefined | function

A reference to the current chart for functional chaining.

moveSeriesToFront(name)
Defined by dojox/charting/Chart

Moves a given series to front of a plot.

Parameter Type Description
name String

Series' name to move.
Returns:dojox/charting/Chart | undefined | function

A reference to the current chart for functional chaining.

removeAxis(name)
Defined by dojox/charting/Chart

Remove the axis that was defined using name.

Parameter Type Description
name String

The axis name, as defined in addAxis.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

removePlot(name)
Defined by dojox/charting/Chart

Remove the plot defined using name from the chart's plot stack.

Parameter Type Description
name String

The name of the plot as defined using addPlot.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

removeSeries(name)
Defined by dojox/charting/Chart

Remove the series defined by name from the chart.

Parameter Type Description
name String

The name of the series as defined by addSeries.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

render()
Defined by dojox/charting/Chart

Render the chart according to the current information defined. This should be the last call made when defining/creating a chart, or if data within the chart has been changed.

Returns:dojox/charting/Chart | undefined | function

A reference to the current chart for functional chaining.

resize(width,height)
Defined by dojox/charting/Chart

Resize the chart to the dimensions of width and height.

Resize the chart and its surface to the width and height dimensions. If a single argument of the form {w: value1, h: value2} is provided take that argument as the dimensions to use. Finally if no argument is provided, resize the surface to the marginBox of the chart.

Parameter Type Description
width Number | Object
Optional

The new width of the chart or the box definition.
height Number
Optional

The new height of the chart.
Returns:dojox/charting/Chart | undefined | function

A reference to the current chart for functional chaining.

resizeChart(dim)
Defined by dojox/charting/DataChart

Call this function to change the chart size. Can be connected to a layout widget that calls resize.

Parameter Type Description
dim Object
seriesLabels(val)
Defined by dojox/charting/DataChart

Convenience method that sets series labels based on item labels.

Parameter Type Description
val Number
Returns:string | undefined
setAxisWindow(name,scale,offset,zoom)
Defined by dojox/charting/Chart

Zooms an axis and all dependent plots. Can be used to zoom in 1D.

Parameter Type Description
name String

The name of the axis as defined by addAxis.
scale Number

The scale on the target axis.
offset Number

Any offest, as measured by axis tick
zoom Boolean | Object
Optional

The chart zooming animation trigger. This is null by default, e.g. {duration: 1200}, or just set true.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

setDir(dir)
Defined by dojox/charting/Chart
Parameter Type Description
dir undefined
Returns:function
setPlotOrder(newOrder)
Defined by dojox/charting/Chart

Sets new order of plots. newOrder cannot add or remove plots. Wrong names, or dups are ignored.

Parameter Type Description
newOrder Array

Array of plot names compatible with getPlotOrder().
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

setSeriesOrder(newOrder)
Defined by dojox/charting/Chart

Sets new order of series within a plot. newOrder cannot add or remove series. Wrong names, or dups are ignored.

Parameter Type Description
newOrder Array

Array of series names compatible with getPlotOrder(). All series should belong to the same plot.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

setStore(store,query,fieldName,queryOptions)
Defined by dojox/charting/DataChart

Sets the chart store and query then does the first fetch and connects to subsequent changes.

Parameter Type Description
store Object
query ? String
fieldName ? String
queryOptions ? Object
setTheme(theme)
Defined by dojox/charting/Chart

Set a theme of the chart.

Parameter Type Description
theme dojox/charting/SimpleTheme

The theme to be used for visual rendering.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

setWindow(sx,sy,dx,dy,zoom)
Defined by dojox/charting/Chart

Zooms in or out any plots in two dimensions.

Parameter Type Description
sx Number

The scale for the x axis.
sy Number

The scale for the y axis.
dx Number

The pixel offset on the x axis.
dy Number

The pixel offset on the y axis.
zoom Boolean | Object
Optional

The chart zooming animation trigger. This is null by default, e.g. {duration: 1200}, or just set true.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

show()
Defined by dojox/charting/DataChart

If chart is hidden, show it

updateSeries(name,data,offsets)
Defined by dojox/charting/Chart

Update the given series with a new set of data points.

Parameter Type Description
name String

The name of the series as defined in addSeries.
data Array | Object

The array of data points (either numbers or objects) that represents the data to be drawn. Or it can be an object. In the latter case, it should have a property "data" (an array), destroy(), and setSeriesObject().
offsets Boolean
Optional

If true recomputes the offsets of the chart based on the new data. This is useful if the range of data is drastically changing and offsets need to be recomputed.
Returns:dojox/charting/Chart | function

A reference to the current chart for functional chaining.

zoomIn(name,range,delayed)
Defined by dojox/charting/Chart

Zoom the chart to a specific range on one axis. This calls render() directly as a convenience method.

Parameter Type Description
name String

The name of the axis as defined by addAxis.
range Array

The end points of the zoom range, measured in axis ticks.
delayed undefined

Events

onData(items)
Defined by: dojox/charting/DataChart

Called after a completed fetch or when store items change. On first run, sets the chart data, then updates chart and legends.

Parameter Type Description
items Array

Examples

Example 1

var chart = new dojox.charting.DataChart("myNode", {
    displayRange:8,
    store:dataStore,
    query:{symbol:"*"},
    fieldName:"price"
    type: dojox.charting.plot2d.Columns
});
onDataReceived(items)
Defined by: dojox/charting/DataChart

stub. Fires after data is received but before data is parsed and rendered

Parameter Type Description
items Array

Examples

Example 1

var chart = new dojox.charting.DataChart("myNode", {
    displayRange:8,
    store:dataStore,
    query:{symbol:"*"},
    fieldName:"price"
    type: dojox.charting.plot2d.Columns
});
onError(err)
Defined by: dojox/charting/DataChart
Parameter Type Description
err Error

Examples

Example 1

var chart = new dojox.charting.DataChart("myNode", {
    displayRange:8,
    store:dataStore,
    query:{symbol:"*"},
    fieldName:"price"
    type: dojox.charting.plot2d.Columns
});
onSet(item)
Defined by: dojox/charting/DataChart

Fired when a store item changes. Collects the item calls and when done (after 200ms), sends item array to onData().

Parameter Type Description
item storeObject

Examples

Example 1

var chart = new dojox.charting.DataChart("myNode", {
    displayRange:8,
    store:dataStore,
    query:{symbol:"*"},
    fieldName:"price"
    type: dojox.charting.plot2d.Columns
});
Error in the documentation? Can’t find what you are looking for? Let us know!