Class actuate.Dashboard

Dashboard class represents a Dashboard object.
Member of: actuate.

Class Summary
Constructor Attributes	Constructor Name and Description
	actuate.Dashboard(container) Constructs a new Dashboard object.

Method Summary
Method Attributes	Method Name and Description
	downloadDashboard(callback) Downloads the dashboard metadata definitions.
	embedTemplate(isEmbeded) A personal dashboard can use a shared template file or embed a template file.
	getActiveTab() Returns the name of the current active tab for the dashboard.
	getDashboardName() Returns the dashboard name used by the dashboard object.
	getTemplate() Returns the repository path for the iServer volume.
	isAutoSaveEnabled() Returns whether the autosave feature is enabled.
	isSavingNeeded() Returns whether there are unsaved changes on the dashboard.
	isUsingPersonalDashboard() Returns whether this dashboard is a personal dashboard.
	onUnload() Unloads JavaScript variables that are no longer needed by the dashboard.
	registerEventHandler(eventName, handler) Registers an event handler to activate for parameter eventName.
	removeEventHandler(eventName, handler) Removes an event handler to activate for parameter eventName.
	renderContent(dashboardMetadatas, callback) Renders the dashboard definitions content to the container.
	save(callback, flag) Saves the dashboard as a .dashboard file.
	saveAs(callback, saveAsPath, replace, flag) Saves the dashboard as a .dashboard file to a specific path.
	setActiveTab(tabName) Sets a specified tab as the active tab.
	setAutoSaveDelay(seconds) Sets the amount of time before executing an automatic save for a personal dashboard.
	setContainer(containerID) The container that will be used for rendering the dashboard page HTML fragment.
	setDashboardName(dashboardName) Sets the dashboard name to view.
	setHeight(height) Sets the dashboard's startup height.
	setService(iportalURL, requestOptions) Sets the web service this dashboard component connects to.
	setSize(width, height) Sets the dashboard's startup size.
	setTemplate(path) Sets the template path.
	setWidth(width) Sets the dashboard's startup width.
	showGallery(show) Shows the gadget gallery.
	showTabNavigation(show) Shows the tab toolbar.
	submit(callback) Submits requests to the server for the dashboard.
	usePersonalDashboard(true\|false) Forces the dashboard framework to use the user's personal dashboard.

Class Detail

actuate.Dashboard(container)

Constructs a new Dashboard object.

Parameters:
{String} container: Optional container object or name of a container in the current document ID of container where controls are to be rendered.

Method Detail

{void} downloadDashboard(callback)

Downloads the dashboard metadata definitions. This example specifies a function to call after the dashboard object finishes downloading:

	myDashboard.downloadDashboard(runNext);
	function runNext(dashobject){
		mydashboard.getDashboardName(dashobject);
	}

Parameters:
{Function} callback: The callback function to use after the dashboard finishes downloading. This function must take the returned dashboard object as an input parameter.

Returns:: {void}

{void} embedTemplate(isEmbeded)

A personal dashboard can use a shared template file or embed a template file. This example specifies that the personal dashboard myDashboard uses an embedded template file:

	myDashboard.embedTemplate(true);

Parameters:
{boolean} isEmbeded: When the isEmbedded parameter is true, the personal dashboard uses an embedded template file. The default value is false.

Returns:: {void}

{String} getActiveTab()

Returns the name of the current active tab for the dashboard. This example displays the name of the active tab for the myDashboard dashboard object in an alert box:

	alert(myDashboard.getActiveTab( ));

Returns:: {String} The name of the current active dashboard tab.

{String} getDashboardName()

Returns the dashboard name used by the dashboard object. This example displays the dashboard object's dashboard name in an alert box:

	myDashboard.downloadDashboard(runNext);
	function runNext(dashobject){
		mydashboard.getDashboardName(dashobject);
	}

Returns:: {String} dashboardName. Return null if not set

{String} getTemplate()

Returns the repository path for the iServer volume. This example displays the repository path for the iServer volume in an alert box:

	alert(myDashboard.getTemplate( ));

Returns:: {String} iServer volume repository path or null if not set

{boolean} isAutoSaveEnabled()

Returns whether the autosave feature is enabled. This example informs the user of the status of the autosave feature:

	if (dashboard.isAutoSavEnabled()){
		alert("Autosave is enabled.");
	}else{
		alert("Autosave is disabled.");
	}

Returns:: {boolean} True indicates that autosave is enabled.

{boolean} isSavingNeeded()

Returns whether there are unsaved changes on the dashboard. This example informs the user of unsaved changed:

	if (dashboard.isSavingNeeded()){
		alert("The dashboard contains unsaved changes.");
	}

Returns:: {boolean} True indicates that there are unsaved changes on the dashboard.

{boolean} isUsingPersonalDashboard()

Returns whether this dashboard is a personal dashboard. This example informs the user that they are using a personal dashboard:

	if (dashboard.isUsingPersonalDashboard)){
		alert("This is a personal dashboard.");
	}

Returns:: {boolean} True indicates that this dashboard is a personal dashboard.

{void} onUnload()

Unloads JavaScript variables that are no longer needed by the dashboard. This example unloads JavaScript variables and displays the Dashboard object's dashboard name in an alert box:

	myDashboard.onUnload;
	alert("JS variables unloaded for " + myDashboard.getDashboardName( ));

Returns:: {void}

{void} registerEventHandler(eventName, handler)

Registers an event handler to activate for parameter eventName. This function can assign several handlers to a single event. This example registers the errorHandler( ) function to respond to the ON_EXCEPTION event:

	myDashboard.registerEventHandler(actuate.dashboard.EventConstants.ON_EXCEPTION, errorHandler);

Parameters:
{String} eventName: Event name to capture.
{Function} handler: The function to execute when the event occurs. The handler must take two arguments: The dashboard instance that fired the event and an event object specific to the event type.

Returns:: {void}

See:: actuate.dashboard.EventConstants for supported Dashboard events

{void} removeEventHandler(eventName, handler)

Removes an event handler to activate for parameter eventName. This example removes the errorHandler( ) function from responding to the ON_EXCEPTION event:

	myDashboard.removeEventHandler(actuate.dashboard.EventConstants.ON_EXCEPTION, errorHandler);

Parameters:
{String} eventName: Event name to remove from the internal list of registered events.
{Function} handler: The function to disable.

Returns:: {void}

See:: actuate.dashboard.EventConstants for supported Dashboard events

{void} renderContent(dashboardMetadatas, callback)

Renders the dashboard definitions content to the container. The #submit function calls the #renderContent internally. The #renderContent function assumes that the user has already a list of actuate.dashboard.DashboardDefinition objects to process. This example renders the myDash dashboard object using the actuate.dashboard.DashboardDefinition array defs and calls the #afterRender callback once complete:

	myDash.renderContent(defs, afterRender);

Parameters:

{Array} dashboardMetadatas

Each object is some piece of dashboard metadata and as many can be added as needed. Typically, this array contains the following metadata:

Number of tabs in a dashboard file
Number of sections/columns in a dashboard tab
Number of gadgets in each section/column
Attributes of each gadget
Attributes of each tab
Dependency information between gadgets to support publishing and subscribing mechanism

{Function} callback

The callback function to call after #renderContent finishes.

Returns:: {void}

{void} save(callback, flag)

Saves the dashboard as a .dashboard file. This example saves the dashboard as .dashboard file:

	myDash.save( );

Parameters:
{function} callback: Optional. The function to execute after the save operation completes.
{boolean} flag: Optional. True indicates a synchronous save operation.

Returns:: {void} throws an exception if save fails

{void} saveAs(callback, saveAsPath, replace, flag)

Saves the dashboard as a .dashboard file to a specific path. This example saves the dashboard as .dashboard file, replacing the latest version:

	myDash.saveAs(null, null, true, true);

Parameters:
{function} callback: Optional. The function to execute after the save operation completes.
{string} saveAsPath: Optional. Fully qualified path in which to save the dashboard. The default value is the path for the original dashboard file, if one exists, or the path for the user's home directory.
{boolean} replace: Optional. True indicates to replace the latest version of the file. False indicates to create a new version.
{boolean} flag: Optional. True indicates a synchronous save operation.

Returns:: {void}

setActiveTab(tabName)

Sets a specified tab as the active tab. Only one tab can be active at a time. This example sets the Files tab as the active tab for this dashboard:

	myDash.setActiveTab("Files");

Parameters:
{String} tabName: The name of the tab to set as the active tab.

{void} setAutoSaveDelay(seconds)

Sets the amount of time before executing an automatic save for a personal dashboard. This example sets the delay for the automatic save for dashboard myDash to 5 minutes:

	myDash.setAutoSaveDelay(300);

Parameters:
{integer} seconds: The number of seconds to delay the automatic save.

Returns:: {void}

{void} setContainer(containerID)

The container that will be used for rendering the dashboard page HTML fragment. This example sets the container where the myDash dashboard object renders:

	myDash.setContainer("leftpane");

Parameters:
{String} containerID: The container ID.

Returns:: {void}

{void} setDashboardName(dashboardName)

Sets the dashboard name to view. This example sets the path for the myDash dashboard object:

	myDash.setDashboardName("/Dashboard/Contents/Hello.DASHBOARD");

Parameters:
{String} dashboardName: A fully qualified repository path and file name.

Returns:: {void}

{void} setHeight(height)

Sets the dashboard's startup height. To set the dashboard height to 400 pixels, use code similar to the following:

	myDashboard.setHeight(400);

Parameters:
{integer} height: Specifies the height in pixels.

Returns:: {void}

{void} setService(iportalURL, requestOptions)

Sets the web service this dashboard component connects to. This example connects a dashboard component to the iPortal service and adds a custom URL parameter:

	function setDashboardService( ){
		myDashboard.setService("http://localhost:8700/iportal", myRequestOptions.setCustomParameters({myParam: "myValue"});
	}

Parameters:
{String} iportalURL: The URL of the web service to connect to.
{actuate.RequestOptions} requestOptions: Request options, if any, to apply to the connection.

Returns:: {void}

See:: actuate.RequestOptions for details on the options that this parameter can set.

{void} setSize(width, height)

Sets the dashboard's startup size. To set the dashboard height to 400 pixels and the width to 800 pixels, use code similar to the following:

	myDashboard.setSize(400, 800);

Parameters:
{integer} width: Width in pixels.
{integer} height: Height in pixels.

Returns:: {void}

{void} setTemplate(path)

Sets the template path. This function overwrites the template path that is used by Information Console. This example sets the template path for myDashboard to /iportal/jsapi/template/path:

	myDashboard.setTemplate("/iportal/jsapi/template/path");

Parameters:
{String} path: Specifies a new template path. Use an iServer volume repository path.

Returns:: {void}

{void} setWidth(width)

Sets the dashboard's startup width. To set the dashboard width to 800 pixels, use code similar to the following:

	myDashboard.setWidth(800);

Parameters:
{integer} width: Specifies the width in pixels.

Returns:: {void}

{void} showGallery(show)

Shows the gadget gallery. To show the gadget gallery for the myDashboard dashboard object, use code similar to the following:

	myDashboard.showGallery(true);

Parameters:
{boolean} show: The gadget gallery is visible when this parameter is set to true.

Returns:: {void}

{void} showTabNavigation(show)

Shows the tab toolbar. To show the tab toolbar for the myDashboard dashboard object, use code similar to the following:

	myDashboard.showTabNavigation(true);

Parameters:
{boolean} show: The tab toolbar is visible when this parameter is set to true.

Returns:: {void}

{void} submit(callback)

Submits requests to the server for the dashboard. When this function is called, an AJAX request is triggered to submit all pending operations. When the server finishes the processing, it returns a response and the results are rendered on the page in the dashboard container. This example submits the dashboard name that was set with #setDashboardName:

	dash.setDashboardName("/Dashboard/Contents/Hello.DASHBOARD");
	dash.submit( );

Parameters:
{Function} callback: The function to execute after the asynchronous call processing is done.

Returns:: {void}

{void} usePersonalDashboard(true|false)

Forces the dashboard framework to use the user's personal dashboard. To force the use of a personal dashboard for the myDashboard object, use code similar to the following:

	myDashboard.usePersonalDashboard(true);

Parameters:
{boolean} true|false: A value of true sets the dashboard framework to ignore any value set by the #setDashboardName function. The dashboard framework creates a new personal dashboard file for the logged in user when no personal dashboard file is present.

Returns:: {void}

Classes

Class actuate.Dashboard