Class actuate.Dashboard
Description
Represents a dashboard object.
Constructor
Syntax
actuate.Dashboard(string container)
Constructs a dashboard object.
Parameter
container
String. Optional. Container object or name of a container in the current document ID of container where controls are to be rendered.
Function summary
Table 44‑5 describes actuate.Dashboard functions.
Table 44‑5 actuate.Dashboard functions
Function
Description
downloadDashboard( )
Downloads the dashboard definitions.
embedTemplate( )
The personal dashboard uses an embedded template file.
getActiveTab( )
Returns the active tab name.
getDashboardName( )
Returns the dashboard name used by the dashboard object.
getTemplate( )
Returns the iHub volume repository path.
isAutoSaveEnabled( )
Returns whether autosave is enabled.
isSavingNeeded( )
Returns whether there are unsaved changes on the dashboard.
isUsingPersonalDashboard( )
Returns whether the dashboard is a personal dashboard.
onUnload( )
Unloads JavaScript variables that are no longer needed by the dashboard.
registerEventHandler( )
Registers an event handler.
removeEventHandler( )
Removes an event handler.
renderContent( )
Renders the dashboard.
save( )
Saves the dashboard as a .dashboard file.
saveAs( )
Saves the dashboard in non-default location.
setActiveTab( )
Sets a specific tab as the active tab.
setAutoSaveDelay( )
Sets the time interval before executing an automatic save for a personal dashboard.
setContainer( )
Sets the container for rendering the dashboard page HTML fragment.
setDashboardName( )
Sets the dashboard name to view.
setHeight( )
Sets the dashboard height.
setService( )
Sets the connection to the Actuate web service.
setSize( )
Sets the dashboard size.
setTemplate( )
Sets the template path.
setWidth( )
Sets the dashboard width.
showTabNavigation( )
Shows the tab toolbar.
submit( )
Submits the dashboard page component request.
usePersonalDashboard( )
Forces the dashboard framework to use a personal dashboard.
downloadDashboard
Syntax
void Dashboard.downloadDashboard(function callback)
Downloads the dashboard metadata definitions.
Parameter
callback
Function. The callback function to use after the dashboard finishes downloading. This function must take the returned dashboard object as an input parameter.
Example
This example specifies a function to call after the dashboard object finishes downloading:
myDashboard.downloadDashboard(runNext);
function runNext(dashobject){
mydashboard.getDashboardName(dashobject);
}
embedTemplate
Syntax
void Dashboard.embedTemplate(boolean isEmbedded)
A personal dashboard can use a shared template file or embed a template file.
Parameter
isEmbedded
Boolean. When the isEmbedded parameter is true, the personal dashboard uses an embedded template file. The default value is false.
Example
This example specifies that the personal dashboard myDashboard uses an embedded template file:
myDashboard.embedTemplate(true);
getActiveTab
Syntax
string Dashboard.getActiveTab
Returns the name of the current active tab for the dashboard.
Returns
String. The name of the current active dashboard tab.
Example
This example displays the name of the active tab for the myDashboard dashboard object in an alert box:
alert(myDashboard.getActiveTab( ));
getDashboardName
Syntax
string Dashboard.getDashboardName( )
Returns the dashboard name used by the dashboard object.
Returns
String. The dashboard’s name.
Example
This example displays the dashboard object’s dashboard name in an alert box:
alert(myDashboard.getDashboardName( ));
getTemplate
Syntax
string Dashboard.getTemplate( )
Returns the repository path for the iHub volume.
Returns
String. The repository path for the iHub volume.
Example
This example displays the repository path for the iHub volume in an alert box:
alert(myDashboard.getTemplate( ));
isAutoSaveEnabled
Syntax
boolean Dashboard.isAutoSaveEnabled( )
Returns whether the autosave feature is enabled.
Returns
Boolean. True indicates that autosave is enabled.
Example
This example informs the user of the status of the autosave feature:
if (dashboard.isAutoSavEnabled()){
alert("Autosave is enabled.");
}else{
alert("Autosave is disabled.");
}
isSavingNeeded
Syntax
boolean Dashboard.isSavingNeeded( )
Returns whether there are unsaved changes on the dashboard.
Returns
Boolean. True indicates that there are unsaved changes on the dashboard.
Example
This example informs the user of unsaved changed:
if (dashboard.isSavingNeeded()){
alert("The dashboard contains unsaved changes.");
}
isUsingPersonalDashboard
Syntax
boolean Dashboard.isUsingPersonalDashboard( )
Returns whether this dashboard is a personal dashboard.
Returns
Boolean. True indicates that this dashboard is a personal dashboard.
Example
This example informs the user that they are using a personal dashboard:
if (dashboard.isUsingPersonalDashboard)){
alert("This is a personal dashboard.");
}
onUnload
Syntax
void Dashboard.onUnload( )
Unloads JavaScript variables that are no longer needed by the dashboard.
Example
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( ));
registerEventHandler
Syntax
void Dashboard.registerEventHandler(string eventName, function handler)
Registers an event handler to activate for parameter eventName. This function can assign several handlers to a single event.
Parameters
eventName
String. Event name to capture.
handler
Function. 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.
Example
This example registers the errorHandler( ) function to respond to the ON_EXCEPTION event:
myDashboard.registerEventHandler(actuate.dashboard.EventConstants
.ON_EXCEPTION, errorHandler);
removeEventHandler
Syntax
void Dashboard.removeEventHandler(string eventName, function handler)
Removes an event handler to activate for parameter eventName.
Parameters
eventName
String. Event name to remove from the internal list of registered events.
handler
Function. The function to disable.
Example
This example removes the errorHandler( ) function from responding to the ON_EXCEPTION event:
myDashboard.removeEventHandler(actuate.dashboard.EventConstants
.ON_EXCEPTION, errorHandler);
renderContent
Syntax
void Dashboard.renderContent(object[ ] dashboardDefinitions, function callback)
Renders the dashboard definitions content to the container. The submit API calls the renderContent API internally. The renderContent( ) function assumes that the user has already a list of DashboardDefinition to process.
Parameters
dashboardDefinitions
Array of objects. 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
callback
Function. The callback function to call after renderContent( ) finishes.
Example
This example renders the myDash dashboard object using the dashboardDefinition array defs and calls afterRender( ) once complete:
myDash.renderContent(defs, afterRender);
save
Syntax
void Dashboard.save(function callback, boolean flag)
Saves the dashboard as a .dashboard file.
Parameters
callback
Function. Optional. The function to execute after the save operation completes.
flag
Boolean. Optional. True indicates a synchronous save operation.
Example
This example saves the dashboard as a .dashboard file:
myDash.save( );
saveAs
Syntax
void Dashboard.saveAs(function callback, string saveAsPath, boolean replace, boolean flag)
Saves the dashboard as a .dashboard file to a specific path.
Parameters
callback
Function. Optional. The function to execute after the save operation completes.
saveAsPath
String. 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.
replace
Boolean. Optional. True indicates to replace the latest version of the file. False indicates to create a new version.
flag
Boolean. Optional. True indicates a synchronous save operation.
Example
This example saves the dashboard as a .dashboard file, replacing the latest version:
myDash.saveAs(null, null, true, true);
setActiveTab
Syntax
void Dashboard.setActiveTab(string tabName)
Sets a specified tab as the active tab. Only one tab can be active at a time.
Parameter
tabName
String. The name of the tab to set as the active tab.
Example
This example sets the Files tab as the active tab for this dashboard:
myDash.setActiveTab("Files");
setAutoSaveDelay
Syntax
void Dashboard.setAutoSaveDelay(integer seconds)
Sets the amount of time before executing an automatic save for a personal dashboard.
Parameter
seconds
Integer. The number of seconds to delay the automatic save.
Example
This example sets the delay for the automatic save for dashboard myDash to 5 minutes:
myDash.setAutoSaveDelay(300);
setContainer
Syntax
void Dashboard.setContainer(string containerID)
The container that will be used for rendering the dashboard page HTML fragment.
Parameter
containerID
String. The container ID.
Example
This example sets the container where the myDash dashboard object renders:
myDash.setContainer("leftpane");
setDashboardName
Syntax
void Dashboard.setDashboardName(string dashboardName)
Sets the dashboard name to view.
Parameter
dashboardName
String. A fully qualified repository path and file name.
Example
This example sets the path for the myDash dashboard object:
myDash.setDashboardName("/Dashboard/Contents/Hello.DASHBOARD");
setHeight
Syntax
void Dashboard.setHeight(integer height)
Sets the dashboard’s startup height.
Parameter
height
Integer. Specifies the height in pixels.
Example
To set the dashboard height to 400 pixels, use code similar to the following:
myDashboard.setHeight(400);
setService
Syntax
void Dashboard.setService(string iportalURL, actuate.RequestOptions requestOptions)
Sets the web service this dashboard component connects to.
Parameters
iportalURL
String. The URL of the web service to connect to.
requestOptions
actuate.RequestOptions object. Request options, if any, to apply to the connection. See actuate.RequestOptions for details on the options that this parameter can set.
Example
This example connects a dashboard component to the iPortal service and adds a custom URL parameter:
function setDashboardService( ){
myDashboard.setService("http://127.0.0.1:8700/iportal", myRequestOptions.setCustomParameters({myParam: "myValue"});
}
setSize
Syntax
void Dashboard.setSize(integer height, integer width)
Sets the dashboard’s startup size.
Parameters
height
Integer. Height in pixels.
width
Integer. Width in pixels.
Example
To set the dashboard height to 400 pixels and the width to 800 pixels, use code similar to the following:
myDashboard.setSize(400, 800);
setTemplate
Syntax
void Dashboard.setTemplate(string path)
Sets the template path. This function overwrites the template path that is used by iPortal.
Parameter
path
String. Specifies a new template path. Use an iHub volume repository path.
Example
This example sets the template path for myDashboard to /iportal/jsapi/template/path:
myDashboard.setTemplate("/iportal/jsapi/template/path");
setWidth
Syntax
void Dashboard.setWidth(integer width)
Sets the dashboard’s startup width.
Parameter
width
Integer. Specifies the width in pixels.
Example
To set the dashboard width to 800 pixels, use code similar to the following:
myDashboard.setWidth(800);
showTabNavigation
Syntax
void Dashboard.showTabNavigation(boolean show)
Shows the tab toolbar.
Parameter
show
Boolean. The tab toolbar is visible when this parameter is set to true.
Example
To show the tab toolbar for the myDashboard dashboard object, use code similar to the following:
myDashboard.showTabNavigation(true);
submit
Syntax
void Dashboard.submit(function 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.
Parameter
callback
Function. The function to execute after the asynchronous call processing is done.
Example
This example submits the dashboard name that was set with setDashboardName( ):
dash.setDashboardName("/Dashboard/Contents/Hello.DASHBOARD");
dash.submit( );
usePersonalDashboard
Syntax
void Dashboard.usePersonalDashboard(boolean true|false)
Forces the dashboard framework to use the user’s personal dashboard.
Parameter
true|false
Boolean. A value of true sets the dashboard framework to ignore any value set by the setDashboardName( ) method. The dashboard framework creates a new personal dashboard file for the logged in user when no personal dashboard file is present.
Example
To force the use of a personal dashboard for the myDashboard object, use code similar to the following:
myDashboard.usePersonalDashboard(true);