Class actuate.Dashboard

Represents a dashboard object.
Member of: actuate.

Class Summary
Constructor Attributes	Constructor Name and Description
	actuate.Dashboard(container) Constructs a Dashboard object to contain gadgets such as reportlets, charts, and parameter selectors.

Method Summary
Method Attributes	Method Name and Description
	downloadDashboard(callback) Downloads the dashboard metadata information and runs a callback function.
	embedTemplate(isEmbeded) Specifies whether to embed a template file in a personal dashboard rather than using a shared template file.
	getActiveTab() Returns the name of the current active tab for the dashboard.
	getDashboardName() Returns the name of the dashboard used by the Dashboard object.
	getTemplate() Returns the template path in the iHub volume.
	isAutoSaveEnabled() Returns whether the autosave feature is enabled.
	isSavingNeeded() Returns whether there are unsaved changes on the dashboard.
	isToolbarVisible() Returns whether the dashboard editor toolbar is visible.
	isUsingPersonalDashboard() Returns whether this dashboard is a personal dashboard.
	onUnload() Unloads JavaScript variables no longer needed by the dashboard.
	registerEventHandler(eventName, handler) Registers an event handler to activate for parameter eventName, defined by the constants in actuate.dashboard.EventConstants.
	removeEventHandler(eventName, handler) Removes an event handler activated for parameter eventName, defined by the constants in actuate.dashboard.EventConstants.
	renderContent(dashboardMetadatas, callback) Renders the dashboard definitions content to the container.
	save(callback, flag) Saves the dashboard file.
	saveAs(callback, saveAsPath, replace, flag) Saves the dashboard file to a specific path.
	setActiveTab(tabName) Sets the specified tab to be the active tab.
	setAutoSaveDelay(seconds) Sets the length of time to wait before automatically saving modifications to a personal dashboard.
	setContainer(containerID) Specifies the container to used for rendering the dashboard page HTML fragment.
	setDashboardName(dashboardName) Sets the name of the dashboard to open.
	setHeight(height) Sets the height of the dashboard.
	setIsStandalone(isStandalone) Specifies whether the dashboard is a self-contained web page or embedded.
	setService(iportalUrl, requestOptions) Sets the web service this dashboard component connects to.
	setSize(width, height) Sets the size of the dashboard.
	setTemplate(path) Sets the template path.
	setWidth(width) Sets the width of the dashboard.
	showGallery(show) Shows the gadget gallery for designing a dashboard layout.
	showTabNavigation(show) Shows or hides 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 Dashboard object to contain gadgets such as reportlets, charts, and parameter selectors.

Parameters:
{String} container: Optional Container object or the name of a container in the current document in which to render controls.

Method Detail

{void} downloadDashboard(callback)

Downloads the dashboard metadata information and runs a callback function. The callback receives a Dashboard object and can run Dashboard methods on that object. This example specifies the function to call after the dashboard object finishes downloading:

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

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

Returns:: {void}

{void} embedTemplate(isEmbeded)

Specifies whether to embed a template file in a personal dashboard rather than using a shared template file. This example specifies that the personal dashboard myDashboard uses an embedded template file:

	myDashboard.embedTemplate(true);

Parameters:
{boolean} isEmbeded: When 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 currently active dashboard tab

{String} getDashboardName()

Returns the name of the dashboard 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} The name of the dashboard or null if no dashboard is open

{String} getTemplate()

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

	alert(myDashboard.getTemplate( ));

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

{boolean} isAutoSaveEnabled()

Returns whether the autosave feature is enabled. Autosave saves the modifications to a dashboard at specified time intervals. 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 when autosave is enabled

See:: #setAutoSaveDelay

{boolean} isSavingNeeded()

Returns whether there are unsaved changes on the dashboard. This example displays an alert box when the dashboard contains unsaved changes:

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

Returns:: {boolean} True when there are unsaved changes on the dashboard

{boolean} isToolbarVisible()

Returns whether the dashboard editor toolbar is visible. This example displays an alert box when the toolbar is hidden from the user:

	if (!dashboard.isToolbarVisible()){
		alert("The dashboard editor toolbar is hidden.");
	}

Returns:: {boolean} True when the dashboard editor toolbar is visible.

{boolean} isUsingPersonalDashboard()

Returns whether this dashboard is a personal dashboard. This example displays an alert box if the user is using a personal dashboard:

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

Returns:: {boolean} True for a personal dashboard. False for a shared dashboard.

{void} onUnload()

Unloads JavaScript variables 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, defined by the constants in actuate.dashboard.EventConstants. 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 activated for parameter eventName, defined by the constants in actuate.dashboard.EventConstants. This example removes the errorHandler( ) function 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 this function. 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 function after the rendering is complete:

	myDash.renderContent(defs, afterRender);

Parameters:

{Array} dashboardMetadatas

An array of dashboard metadata actuate.dashboard.DashboardDefinition objects. 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 among gadgets to support publishing and subscribing

{Function} callback

The function to call after renderContent( ) completes.

Returns:: {void}

{void} save(callback, flag)

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

	myDash.save( );

Parameters:
{function} callback: Optional function to execute after the save operation completes.
{boolean} flag: Optional. When true, wait for the save operation to complete.

Returns:: {void} Throws an exception if saving the file fails

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

Saves the 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 function to execute after the save operation completes.
{string} saveAsPath: Optional fully qualified path to which to save the dashboard. The default value is the path of the original dashboard file, if one exists, or the path of the user's home directory.
{boolean} replace: Optional. When true, replace the latest version of the file. When false, create a new version.
{boolean} flag: Optional. When true, wait for the save operation to complete.

Returns:: {void}

setActiveTab(tabName)

Sets the specified tab to be the active tab. Only one tab is 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 length of time to wait before automatically saving modifications to 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 wait before automatically saving a modified personal dashboard

Returns:: {void}

{void} setContainer(containerID)

Specifies the container to used for rendering the dashboard page HTML fragment. This example sets the container where the myDash dashboard object appears:

	myDash.setContainer("leftpane");

Parameters:
{String} containerID: The container ID

Returns:: {void}

{void} setDashboardName(dashboardName)

Sets the name of the dashboard to open. 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 height of the dashboard. To set the dashboard height to 400 pixels, use code similar to the following:

	myDashboard.setHeight(400);

Parameters:
{integer} height: The height in pixels

Returns:: {void}

setIsStandalone(isStandalone)

Specifies whether the dashboard is a self-contained web page or embedded. In standalone mode, the dashboard uses the whole browser page and the browser title is based on the opened dashboard.

Parameters:
{boolean} isStandalone: When true, the dashboard is rendered as a stand-alone web page. The default value is false.

{void} setService(iportalUrl, requestOptions)

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

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

Parameters:
{String} iportalUrl: Web service URL to connect, for example, https://myhost.mycompany.com:8700/iportal
{actuate.RequestOptions} requestOptions: Request options, if any, to apply to the connection

Returns:: {void}

See:: actuate.RequestOptions for details on the options available.

{void} setSize(width, height)

Sets the size of the dashboard. 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: The width in pixels
{integer} height: The height in pixels

Returns:: {void}

{void} setTemplate(path)

Sets the template path. This path overrides the default template path 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: The new template path. Use an iHub volume repository path.

Returns:: {void}

{void} setWidth(width)

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

	myDashboard.setWidth(800);

Parameters:
{integer} width: The width in pixels

Returns:: {void}

{void} showGallery(show)

Shows the gadget gallery for designing a dashboard layout. This example shows the gadget gallery for the myDashboard dashboard object:

	myDashboard.showGallery(true);

Parameters:
{boolean} show: When true, the gadget gallery is visible.

Returns:: {void}

{void} showTabNavigation(show)

Shows or hides the tab toolbar. This example shows the tab toolbar for the myDashboard dashboard object:

	myDashboard.showTabNavigation(true);

Parameters:
{boolean} show: When true, the tab toolbar is visible. The default value is true.

Returns:: {void}

{void} submit(callback)

Submits requests to the server for the dashboard. This function triggers an AJAX request to submit all pending operations. When the server finishes 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 call after the asynchronous processing is complete

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: When true, the dashboard framework ignores any value set by the #setDashboardName function and the dashboard framework creates a new personal dashboard file for the logged in user if no personal dashboard file is present.

Returns:: {void}

Classes

Class actuate.Dashboard