Class actuate.Parameter
Description
The actuate.Parameter class retrieves and displays Actuate BIRT report parameters in an HTML container. Users can interact with the parameters on the page and pass parameter values to an actuate.Viewer object, but not to the server directly.
The actuate.Parameter class displays the parameters by page. The actuate.parameters.navigate( ) function changes the page display or changes the current position on the page.
Constructor
Syntax
actuate.Parameter(string container)
Constructs a parameter object for a page, initializing the parameter component.
Parameter
container
String. The name of the HTML element that displays the rendered parameter component or a container object. The constructor initializes the parameter component but does not render it.
Function summary
Table 44‑18 lists actuate.Parameter functions.
Table 44‑18 actuate.Parameter functions
Function
Description
Returns an array of ParameterDefinition objects
Returns an array list of ParameterValue objects
Returns the parameter layout
Returns the names of the groups of parameters
Returns the name of the report file
Returns the name of the transient document
Hides the navigation bar
Hides report parameters by group
Hides parameters by name
Navigates the parameter page
Unloads unused JavaScript variables
Registers an event handler
Removes an event handler
Renders the parameter content to the container
Sets the auto suggest delay time
Sets the fetch size of the auto suggestion list
Sets the size of the auto suggestion list
Sets the groups to expand by default
Sets the font of the parameter page
Sets the HTML container for the group
Sets the parameter layout type
Sets the parameter UI to read‑only
Sets the remote report path and name
Sets the Actuate web application service
Sets the parameter page to display localized content
submit( )
Submits all the asynchronous operations that the user has requested on this Parameter object and renders the parameter component on the page
downloadParameters
Syntax
void Parameter.downloadParameters(function callback)
Retrieves an array of actuate.parameter.ParameterDefinition objects that contain the report parameters for the report and sends the array to the callback function, which must take the array as an input parameter.
Parameter
callback
Function. The function to execute after the report parameters finish downloading. Parameter.downloadParameters( ) sends an array of actuate.parameter.ParameterDefinition objects to the callback function as an input argument.
Example
This example retrieves a set of report parameters and sends them to a callback function.
function getChartParams(myParameter){
myParameter.downloadParameters(callback( ));
}
downloadParameterValues
Syntax
void Parameter.downloadParameterValues(function callback)
Returns an array of the actuate.parameter.ParameterValue objects for the parameter object. If no values have been set, the parameter object downloads the default values from the server.
Parameter
callback
Function. The function to execute after the report parameters finish downloading. Parameter.downloadParameterValues( ) sends an array of actuate.parameter.ParameterValue objects to the callback function as an input argument.
Example
To download the parameter values and add them to the viewer, the callback function must use the values as an input parameter, as shown in the following code:
paramObj.downloadParameterValues(runNext);
function runNext(values){
viewer.setParameterValues(values);
}
getLayout
Syntax
string Parameter.getLayout( )
Returns the parameter layout type.
Returns
String. The parameter layout, which will match one of the layout constants in actuate.parameter.Constants:
*actuate.parameter.Constants.LAYOUT_NONE
*actuate.parameter.Constants.LAYOUT_GROUP
*actuate.parameter.Constants.LAYOUT_COLLAPSIBLE
Example
This example calls getLayout( ) to display the parameter layout type in an alert box:
alert(paramObj.getLayout( ));
getParameterGroupNames
Syntax
string[ ] Parameter.getParameterGroupNames( )
Returns all the group names for the parameter page as an array of strings.
Returns
Array of strings. Each string is a group name.
Example
This example displays an alert box with the name of the first group for the parameter page:
var groupNames = paramObj.getParameterGroupNames( );
alert("First Group Name: " + groupNames[0]);
getReportName
Syntax
string Parameter.getReportName( )
Returns the name of the report file currently referenced by this Parameter object.
Returns
String. The report file name.
Example
This example displays an alert box with the name of the report file:
alert("Report file: " + paramObj.getReportName( ));
getTransientDocumentName
Syntax
string Parameter.getTransientDocumentName( )
Returns the name of the transient document generated by running the report currently referenced by this Parameter object.
Returns
String.
Example
This example displays an alert box with the name of the transient document:
alert("Transient document: " + paramObj.getTransientDocumentName
( ));
hideNavBar
Syntax
void Parameter.hideNavBar( )
Hides the navigation bar for the parameter component in the LAYOUT_GROUP layout.
Example
This example hides the navigation bar:
paramObj.hideNavBar( );
alert("Navigation bar is hidden");
hideParameterGroup
Syntax
void Parameter.hideParameterGroup(string[ ] groupNames)
Hides all report parameters that belongs to a group or to a list of groups.
Parameter
groupNames
String or array of strings. Hides any groups listed.
Example
This example hides the report parameters that belong to the groups that are listed in the myGroups string array:
var myGroups = ["Group1", "Group2", "Group3"];
paramObj.hideParameterGroup(myGroups);
alert("Groups are hidden");
hideParameterName
Syntax
void Parameter.hideParameterName(string[ ] parameterNames)
Hides report parameters as specified by name.
Parameter
parameterNames
String or array of strings.
Example
This example hides the parameters that are listed in the myParams string array:
var myParams = ["Parameter1", "Parameter2", "Parameter3"];
paramObj.hideParameterName(myParams);
alert("Parameters are hidden");
navigate
Syntax
void Parameter.navigate(string containerId, string navTarget)
Changes the current page of the parameter component. The navTarget determines the new location to display the parameter container.
Parameters
containerId
String. The value of the id parameter for the HTML <div> element that holds the parameter component.
navTarget
String constant. Which navigation button to trigger. Possible values from actuate.parameter.Constants are NAV_FIRST, NAV_PREV, NAV_NEXT, NAV_LAST.
Example
This example displays the last page of the parameter component in the HTML <div> element with the myParams ID:
function myParamsLast(myParameter){
myParameter.navigate("myParams", NAV_LAST);
}
onUnload
Syntax
void Parameter.onUnload( )
Performs garbage collection for the parameter object and unloads JavaScript variables that are no longer needed by Parameter.
Example
This example unloads JavaScript variables and displays an alert box:
myParameter.onUnload();
alert("JS variables unloaded.");
registerEventHandler
Syntax
void Parameter.registerEventHandler(actuate.parameter.EventConstants event, function handler)
Registers an event handler to activate for parameter events. This function can assign several handlers to a single event.
Parameters
event
actuate.parameter.EventConstants. A constant corresponding to a supported event. actuate.Parameter supports the following two events:
*actuate.parameter.EventConstants.ON_CHANGED
*actuate.parameter.EventConstants.ON_SELECTION_CHANGED
handler
Function. The function to execute when the event occurs. The handler must take two arguments: the parameter instance that fired the event and an event object specific to the event type.
Example
To register an event handler to catch exceptions, call actuate.Parameter.registerEventHandler using the ON_CHANGED constant after creating the viewer object, as shown in the following example:
function initParameter( ){
parameter = new actuate.Parameter("acparameter");
parameter.registerEventHandler(actuate.parameter.EventConstants
.ON_CHANGED, errorHandler);
}
removeEventHandler
Syntax
void Parameter.removeEventHandler(actuate.viewer.EventConstants event, function handler)
Removes an event handler.
Parameters
event
actuate.parameter.EventConstants. A constant corresponding to a supported event. actuate.Parameter supports the following two events:
*actuate.parameter.EventConstants.ON_CHANGED
*actuate.parameter.EventConstants.ON_SELECTION_CHANGED
handler
Function. A handler function registered for the event.
Example
To remove an event handler, call actuate.Parameter.removeEventHandler with a legal event constant, as shown in the following example:
function cleanupParameter( ){
parameter.removeEventHandler(actuate.parameter.EventConstants
.ON_CHANGED, errorHandler);
}
renderContent
Syntax
void Parameter.renderContent(actuate.parameter.ParameterDefinition[ ] paramDefs, function callback)
Renders the parameter component to the container.
Parameters
paramDefs
Array of actuate.parameter.ParameterDefinition objects.
callback
Function. The function to execute after the rendering is done.
Example
This example calls renderContent( ) after hiding parameter groups:
function showNoGroups(myParameter){
myParameter.hideParameterGroup(zipcodes);
myParameter.renderContent(myParameterArray,
cleanupParameter(myParameter));
}
setAutoSuggestDelay
Syntax
void Parameter.setAutoSuggestDelay(long delay)
Sets the auto suggest delay time.
Parameter
delay
Long. Interpreted as milliseconds.
Example
This example implements a custom auto suggest list. The list is 10 suggestions long and displays 3 suggestions at a time after a delay of 250 milliseconds.
function myCustomAutoSuggest(myParameter){
myParameter.setAutoSuggestFetchSize(10);
myParameter.setAutoSuggestListSize(3);
myParameter.setAutoSuggestDelay(250);
}
setAutoSuggestFetchSize
Syntax
void Parameter.setAutoSuggestFetchSize(integer size)
Sets the fetch size of the auto suggestion list. AutoSuggest fetches all suggestions from the server when the fetch size is not set.
Parameter
size
Integer. The number of suggestions to fetch at a time.
Example
This example implements a custom auto suggest list. The list is 10 suggestions long and displays 3 suggestions at a time after a delay of 250 milliseconds.
function myCustomAutoSuggest(myParameter){
myParameter.setAutoSuggestFetchSize(10);
myParameter.setAutoSuggestListSize(3);
myParameter.setAutoSuggestDelay(250);
}
setAutoSuggestListSize
Syntax
void Parameter.setAutoSuggestListSize(integer size)
Sets the length of the auto suggestion list. AutoSuggest shows all of the suggestions from the server when the list length is not set.
Parameter
size
Integer. The number of suggestions to display.
Example
This example implements a custom auto suggest list. The list is 10 suggestions long and displays 3 suggestions at a time after a delay of 250 milliseconds.
function myCustomAutoSuggest(myParameter){
myParameter.setAutoSuggestFetchSize(10);
myParameter.setAutoSuggestListSize(3);
myParameter.setAutoSuggestDelay(250);
}
setExpandedGroups
Syntax
void Parameter.setExpandedGroups(groupNames)
Defines a set of groups that are expanded by default.
Parameter
groupNames
Array of strings. The group names to expand by default.
Example
This example sets the "Motorcycles", "Trucks", and "Airplanes" groups as expanded by default:
var myGroups = new Array["Motorcycles", "Trucks", "Airplanes"];
paramObj.setExpandedGroups(myGroups);
setFont
Syntax
void Parameter.setFont(string fontStyleString)
Sets the font of the parameter page content after the page is rendered.
Parameter
fontStyleString
String. The name of a font.
Example
This example sets the font to Arial for the parameters page:
paramObj.setFont("arial");
setGroupContainer
Syntax
void Parameter.setGroupContainer(string[ ] groupNames, string containerId)
Sets the HTML element container for the provided group. All parameter objects listed in groupNames are assigned to the container.
Parameters
groupNames
Array of strings. The group names to be assigned.
containerID
String. The name of the HTML element that displays the group of rendered parameter components.
Example
This example assigns the group names in the myGroups string array to the leftpane HTML element:
var myGroups = ["Group1", "Group2", "Group3"];
paramObj.setGroupContainer(myGroups, "leftpane");
setLayout
Syntax
void Parameter.setLayout(string layoutName)
Sets the parameter layout.
Parameter
layoutName
String constant. Possible values are:
*actuate.parameter.Constants.LAYOUT_GROUP
*actuate.parameter.Constants.LAYOUT_NONE
*actuate.parameter.Constants.LAYOUT_COLLAPSIBLE
Example
This example sets the parameter object’s layout type to LAYOUT_COLLAPSIBLE:
paramObj.setLayout("LAYOUT_COLLAPSIBLE");
setReadOnly
Syntax
void Parameter.setReadOnly(boolean readOnly)
Sets the parameters to read-only.
Parameter
readOnly
Boolean. True indicates that the parameters are read-only.
Example
This example makes the parameters read-only:
paramObj.setReadOnly(true);
setReportName
Syntax
void Parameter.setReportName(string reportFile)
Sets the report file from which to get report parameters.
Parameter
reportFile
String. The report file path and name. The report file can be a report design file or a report document file.
Example
To set the name using an HTML input tag with an ID of Selector, use the following code:
myViewer.setReportName(document.getElementById("Selector").value);
setService
Syntax
void Parameter.setService(string iPortalURL, actuate.RequestOptions requestOptions)
Sets the target service URL to which the Parameter object links. If the service URL is not set, this Parameter object links to the default service URL set on the actuate object.
Parameters
iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send with the authentication request, such as the iHub URL, volume, or repository type. The URL can also include custom parameters.
Example
This example sets the URL for the Actuate iPortal web application service:
paramObj.setService("http://127.0.0.1:8700
/iportal",myRequestOptions);
setShowDisplayType
Syntax
void Parameter.setShowDisplayType(boolean showDisplayType)
Sets whether localized data is shown or not.
Parameter
showDisplayType
Boolean. True indicates that localized data is shown.
Example
This example hides localized data:
paramObj.setShowDisplayType(false);
paramObj.submit(alert("Localized data hidden.");
submit
Syntax
void Parameter.submit(function callback)
Submits requests to the server for the report parameters. When this function is called, an AJAX request is triggered to submit all the operations. When the server finishes the processing, it returns a response and the results are rendered on the page in the parameter container.
Parameter
callback
Function. The function to execute after the asynchronous call processing is done.
Example
This example calls submit( ) after hiding localized data:
paramObj.setShowDisplayType(false);
paramObj.submit(alert("Localized data hidden."));