dojo_app/js/library/dojox/widget/DataPresentation.js

dojo.provide("dojox.widget.DataPresentation");
dojo.experimental("dojox.widget.DataPresentation");

dojo.require("dojox.grid.DataGrid");
dojo.require("dojox.charting.Chart2D");
dojo.require("dojox.charting.widget.Legend");
dojo.require("dojox.charting.action2d.Tooltip");
dojo.require("dojox.charting.action2d.Highlight");
dojo.require("dojo.colors");
dojo.require("dojo.data.ItemFileWriteStore");

(function(){
	
	// sort out the labels for the independent axis of the chart
	var getLabels = function(range, labelMod, charttype, domNode){
		
		// prepare labels for the independent axis
		var labels = [];
		// add empty label, hack
		labels[0] = {value: 0, text: ''};

		var nlabels = range.length;

		// auto-set labelMod for horizontal charts if the labels will otherwise collide
		if((charttype !== "ClusteredBars") && (charttype !== "StackedBars")){
    		var cwid = domNode.offsetWidth;
    		var tmp = ("" + range[0]).length * range.length * 7; // *assume* 7 pixels width per character ( was 9 )
    	  
    		if(labelMod == 1){
    			for(var z = 1; z < 500; ++z){
    				if((tmp / z) < cwid){
    					break;
    				}
    				++labelMod;
    			}
    		}
	    }

		// now set the labels
		for(var i = 0; i < nlabels; i++){
			//sparse labels
			labels.push({
				value: i + 1,
				text: (!labelMod || i % labelMod) ? "" : range[i]
			});
		}
		
		// add empty label again, hack
		labels.push({value: nlabels + 1, text:''});
		
		return labels;
	};
	
	// get the configuration of an independent axis for the chart
	var getIndependentAxisArgs = function(charttype, labels){

		var args = { vertical: false, labels: labels, min: 0, max: labels.length-1, majorTickStep: 1, minorTickStep: 1 };
		
		// clustered or stacked bars have a vertical independent axis
		if((charttype === "ClusteredBars") || (charttype === "StackedBars")){
			args.vertical = true;
		}
		
		// lines, areas and stacked areas don't need the extra slots at each end
		if((charttype === "Lines") || (charttype === "Areas") || (charttype === "StackedAreas")){
			args.min++;
			args.max--;
		}

		return args;
	};

	// get the configuration of a dependent axis for the chart
	var getDependentAxisArgs = function(charttype, axistype, minval, maxval){
		
		var args = { vertical: true, fixLower: "major", fixUpper: "major", natural: true };
		
		// secondary dependent axis is not left-bottom
		if(axistype === "secondary"){
			args.leftBottom = false;
		}

		// clustered or stacked bars have horizontal dependent axes
		if((charttype === "ClusteredBars") || (charttype === "StackedBars")){
			args.vertical = false;
		}
		
		// ensure axis does not "collapse" for flat series
		if(minval == maxval){
			args.min = minval - 1;
			args.max = maxval + 1;
		}
		
		return args;
	};
	
	// get the configuration of a plot for the chart
	var getPlotArgs = function(charttype, axistype, animate){
		
		var args = { type: charttype, hAxis: "independent", vAxis: "dependent-" + axistype, gap: 4, lines: false, areas: false, markers: false };
		
		// clustered or stacked bars have horizontal dependent axes
		if((charttype === "ClusteredBars") || (charttype === "StackedBars")){
			args.hAxis = args.vAxis;
			args.vAxis = "independent";
		}

		// turn on lines for Lines, Areas and StackedAreas
		if((charttype === "Lines") || (charttype === "Hybrid-Lines") || (charttype === "Areas") || (charttype === "StackedAreas")){
			args.lines = true;
		}
		
		// turn on areas for Areas and StackedAreas
		if((charttype === "Areas") || (charttype === "StackedAreas")){
			args.areas = true;
		}
		
		// turn on markers and shadow for Lines
		if(charttype === "Lines"){
			args.markers = true;
		}
		
		// turn on shadow for Hybrid-Lines
		// also, Hybrid-Lines is not a true chart type: use Lines for the actual plot
		if(charttype === "Hybrid-Lines"){
			args.shadows = {dx: 2, dy: 2, dw: 2};
			args.type = "Lines";
		}
		
		// also, Hybrid-ClusteredColumns is not a true chart type: use ClusteredColumns for the actual plot
		if(charttype === "Hybrid-ClusteredColumns"){
			args.type = "ClusteredColumns";
		}
		
		// enable animation on the plot if animation is requested
		if(animate){
			args.animate = animate;
		}
		
		return args;
	};

	// set up a chart presentation
	var setupChart = function(/*DomNode*/domNode, /*Object?*/chart, /*String*/type, /*Boolean*/reverse, /*Object*/animate, /*Integer*/labelMod, /*String*/theme, /*String*/tooltip, /*Object?*/store, /*String?*/query, /*String?*/queryOptions){
		var _chart = chart;
		
		if(!_chart){
			domNode.innerHTML = "";  // any other content in the node disrupts the chart rendering
			_chart = new dojox.charting.Chart2D(domNode);
		}
		
		// set the theme
		if(theme){

			// workaround for a theme bug: its _clone method
			// does not transfer the markers, so we repair
			// that omission here
			// FIXME this should be removed once the theme bug is fixed
	        theme._clone = function(){
			      var result = new dojox.charting.Theme({
			        chart: this.chart,
			        plotarea: this.plotarea,
			        axis: this.axis,
			        series: this.series,
			        marker: this.marker,
			        antiAlias: this.antiAlias,
			        assignColors: this.assignColors,
			        assignMarkers: this.assigneMarkers,
			        colors: dojo.delegate(this.colors)
			      });
			      
			      result.markers = this.markers;
			      result._buildMarkerArray();
			      
			      return result;
	        };
			
			_chart.setTheme(theme);
		}

		var range = store.series_data[0].slice(0);
		
		// reverse the labels if requested
		if(reverse){
			range.reverse();
		}
			
		var labels = getLabels(range, labelMod, type, domNode);

		// collect details of whether primary and/or secondary axes are required
		// and what plots we have instantiated using each type of axis
		var plots = {};
		
		// collect maximum and minimum data values
		var maxval = null;
		var minval = null;
		
		var seriestoremove = {};
		for(var sname in _chart.runs){
			seriestoremove[sname] = true;
		}

		// set x values & max data value
		var nseries = store.series_name.length;
		for(var i = 0; i < nseries; i++){
			// only include series with chart=true and with some data values in
			if(store.series_chart[i] && (store.series_data[i].length > 0)){

				var charttype = type;
				var axistype = store.series_axis[i];

				if(charttype == "Hybrid"){
					if(store.series_charttype[i] == 'line'){
						charttype = "Hybrid-Lines";
					}else{
						charttype = "Hybrid-ClusteredColumns";
					}
				}
				
				// ensure we have recorded that we are using this axis type
				if(!plots[axistype]){
					plots[axistype] = {};
				}
				
				// ensure we have the correct type of plot for this series
				if(!plots[axistype][charttype]){
					var axisname = axistype + "-" + charttype;
					
					// create the plot and enable tooltips
					_chart.addPlot(axisname, getPlotArgs(charttype, axistype, animate));

					var tooltipArgs = {};
					if(typeof tooltip == 'string'){
						tooltipArgs.text = function(o){
							var substitutions = [o.element, o.run.name, range[o.index], ((charttype === "ClusteredBars") || (charttype === "StackedBars")) ? o.x : o.y];
							return dojo.replace(tooltip, substitutions);  // from Dojo 1.4 onward
							//return tooltip.replace(/\{([^\}]+)\}/g, function(_, token){ return dojo.getObject(token, false, substitutions); });  // prior to Dojo 1.4
						}
					}else if(typeof tooltip == 'function'){
						tooltipArgs.text = tooltip;
					}
					new dojox.charting.action2d.Tooltip(_chart, axisname, tooltipArgs);
					
					// add highlighting, except for lines
					if(charttype !== "Lines" && charttype !== "Hybrid-Lines"){
						new dojox.charting.action2d.Highlight(_chart, axisname);
					}
					
					// record that this plot type is now created
					plots[axistype][charttype] = true;
				}
				
				// extract the series values
				var xvals = [];
				var valen = store.series_data[i].length;
				for(var j = 0; j < valen; j++){
					var val = store.series_data[i][j];
					xvals.push(val);
					if(maxval === null || val > maxval){
						maxval = val;
					}
					if(minval === null || val < minval){
						minval = val;
					}
				}
					
				// reverse the values if requested
				if(reverse){
					xvals.reverse();
				}

				var seriesargs = { plot: axistype + "-" + charttype };
				if(store.series_linestyle[i]){
					seriesargs.stroke = { style: store.series_linestyle[i] };
				}

				_chart.addSeries(store.series_name[i], xvals, seriesargs);
				delete seriestoremove[store.series_name[i]];
			}
		}
		
		// remove any series that are no longer needed
		for(sname in seriestoremove){
			_chart.removeSeries(sname);
		}

		// create axes
		_chart.addAxis("independent", getIndependentAxisArgs(type, labels));
		_chart.addAxis("dependent-primary", getDependentAxisArgs(type, "primary", minval, maxval));
		_chart.addAxis("dependent-secondary", getDependentAxisArgs(type, "secondary", minval, maxval));
		
		return _chart;
	};

	// set up a legend presentation
	var setupLegend = function(/*DomNode*/domNode, /*Legend*/legend, /*Chart2D*/chart, /*Boolean*/horizontal){
		// destroy any existing legend and recreate
		var _legend = legend;
		
		if(!_legend){
			_legend = new dojox.charting.widget.Legend({ chart: chart, horizontal: horizontal }, domNode);
		}else{
			_legend.refresh();
		}
		
		return _legend;
	};
	
	// set up a grid presentation
	var setupGrid = function(/*DomNode*/domNode, /*Object?*/grid, /*Object?*/store, /*String?*/query, /*String?*/queryOptions){
		var _grid = grid || new dojox.grid.DataGrid({}, domNode);
		_grid.startup();
		_grid.setStore(store, query, queryOptions);
		
		var structure = [];
		for(var ser = 0; ser < store.series_name.length; ser++){
			// only include series with grid=true and with some data values in
			if(store.series_grid[ser] && (store.series_data[ser].length > 0)){
				structure.push({ field: "data." + ser, name: store.series_name[ser], width: "auto", formatter: store.series_gridformatter[ser] });
			}
		}
		
		_grid.setStructure(structure);
		
		return _grid;
	};
	
	// set up a title presentation
	var setupTitle = function(/*DomNode*/domNode, /*object*/store){
		if(store.title){
			domNode.innerHTML = store.title;
		}
	};
	
	// set up a footer presentation
	var setupFooter = function(/*DomNode*/domNode, /*object*/store){
		if(store.footer){
			domNode.innerHTML = store.footer;
		}
	};
	
	// obtain a subfield from a field specifier which may contain
	// multiple levels (eg, "child.foo[36].manacle")
	var getSubfield = function(/*Object*/object, /*String*/field){
		var result = object;
		
		if(field){
			var fragments = field.split(/[.\[\]]+/);
			for(var frag = 0, l = fragments.length; frag < l; frag++){
				if(result){
					result = result[fragments[frag]];
				}
			}
		}
		
		return result;
	};
	
	dojo.declare("dojox.widget.DataPresentation", null, {
		// summary:
		//		A widget that connects to a data store in a simple manner,
		//		and also provides some additional convenience mechanisms
		//		for connecting to common data sources without needing to
		//		explicitly construct a Dojo data store. The widget can then
		//		present the data in several forms: as a graphical chart,
		//		as a tabular grid, or as display panels presenting meta-data
		//		(title, creation information, etc) from the data. The
		//		widget can also create and manage several of these forms
		//		in one simple construction.
		//
		//		Note: this is a first experimental draft and any/all details
		//		are subject to substantial change in later drafts.
		// example:
		// |	var pres = new dojox.data.DataPresentation("myChartNode", {
		// |		type: "chart",
		// |		url: "/data/mydata",
		// |		gridNode: "myGridNode"
		// |	});

		// store: Object
		//		Dojo data store used to supply data to be presented. This may
		//		be supplied on construction or created implicitly based on
		//		other construction parameters ('data', 'url').

		// query: String
		//		Query to apply to the Dojo data store used to supply data to
		//		be presented.

		// queryOptions: String
		//		Query options to apply to the Dojo data store used to supply
		//		data to be presented.

		// data: Object
		//		Data to be presented. If supplied on construction this property
		//		will override any value supplied for the 'store' property.

		// url: String
		//		URL to fetch data from in JSON format. If supplied on
		//		construction this property will override any values supplied
		//		for the 'store' and/or 'data' properties. Note that the data
		//		can also be comment-filtered JSON, although this will trigger
		//		a warning message in the console unless djConfig.useCommentedJson
		//		has been set to true.

		// urlContent: Object
		//		Content to be passed to the URL when fetching data. If a URL has
		//		not been supplied, this value is ignored.

		// urlError: function
		//		A function to be called if an error is encountered when fetching
		//		data from the supplied URL. This function will be supplied with
		//		two parameters exactly as the error function supplied to the
		//		dojo.xhrGet function. This function may be called multiple times
		//		if a refresh interval has been supplied.

		// refreshInterval: Number
		//		the time interval in milliseconds after which the data supplied
		//		via the 'data' property or fetched from a URL via the 'url'
		//		property should be regularly refreshed. This property is
		//		ignored if neither the 'data' nor 'url' property has been
		//		supplied. If the refresh interval is zero, no regular refresh is done.

		// refreshIntervalPending:
		//		the JavaScript set interval currently in progress, if any

		// series: Array
		//		an array of objects describing the data series to be included
		//		in the data presentation. Each object may contain the
		//		following fields:
		//
		//		- datapoints: the name of the field from the source data which
		//			contains an array of the data points for this data series.
		//			If not supplied, the source data is assumed to be an array
		//			of data points to be used.
		//		- field: the name of the field within each data point which
		//			contains the data for this data series. If not supplied,
		//			each data point is assumed to be the value for the series.
		//		- name: a name for the series, used in the legend and grid headings
		//		- namefield:
		//			the name of the field from the source data which
		//			contains the name the series, used in the legend and grid
		//			headings. If both name and namefield are supplied, name takes
		//		    precedence. If neither are supplied, a default name is used.
		//		- chart: true if the series should be included in a chart presentation (default: true)
		//		- charttype: the type of presentation of the series in the chart, which can be
		//			"range", "line", "bar" (default: "bar")
		//		- linestyle: the stroke style for lines (if applicable) (default: "Solid")
		//		- axis: the dependant axis to which the series will be attached in the chart,
		//		    which can be "primary" or "secondary"
		//		- grid: true if the series should be included in a data grid presentation (default: true)
		//		- gridformatter: an optional formatter to use for this series in the data grid
		//
		//		a call-back function may alternatively be supplied. The function takes
		//		a single parameter, which will be the data (from the 'data' field or
		//		loaded from the value in the 'url' field), and should return the array
		//		of objects describing the data series to be included in the data
		//		presentation. This enables the series structures to be built dynamically
		//		after data load, and rebuilt if necessary on data refresh. The call-back
		//		function will be called each time new data is set, loaded or refreshed.
		//		A call-back function cannot be used if the data is supplied directly
		//		from a Dojo data store.

		// type: String
		//		the type of presentation to be applied at the DOM attach point.
		//		This can be 'chart', 'legend', 'grid', 'title', 'footer'. The
		//		default type is 'chart'.
		type: "chart",

		// chartType: String
		//		the type of chart to display. This can be 'clusteredbars',
		//		'areas', 'stackedcolumns', 'stackedbars', 'stackedareas',
		//		'lines', 'hybrid'. The default type is 'bar'.
		chartType: "clusteredBars",

		// reverse: Boolean
		//		true if the chart independent axis should be reversed.
		reverse: false,

		// animate: Object
		//		if an object is supplied, then the chart bars or columns will animate
		//		into place. If the object contains a field 'duration' then the value
		//		supplied is the duration of the animation in milliseconds, otherwise
		//		a default duration is used. A boolean value true can alternatively be
		//		supplied to enable animation with the default duration.
		//		The default is null (no animation).
		animate: null,

		// labelMod: Integer
		//		the frequency of label annotations to be included on the
		//		independent axis. 1=every label. 0=no labels. The default is 1.
		labelMod: 1,

		// tooltip: String|Function
		//		a string pattern defining the tooltip text to be applied to chart
		//		data points, or a function which takes a single parameter and returns
		//		the tooltip text to be applied to chart data points. The string pattern
		//		will have the following substitutions applied:
		//
		//		- {0} - the type of chart element ('bar', 'surface', etc)
		//		- {1} - the name of the data series
		//		- {2} - the independent axis value at the tooltip data point
		//		- {3} - the series value at the tooltip data point point
		//
		//		The function, if supplied, will receive a single parameter exactly
		//		as per the dojox.charting.action2D.Tooltip class. The default value
		//		is to apply the default tooltip as defined by the
		//		dojox.charting.action2D.Tooltip class.

		// legendHorizontal: Boolean|Number
		//		true if the legend should be rendered horizontally, or a number if
		//		the legend should be rendered as horizontal rows with that number of
		//		items in each row, or false if the legend should be rendered
		//		vertically (same as specifying 1). The default is true (legend
		//		rendered horizontally).
		legendHorizontal: true,

		// theme: String|Theme
		//		a theme to use for the chart, or the name of a theme.

		// chartNode: String|DomNode
		//		an optional DOM node or the id of a DOM node to receive a
		//		chart presentation of the data. Supply only when a chart is
		//		required and the type is not 'chart'; when the type is
		//		'chart' this property will be set to the widget attach point.

		// legendNode: String|DomNode
		//		an optional DOM node or the id of a DOM node to receive a
		//		chart legend for the data. Supply only when a legend is
		//		required and the type is not 'legend'; when the type is
		//		'legend' this property will be set to the widget attach point.

		// gridNode: String|DomNode
		//		an optional DOM node or the id of a DOM node to receive a
		//		grid presentation of the data. Supply only when a grid is
		//		required and the type is not 'grid'; when the type is
		//		'grid' this property will be set to the widget attach point.

		// titleNode: String|DomNode
		//		an optional DOM node or the id of a DOM node to receive a
		//		title for the data. Supply only when a title is
		//		required and the type is not 'title'; when the type is
		//		'title' this property will be set to the widget attach point.

		// footerNode: String|DomNode
		//		an optional DOM node or the id of a DOM node to receive a
		//		footer presentation of the data. Supply only when a footer is
		//		required and the type is not 'footer'; when the type is
		//		'footer' this property will be set to the widget attach point.

		// chartWidget: Object
		//		the chart widget, if any

		// legendWidget: Object
		//		the legend widget, if any

		// gridWidget: Object
		//		the grid widget, if any
		
		constructor: function(node, args){
			// summary:
			//		Set up properties and initialize.
			// node: DomNode
			//		The node to attach the data presentation to.
			// args: Object
			//		(see above)
			
			// apply arguments directly
			dojo.mixin(this, args);

			// store our DOM attach point
			this.domNode = dojo.byId(node);
			
			// also apply the DOM attach point as the node for the presentation type
			this[this.type + "Node"] = this.domNode;
			
			// load the theme if provided by name
			if(typeof this.theme == 'string'){
				this.theme = dojo.getObject(this.theme);
			}
			
			// resolve any the nodes that were supplied as ids
			this.chartNode = dojo.byId(this.chartNode);
			this.legendNode = dojo.byId(this.legendNode);
			this.gridNode = dojo.byId(this.gridNode);
			this.titleNode = dojo.byId(this.titleNode);
			this.footerNode = dojo.byId(this.footerNode);
			
			// we used to support a 'legendVertical' so for now
			// at least maintain backward compatibility
			if(this.legendVertical){
				this.legendHorizontal = !this.legendVertical;
			}
			
			if(this.url){
				this.setURL(null, null, this.refreshInterval);
			}
			else{
				if(this.data){
					this.setData(null, this.refreshInterval);
				}
				else{
					this.setStore();
				}
			}
		},
		
		setURL: function(/*String?*/url, /*Object?*/ urlContent, /*Number?*/refreshInterval){
			// summary:
			//		Sets the URL to fetch data from, with optional content
			//		supplied with the request, and an optional
			//		refresh interval in milliseconds (0=no refresh)

			// if a refresh interval is supplied we will start a fresh
			// refresh after storing the supplied url
			if(refreshInterval){
				this.cancelRefresh();
			}
			
			this.url = url || this.url;
			this.urlContent = urlContent || this.urlContent;
			this.refreshInterval = refreshInterval || this.refreshInterval;
			
			var me = this;
			
			dojo.xhrGet({
				url: this.url,
				content: this.urlContent,
				handleAs: 'json-comment-optional',
				load: function(response, ioArgs){
					me.setData(response);
				},
				error: function(xhr, ioArgs){
					if(me.urlError && (typeof me.urlError == "function")){
						me.urlError(xhr, ioArgs);
					}
				}
			});
			
			if(refreshInterval && (this.refreshInterval > 0)){
				this.refreshIntervalPending = setInterval(function(){
					me.setURL();
				}, this.refreshInterval);
			}
		},
		
		setData: function(/*Object?*/data, /*Number?*/refreshInterval){
			// summary:
			//		Sets the data to be presented, and an optional
			//		refresh interval in milliseconds (0=no refresh)
			
			// if a refresh interval is supplied we will start a fresh
			// refresh after storing the supplied data reference
			if(refreshInterval){
				this.cancelRefresh();
			}
			
			this.data = data || this.data;
			this.refreshInterval = refreshInterval || this.refreshInterval;
			
			// TODO if no 'series' property was provided, build one intelligently here
			// (until that is done, a 'series' property must be supplied)
			
			var _series = (typeof this.series == 'function') ? this.series(this.data) : this.series;

			var datasets = [],
				series_data = [],
				series_name = [],
				series_chart = [],
				series_charttype = [],
				series_linestyle = [],
				series_axis = [],
				series_grid = [],
				series_gridformatter = [],
				maxlen = 0;
			
			// identify the dataset arrays in which series values can be found
			for(var ser = 0; ser < _series.length; ser++){
				datasets[ser] = getSubfield(this.data, _series[ser].datapoints);
				if(datasets[ser] && (datasets[ser].length > maxlen)){
					maxlen = datasets[ser].length;
				}
				
				series_data[ser] = [];
				// name can be specified in series structure, or by field in series structure, otherwise use a default
				series_name[ser] = _series[ser].name || (_series[ser].namefield ? getSubfield(this.data, _series[ser].namefield) : null) || ("series " + ser);
				series_chart[ser] = (_series[ser].chart !== false);
				series_charttype[ser] = _series[ser].charttype || "bar";
				series_linestyle[ser] = _series[ser].linestyle;
				series_axis[ser] = _series[ser].axis || "primary";
				series_grid[ser] = (_series[ser].grid !== false);
				series_gridformatter[ser] = _series[ser].gridformatter;
			}
		
			// create an array of data points by sampling the series
			// and an array of series arrays by collecting the series
			// each data point has an 'index' item containing a sequence number
			// and items named "data.0", "data.1", ... containing the series samples
			// and the first data point also has items named "name.0", "name.1", ... containing the series names
			// and items named "series.0", "series.1", ... containing arrays with the complete series in
			var point, datapoint, datavalue, fdatavalue;
			var datapoints = [];
			
			for(point = 0; point < maxlen; point++){
				datapoint = { index: point };
				for(ser = 0; ser < _series.length; ser++){
					if(datasets[ser] && (datasets[ser].length > point)){
						datavalue = getSubfield(datasets[ser][point], _series[ser].field);
						
						if(series_chart[ser]){
							// convert the data value to a float if possible
							fdatavalue = parseFloat(datavalue);
							if(!isNaN(fdatavalue)){
								datavalue = fdatavalue;
							}
						}
						
						datapoint["data." + ser] = datavalue;
						series_data[ser].push(datavalue);
					}
				}
				datapoints.push(datapoint);
			}

			if(maxlen <= 0){
				datapoints.push({index: 0});
			}
		
			// now build a prepared store from the data points we've constructed
			var store = new dojo.data.ItemFileWriteStore({ data: { identifier: 'index', items: datapoints }});
			if(this.data.title){
				store.title = this.data.title;
			}
			if(this.data.footer){
				store.footer = this.data.footer;
			}
			
			store.series_data = series_data;
			store.series_name = series_name;
			store.series_chart = series_chart;
			store.series_charttype = series_charttype;
			store.series_linestyle = series_linestyle;
			store.series_axis = series_axis;
			store.series_grid = series_grid;
			store.series_gridformatter = series_gridformatter;
			
			this.setPreparedStore(store);
			
			if(refreshInterval && (this.refreshInterval > 0)){
				var me = this;
				this.refreshIntervalPending = setInterval(function(){
					me.setData();
				}, this.refreshInterval);
			}
		},
		
		refresh: function(){
			// summary:
			//		If a URL or data has been supplied, refreshes the
			//		presented data from the URL or data. If a refresh
			//		interval is also set, the periodic refresh is
			//		restarted. If a URL or data was not supplied, this
			//		method has no effect.
			if(this.url){
				this.setURL(this.url, this.urlContent, this.refreshInterval);
			}else if(this.data){
				this.setData(this.data, this.refreshInterval);
			}
		},
		
		cancelRefresh: function(){
			// summary:
			//		Cancels any and all outstanding data refreshes
			if(this.refreshIntervalPending){
				// cancel existing refresh
				clearInterval(this.refreshIntervalPending);
				this.refreshIntervalPending = undefined;
			}
		},
	
		setStore: function(/*Object?*/store, /*String?*/query, /*Object?*/queryOptions){
			// FIXME build a prepared store properly -- this requires too tight a convention to be followed to be useful
			this.setPreparedStore(store, query, queryOptions);
		},
		
		setPreparedStore: function(/*Object?*/store, /*String?*/query, /*Object?*/queryOptions){
			// summary:
			//		Sets the store and query.

			this.preparedstore = store || this.store;
			this.query = query || this.query;
			this.queryOptions = queryOptions || this.queryOptions;
			
			if(this.preparedstore){
				if(this.chartNode){
					this.chartWidget = setupChart(this.chartNode, this.chartWidget, this.chartType, this.reverse, this.animate, this.labelMod, this.theme, this.tooltip, this.preparedstore, this.query, this.queryOptions);
					this.renderChartWidget();
				}
				if(this.legendNode){
					this.legendWidget = setupLegend(this.legendNode, this.legendWidget, this.chartWidget, this.legendHorizontal);
				}
				if(this.gridNode){
					this.gridWidget = setupGrid(this.gridNode, this.gridWidget, this.preparedstore, this.query, this.queryOptions);
					this.renderGridWidget();
				}
				if(this.titleNode){
					setupTitle(this.titleNode, this.preparedstore);
				}
				if(this.footerNode){
					setupFooter(this.footerNode, this.preparedstore);
				}
			}
		},
		
		renderChartWidget: function(){
			// summary:
			//		Renders the chart widget (if any). This method is
			//		called whenever a chart widget is created or
			//		configured, and may be connected to.
			if(this.chartWidget){
				this.chartWidget.render();
			}
		},
		
		renderGridWidget: function(){
			// summary:
			//		Renders the grid widget (if any). This method is
			//		called whenever a grid widget is created or
			//		configured, and may be connected to.
			if(this.gridWidget){
				this.gridWidget.render();
			}
		},
		
		getChartWidget: function(){
			// summary:
			//		Returns the chart widget (if any) created if the type
			//		is "chart" or the "chartNode" property was supplied.
			return this.chartWidget;
		},
		
		getGridWidget: function(){
			// summary:
			//		Returns the grid widget (if any) created if the type
			//		is "grid" or the "gridNode" property was supplied.
			return this.gridWidget;
		},
		
		destroy: function(){
			// summary:
			//		Destroys the widget and all components and resources.

			// cancel any outstanding refresh requests
			this.cancelRefresh();
			
			if(this.chartWidget){
				this.chartWidget.destroy();
				delete this.chartWidget;
			}
			
			if(this.legendWidget){
				// no legend.destroy()
				delete this.legendWidget;
			}

			if(this.gridWidget){
				// no grid.destroy()
				delete this.gridWidget;
			}
			
			if(this.chartNode){
				this.chartNode.innerHTML = "";
			}
			
			if(this.legendNode){
				this.legendNode.innerHTML = "";
			}
			
			if(this.gridNode){
				this.gridNode.innerHTML = "";
			}
			
			if(this.titleNode){
				this.titleNode.innerHTML = "";
			}
			
			if(this.footerNode){
				this.footerNode.innerHTML = "";
			}
		}
		
	});
		
})();