Class actuate
Description
The entry point to the Actuate JavaScript API library. The actuate class uses load( ) to generate viewer and parameter components. The actuate class uses initialize( ) and authenticate( ) to connect to an Actuate web application service.
Use actuate.load( ) before calling actuate.initialize( ). The actuate.initialize( ) function loads all of the components added with load( ).
The initialize( ) function connects to an initial Actuate web application service. To connect to additional services simultaneously, use authenticate( ). Call initialize( ) before calling authenticate( ).
Constructor
The static actuate class loads when a <script> element loads the Actuate JavaScript API.
Function summary
Table 11‑2 lists actuate functions.
Table 11‑2 actuate functions
Function | Description |
authenticate( ) | Connects to an Actuate web application service |
getDefaultIportalUrl( ) | Returns the default service URL |
getDefaultRequestOptions( ) | Returns the default request options |
getViewer( ) | Returns a viewer instance containing the given bookmark element |
initialize( ) | Connects to an initial Actuate web application service, imports library components, and invokes a callback function |
isConnected( ) | Reports whether a given Actuate web application is connected |
isInitialized( ) | Returns whether a library is initialized |
load( ) | Loads the library for an additional component |
logout( ) | Logs a user out of an Actuate web application service |
actuate.authenticate
Syntax
void authenticate(string iPortalURL, actuate.RequestOptions requestOptions, reserved, reserved, function callback, string credentials, function errorCallback)
Connects to the Actuate web application service that is addressed by iPortalURL and authenticates the connection.
Parameters
iPortalURL
The iPortalURL parameter is a required string parameter that specifies the target Actuate web application URL.
requestOptions
The requestOptions parameter is an optional
actuate.RequestOptions object. The requestOptions parameter defines the URL parameters to send with the connection request. Functions in the RequestOptions class enable the addition of custom parameters to the URL. When requestOptions is null, authenticate( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in the Actuate web application’s web.xml file.
reserved
Set to null.
reserved
Set to null.
credentials
The credentials parameter is an optional string parameter. This parameter holds information that supports checking user credentials with an externalized system such as LDAP. The credentials parameter supports additional credential information for any additional security systems in place on the application server where the web service is deployed.
callback
The callback parameter is an optional function to call after authentication. The actuate.authenticate( ) function passes the following variables to the callback function, if applicable:
iportalURL: The web service URL passed in from the iPortalURL parameter
userid: The authenticated user ID, if one is set
errorCallback
The errorCallback parameter is an optional function that specifies a function to call when an error occurs. The possible errors are actuate.ConnectionException, actuate.AuthenticationException, and actuate.Exception. The callback function must take an exception as an argument.
Example
To connect to an additional Actuate web service called digits, use code similar to the following:
actuate.authenticate("http://digits:8080/webapp", null, null, null, null, null, null);
actuate.getDefaultIportalUrl
Syntax
String getDefaultIportalUrl( )
Returns the default service URL.
Returns
String. The default service URL.
Example
This example calls actuate.getDefaultIportalUrl( ) to return the default service URL:
alert ("The default service URL is " + actuate.getDefaultIportalUrl( ));
actuate.getDefaultRequestOptions
Syntax
Returns the default request options.
Returns
actuate.RequestOptions object that contains the default request options.
actuate.getViewer
Syntax
actuate.Viewer getViewer(string bookmark)
actuate.Viewer getViewer(htmlelement viewer)
Returns a viewer instance containing the given bookmark element. Load the viewer module before calling actuate.getViewer( ).
Parameters
bookmark
This string parameter contains the name of the bookmark to retrieve or the name of an HTML <div> element.
viewer
This parameter is the DOM htmlelement object for the HTML <div> element that contains a viewer.
Returns
An actuate.Viewer object that contains a viewer. When actuate.getViewer( ) does not find a viewer, the function returns null.
Example
To retrieve the viewer assigned to the first_viewer <div> element on the page, use code similar to the following:
currentViewer = actuate.getViewer("first_viewer");
actuate.initialize
Syntax
void initialize(string iPortalURL, actuate.RequestOptions requestOptions, reserved, reserved, function callback, function errorCallback)
Connects to an initial Actuate web application service, loads all of the components added with load( ), and invokes a callback function. Authentication is optional in initialize( ).
When using more than one service in one mashup page, use
actuate.authenticate( ) to connect to additional services.
Parameters
iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send in the connection request. It can also add custom parameters to the URL. If requestOptions is null, initialize( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in Actuate web application’s web.xml file. reserved
Set to null.
reserved
Set to null.
callback
Function. The callback function called after the initialization is done. The following variables are passed to the callback function:
iportalUrl: The web service URL passed in from the iPortalURL parameter
errorCallback
Function. The function to call when an error occurs. The possible errors are actuate.ConnectionException, actuate.AuthenticationException, and actuate.Exception. errorCallback must take an exception as an argument.
Example
To initialize the client connection to a web service on myhost, set the default request options, and then run the init( ) function, use the following code:
var roptions = actuate.getDefaultRequestOptions( );
actuate.initialize("http://myhost:8700/webapp", rpotions, null, null, init, null);
actuate.isConnected
Syntax
boolean isConnected(string iportalUrl, actuate.RequestOptions requestOptions)
Returns whether a given Actuate web application URL is connected.
Parameters
iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send in the connection test. It can also add custom parameters to the URL. If requestOptions is null, isConnected( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in Actuate web application’s web.xml file. Returns
Boolean. True if there is a connection to the given Actuate web application, False if there is no connection or if it is pending.
Example
The following sample code connects to the digits service using authenticate if not currently connected:
if (!actuate.isConnected("http://digits:8700/iportal", null)){
actuate.authenticate("http://digits:8700/iportal", null, null, null, null, null, null);
}
actuate.isInitialized
Syntax
boolean isInitialized( )
Returns whether the library is already initialized.
Returns
Boolean. True if the library is already initialized.
Example
The following sample code initializes a connection with the Actuate web service if one is not already initialized:
if (!actuate.isInitialized( )){
actuate.initialize("http://myhost:8700/iportal", null, null, null, init, null);
}
actuate.load
Syntax
void load(string componentName)
Specifies a component to be loaded by actuate.initialize( ). The available components are:
parameter: The parameter page component including the
actuate.Parameter class and subclasses
viewer: The viewer component including the
actuate.Viewer class and subclasses
Parameter
componentName
String. componentName is a case-sensitive parameter. Valid component names are listed above.
Example
To enable a page to use both a viewer and parameters, call actuate.load( ) twice, as shown in the following code:
actuate.load("viewer");
actuate.load("parameter");
actuate.logout
Syntax
void logout(string iPortalURL, actuate.RequestOptions requestOptions, function callback, function errorCallback)
Logs out from the given Actuate web application URL and removes authentication information from the session. If the application was previously not logged in to this Actuate web application, it generates no errors but still calls the callback function.
Parameters
iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send with the logout request. It can also add custom parameters to the URL. If requestOptions is null, logout( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in the Actuate web application’s web.xml file. callback
Function. Optional. The callback function called after the logout is done.
errorCallback
Function. The function called when an error occurs. The possible errors are actuate.ConnectionException, actuate.AuthenticationException, and actuate.Exception. errorCallback must take an exception as an argument.
Example
The following sample code disconnects from the digits service if currently connected:
if (actuate.isConnected("http://digits:8700/iportal", null)){
actuate.logout("http://digits:8700/iportal", null, null, null);
}