Class actuate.Viewer
Description
The actuate.Viewer class retrieves and displays Actuate BIRT report contents in an HTML container. The actuate.Viewer class displays the report by page. The goto functions of this class change the current position and page displayed in the viewer.
Constructor
Syntax
actuate.Viewer(object viewContainer)
actuate.Viewer(string viewContainerId)
Constructs a new viewer object. The container is an HTML object defined on the HTML page.
Parameters
viewContainer
Object. A document object that references the <div> element that holds the viewer.
viewContainerId
String. The value of the id parameter for the <div> element that holds the viewer.
Example
To assign the viewer to display in a <div id='containerName' /> tag on the page, use the following constructor call:
var myViewer = new actuate.Viewer("containerName");
Function summary
Table 44‑47 lists actuate.Viewer functions.
Table 44‑47 actuate.Viewer functions
Function
Description
Disables Interactive Viewer features
Exports a report using the specified format
Exports data to an external file
Enables Interactive Viewer features
Retrieves a chart by bookmark
Gets the viewer’s height
Gets the viewer’s width
Gets the report content by bookmark
Gets the report content by page range
Gets the margin dimensions of the content in pixels
Returns the report content displayed in the viewer
Returns the current page number
Retrieves a data item by bookmark
Retrieves a Flash object by bookmark
Retrieves a gadget by bookmark
Returns the viewer height setting
Retrieves a label by bookmark
Returns the bookmark of a Reportlet displayed in the viewer
Returns the report file displayed in the viewer
Retrieves a table by bookmark
Retrieves a text element by bookmark
Returns the total number of pages
Gets the UIConfig object assigned to the viewer
Returns the UIOptions object
Returns a viewer object containing the given bookmarked element
Returns the viewer width setting
Goes to the position in the report specified by the bookmark
Goes to the specified page
Returns whether interactive viewing features are enabled
Saves a report design to the repository
Saves a report document to the repository
Sets the viewer content margin
Sets the focus element of the viewer
Sets the viewer height
Sets the parameters to run a report using a list of literal string pairs
Sets the parameters to run a report using a generated object
Sets the report document to render within this Viewer
Sets bookmark name for a Reportlet
Sets the report file to render within this Viewer
Sets the target service URL
Sets the size of the viewer
Sets the Scalable Vector Graphic support flag to enable Scalable Vector Graphics content
Sets UIOptions using a UIOptions object
Sets the dashboard viewing mode
Sets the width of the viewer
Enables the export report dialog window
Enables the download data dialog window
Shows the Facebook comments panel
Shows the parameter panel
Enables the print dialog window
Shows the table of contents panel
submit( )
Submits all the asynchronous operations that the user has requested on this Viewer and renders the viewer component on the page
disableIV
Syntax
void Viewer.disableIV(function callback)
Disables the Interactive Viewer features of this viewer object. This is an asynchronous setting committed by submit( ).
Parameter
callback
Function. The callback function to call after the Interactive Viewer is disabled.
Example
To disable the Interactive Viewer option for myViewer, use code similar to the following:
myViewer.disableIV(function alertUser( ){alert("IV disabled");});
downloadReport
Syntax
void Viewer.downloadReport(string format, string pages, actuate.viewer.RenderOptions renderoption)
Exports the report with a specified format. The downloadReport function does not return any object. The report is exported to the client side. Then the browser opens a download window for the user to specify a location for the report.
Parameters
format
String. The format in which to export the report. Valid values and their corresponding formats are:
*doc: Word
*docx: Word 2007
*html: HTML-encoded web page
*ppt: PowerPoint
*pptx: PowerPoint 2007
*pdf: Adobe PDF
*ps: PostScript
*xls: Excel
*xlsx: Excel 2007
pages
String. The pages to retrieve. Indicate page ranges by using the first page number of the range and the last page number separated by a dash. To use more than one value, separate individual page numbers or page ranges with commas.
renderoption
actuate.viewer.RenderOptions object. Optional. Sets the rendering options for the download, which currently only applies to multisheet xls format reports.
Example
To download the first five pages of the report in the viewer, use the following code:
viewer.downloadReport("pdf", "1-5", null);
downloadResultSet
Syntax
void Viewer.downloadResultSet(actuate.data.Request request, function callback)
Gets all the data from the report as specified by the request. This function makes an AJAX call to the server for the data that is not in the current page. Write a callback function to process the result set. The callback must take an actuate.data.ResultSet object as an argument.
Parameters
request
actuate.data.Request object. The request to generate the result set.
callback
Function. The callback function to call after retrieving the results. The callback function must take an actuate.data.ResultSet object as an argument.
Example
This example creates an actuate.data.ResultSet object from the report in myViewer as specified by myRequest and passes it to a callback function:
myViewer.downloadResultSet(myRequest, callback);
enableIV
Syntax
void Viewer.enableIV(function callback)
Enables interactive viewing features for this Viewer, which enables the selection and modification of report content. This function must be used in the callback of viewer.submit( ) as shown in the following example:
function runInteractive(){
myviewer.setReportName("/Public/BIRT and BIRT Studio Examples
/Sales by Customer.rptdesign");
myviewer.submit(function() {myviewer.enableIV(callback);});
}
Parameter
callback
Function. The callback function to call after enabling the Interactive Viewer features.
Example
This function must be used in the callback of viewer.submit( ) as shown in the following example:
function runInteractive(){
myviewer.setReportName("/Public/BIRT and BIRT Studio Examples
/Sales by Customer.rptdesign");
myviewer.submit(function() {myviewer.enableIV(callback);});
}
getChart
Syntax
actuate.report.Chart Viewer.getChart(string bookmark)
Returns an instance of the chart referenced by a bookmark.
Parameter
bookmark
String. The bookmark name.
Returns
actuate.report.Chart object.
Example
This example returns the chart with the bookmark ChartBookmark:
function getMyChartByBookmark(myReport) {
var bviewer = myReport.getViewer("Chart");
var bpagecontents = bviewer.getCurrentPageContent( );
return bpagecontents.getChart("ChartBookmark");
}
getClientHeight
Syntax
integer Viewer.getClientHeight( )
Gets the browser window’s height.
Returns
Integer. Height in pixels.
Example
To reset the viewer height to 20 pixels less than the browser window if it is larger than the browser window, use code similar to the following:
if(myViewer.getClientHeight( ) < myViewer.getHeight( )){
myViewer.setHeight(myViewer.getClientHeight( ) - 20);
}
getClientWidth
Syntax
integer Viewer.getClientWidth( )
Gets the browser window’s width.
Returns
Integer. Width in pixels.
Example
To reset the viewer width to 20 pixels less than the browser window if it is larger than the browser window, use code similar to the following:
if(myViewer.getClientWidth( ) < myViewer.getWidth( )){
myViewer.setWidth(myViewer.getClientWidth( ) - 20);
}
getContentByBookmark
Syntax
void Viewer.getContentByBookmark(string bookmark, string format, function callback)
Gets the report content by bookmark and passes the content as data to a callback.
Parameters
bookmark
String. The bookmark of a report element to retrieve.
format
String. The output format, which is either html or xhtml.
callback
Function. Callback to be called once the operation is finished. The callback must take actuate.data.ReportContent object as an argument.
Example
To retrieve the content with the bookmark FirstChart as html, use code similar to the following:
myViewer.getContentByBookmark("FirstChart", "html", processChart);
getContentByPageRange
Syntax
void Viewer.getContentByPageRange(string PageRange, string format, function callback)
Gets the report content by page range and passes the content as data to a callback.
Parameters
PageRange
String. Page range to retrieve the report content, separated by a dash.
format
String. The output format, which is either html or xhtml.
callback
Function. Callback to be called once the operation is finished. The callback must take actuate.data.ReportContent object as an argument.
Example
To retrieve the content from pages 3 through 5 as html, use code similar to the following:
myViewer.getContentByPageRange("3-5", "html", processPages);
getContentMargin
Syntax
integer | object Viewer.getContentMargin( )
Gets the viewer content margin.
Returns
Integer or Object. An integer indicates the same margin on all sides, in pixels. The object contains the pixel values for the top, bottom, left, and right margins of the viewer in an array. For example, a 25-pixel top content margin and no margin in the other directions would be the object array {top:25, left:0, right:0, bottom:0}.
Example
To set the margin of the viewer newViewer to match the margin of myViewer, use code similar to the following:
newViewer.setContentMargin(myViewer.getContentMargin( ));
getCurrentPageContent
Syntax
actuate.viewer.Content Viewer.getCurrentPageContent( )
Returns the report content displayed in the viewer. This function is the entry point for retrieving the report elements from this viewer object.
Returns
actuate.viewer.PageContent object.
Example
Use this function to access the bookmarks for specific elements in the page content. For example, to access the table "mytable" on the page loaded in the myViewer viewer object, use the following code:
var element = myViewer.getCurrentPageContent( )
.getTableByBookmark("mytable");
getCurrentPageNum
Syntax
integer Viewer.getCurrentPageNum( )
Returns the page number for the page currently being displayed.
Returns
Integer. The current page number.
Example
This function is useful to move to another page relative to the current page. To go to the next page in a document, use the following code:
viewer.gotoPage(viewer.getCurrentPageNum( ) + 1);
getDataItem
Syntax
actuate.report.DataItem Viewer.getDataItem(string bookmark)
Returns an instance of report data referenced by a bookmark.
Parameter
bookmark
String. The bookmark name.
Returns
actuate.report.DataItem object.
Example
To get the report data with the bookmark FirstDataItem and store it in the variable myDataItem, use code similar to the following:
var myDataItem = myViewer.getDataItem("FirstDataItem");
getFlashObject
Syntax
actuate.report.FlashObject Viewer.getFlashObject(string bookmark)
Returns an instance of the Flash object referenced by a bookmark.
Parameter
bookmark
String. The bookmark name.
Returns
actuate.report.FlashObject object.
Example
To get the Flash object with the bookmark FirstFlashObject and store it in the variable myFlashObject, use code similar to the following:
var myFlashObject = myViewer.getFlashObject("FirstFlashObject");
getGadget
Syntax
actuate.report.Gadget Viewer.getGadget(string bookmark)
Returns an instance of the gadget referenced by a bookmark.
Parameter
bookmark
String. The bookmark name.
Returns
actuate.report.Gadget object.
Example
To get the gadget with the bookmark FirstGadget and store it in the variable myGadget, use code similar to the following:
var myGadget = myViewer.getGadget("FirstGadget");
getHeight
Syntax
string Viewer.getHeight( )
Returns the height value of the viewer.
Returns
String.
Example
This example decreases the viewer’s height by 10:
var height = myViewer.getHeight( );
myViewer.setHeight(height - 10);
getLabel
Syntax
actuate.report.Label Viewer.getLabel(string bookmark)
Returns an instance of the label referenced by a bookmark.
Parameter
bookmark
String. The bookmark name.
Returns
actuate.report.Label object.
Example
To get the label with the bookmark FirstLabel and store it in the variable myLabel, use code similar to the following:
var myLabel = myViewer.getLabel("FirstLabel");
getReportletBookmark
Syntax
string Viewer.getReportletBookmark( )
Returns the bookmark of the current report page or element.
Returns
String. Bookmark.
Example
This example displays the bookmark of the current report page in an alert box:
alert ("Report bookmark is " + myViewer.getReportletBookmark( ));
getReportName
Syntax
string Viewer.getReportName( )
Returns the name of the report file, either a report design file or report document file, that is currently displayed in this Viewer.
Returns
String.
Example
This example displays the currently displayed report file name in an alert box:
alert ("Currently displaying " + myViewer.getReportName( ));
getTable
Syntax
actuate.report.Table Viewer.getTable(string bookmark)
Returns an instance of the table referenced by a bookmark.
Parameter
bookmark
String. The bookmark name.
Returns
actuate.report.Table object.
Example
To get the table with the bookmark FirstTable and store it in the variable myTable, use code similar to the following:
var myTable = myViewer.getTable("FirstTable");
getText
Syntax
actuate.report.Text Viewer.getText(string bookmark)
Returns an instance of the Text object referenced by a bookmark.
Parameter
bookmark
String. The bookmark name.
Returns
actuate.report.Text object.
Example
To get the Text object with the bookmark Title and store it in the variable myText, use code similar to the following:
var myText = myViewer.getText("Title");
getTotalPageCount
Syntax
integer Viewer.getTotalPageCount( )
Returns the total number of pages in the report being viewed.
Returns
Integer.
Example
This function is useful to move to the last page of a document. To go to the last page in a document, use the following code:
viewer.gotoPage(viewer.getTotalPageCount( ));
getUIConfig
Syntax
actuate.viewer.UIConfig Viewer.getUIConfig( )
Returns the current UI configuration.
Returns
actuate.viewer.UIConfig object. This function returns null when no UIConfig object is set.
Example
To retrieve and store the content pane from the viewer, use the following code:
var contentpane = viewer.getUIConfig( ).getContentPane( );
getUIOptions
Syntax
actuate.viewer.UIOptions Viewer.getUIOptions( )
Returns the UIOptions set in this viewer object.
Returns
actuate.viewer.UIOptions object. This function returns null when no UIOptions object is set.
Example
To retrieve and store the uiOptions for the viewer, use the following code:
var options = myViewer.getUIOptions( );
getViewer
Syntax
actuate.Viewer Viewer.getViewer(string bookmark)
actuate.Viewer Viewer.getViewer(object elementID)
Returns a viewer object containing the report element that is associated with a bookmark or contained in an HTML element.
Parameters
bookmark
String. The bookmark of the report element to view.
elementID
Object. An HTML element that contains the viewer.
Returns
actuate.Viewer object or null if the viewer is not found.
Example
This example uses getViewer( ) to retrieve a report element and return the bookmark of the chart in that report:
function chartBookmark(myReport){
var bviewer = myReport.getViewer("Chart");
var bpagecontents = bviewer.getCurrentPageContent( );
return bpagecontents.getChartByBookmark("ChartBookmark");
}
getWidth
Syntax
string Viewer.getWidth( )
Returns the width value of the viewer.
Returns
String.
Example
This example decreases the viewer’s width by 10:
var width = myViewer.getWidth( );
myViewer.setWidth(width - 10);
gotoBookmark
Syntax
void Viewer.gotoBookmark(string bookmark)
Goes to the page position by the specified bookmark. The viewer displays to the first page when the bookmark is not found.
Parameter
bookmark
String. The bookmark of a report element.
Example
To move the viewer to the page position specified by the value of the 'bookmark' parameter, use this code:
viewer.gotoBookmark(document.getElementById('bookmark').value);
gotoPage
Syntax
void Viewer.gotoPage(integer pageNumber)
Goes to the specified page. The viewer throws an exception when the page is not found.
Parameter
pageNumber
Integer. A page number in the report.
Example
To go to the first page of a report, use the following code:
viewer.gotoPage(1);
isInteractive
Syntax
boolean Viewer.isInteractive( )
Returns the interactive viewing status of the viewer. Enables or disables the interactive viewing features with actuate.Viewer.enableIV( ).
Returns
Boolean. True when interactive viewing features are enabled.
Example
This example displays an alert box with the interactive status of the viewer:
alert("Interactivity of this viewer is set to " + myViewer.isInteractive( ));
saveReportDesign
Syntax
void Viewer.saveReportDesign(string filename, function callback)
Saves the current viewer content as a report design. The viewer must enable interactive viewing with enableIV( ) prior to saving a report design.
Parameters
filename
String. Sets the name of the saved file. The current file name is used if null. The file name must be a path relative to the viewer’s repository.
callback
Function. Optional. The function to execute after the asynchronous call processing is done. The callback takes the current actuate.Viewer object as an input parameter.
Example
To save the content of the viewer as the report design called NewDesign, use the following code:
myViewer.saveReportDesign("NewDesign");
saveReportDocument
Syntax
void Viewer.saveReportDocument(string filename, function callback)
Saves the current viewer content as a report document. The viewer must enable interactive viewing with enableIV( ) prior to saving a report design.
Parameters
filename
String. Sets the name of the saved file. The current file name is used if null. The file name must be a path relative to the viewer’s repository.
callback
Function. Optional. The function to execute after the asynchronous call processing is done. The callback takes the current actuate.Viewer object as an input parameter.
Example
To save the content of the viewer as the report document called NewDocument, use the following code:
myViewer.saveReportDocument("NewDocument");
setContentMargin
Syntax
void Viewer.setContentMargin(string[ ] margin)
void Viewer.setContentMargin(int margin)
Sets the viewer content margin.
Parameter
margin
Array of strings or integer. Each member of the array is the margin for the top, left, right, and bottom internal margins for the viewer. An integer sets all margins to that value.
Example
To set the internal margin of the viewer to a 10‑pixel buffer, use the following code:
myViewer.setContentMargin(10);
setFocus
Syntax
void setFocus(boolean focus)
Sets the focus for the viewer.
Parameter
focus
Boolean. The viewer’s context menu is in focus when this parameter is set to true.
Example
This example blurs the context menu for the viewer:
viewer.setFocus(false);
setHeight
Syntax
void Viewer.setHeight(integer height)
Sets the viewer height.
Parameter
height
Integer. The height in pixels.
Example
To set the height of the viewer to 600 pixels, use the following code:
viewer.setHeight(600);
setParameters
Syntax
void Viewer.setParameters(string[ ] params)
Sets parameters for executing report using literal string pairs.
Parameter
params
Array of strings. Each string in the array is constructed of name:"value" pairs. Use a literal list, such as {param1:"value1", param2:"value2", … }.
Example
To set the value of a parameter, city, to the value, New York, use the following object literal:
viewer.setParameters({ city:"New York"});
setParameterValues
Syntax
void Viewer.setParameterValues(actuate.parameter.ParameterValue[ ] parameters)
Sets parameter values for executing a report using ParameterValue objects.
Parameter
parameters
Array of actuate.parameter.ParameterValue objects. An array of this kind is returned by actuate.Parameter.downloadParameterValues( ) and is the recommended function for creating the parameters input.
Example
To set the parameter values for a report to the parameters in the pvs array, use this code:
viewer.setParameterValues(pvs);
setReportDocument
Syntax
void Viewer.setReportName(string reportFile, string connectionHandle)
Sets the report document to render in this Viewer.
Parameters
reportFile
String. The report file path for a report document file. To set the version for the report, add a semicolon and the version number. For example, “/Public/BIRT and BIRT Studio Examples/Customer Dashboard.rptdocument;1” retrieves version 1 of Customer Dashboard.rptdocument.
connectionHandle
String. Optional. The unique identifier generated by iHub for a temporary report.
Example
To open the Top 5 Sales Performers report, set the report by name and then call submit( ), as shown in the following example:
viewer.setReportDocument("/Public/BIRT and BIRT Studio Examples
/Top 5 Sales Performers.rptdocument");
viewer.submit( );
setReportletBookmark
Syntax
void Viewer.setReportletBookmark(string bookmark)
Sets the bookmark for the Reportlet rendered.
Parameter
bookmark
String. The bookmark ID used to render the Reportlet. Viewer requires a bookmark to render a Reportlet. Viewer does not support automatically generated generic bookmarks from a BIRT report.
Example
To open the Top 5 Customers Reportlet of the Customer Dashboard, set the Reportlet bookmark by name and then call viewer.submit, as shown in the following example:
viewer.setReportName("/Public/BIRT and BIRT Studio Examples
/Customer Dashboard.rptdocument");
viewer.setReportletBookmark("Top 5 Customers");
viewer.submit( );
setReportName
Syntax
void Viewer.setReportName(string reportFile)
Sets the report file, either a report design or report document, to render in this Viewer.
Parameter
reportFile
String. The report file path for a report design file or report document file. To set the version for the report, add a semicolon and the version number. For example, “/Public/BIRT and BIRT Studio Examples/Customer Dashboard.rptdesign;1” retrieves version 1 of Customer Dashboard.rptdesign.
Example
To open the Top 5 Sales Performers report, set the report by name and then call submit( ), as shown in the following example:
viewer.setReportName("/Public/BIRT and BIRT Studio Examples
/Top 5 Sales Performers.rptdesign");
viewer.submit( );
setService
Syntax
void Viewer.setService(string iPortalURL, actuate.RequestOptions requestOptions)
Sets the target service URL to which this Viewer links. When the service URL is not set, this Viewer links to the default service URL, which is set on the actuate object.
Parameters
iPortalURL
String. The target Actuate web application URL, either a Java Component or iPortal.
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:
myViewer.setService("http://127.0.0.1:8700/iportal",
myRequestOptions);
setSize
Syntax
void Viewer.setSize(integer width, integer height)
Resizes the viewer’s width and height.
Parameters
width
Integer. The new width is specified in pixels.
height
Integer. The new height is specified in pixels.
Example
To set the viewer’s size to 300 pixels by 300 pixels, use code similar to the following:
myViewer.setSize(300, 300);
setSupportSVG
Syntax
void Viewer.setSupportSVG(boolean usvgFlag)
Controls Scalable Vector Graphics support for the viewer.
Parameter
svgFlag
Boolean. True enables Scalable Vector Graphic support.
Example
To disable Scalable Vector Graphic support for the myViewer viewer, use code similar to the following:
myViewer.setSupportSVG(false);
setUIOptions
Syntax
void Viewer.setUIOptions(actuate.viewer.UIOptions options)
Sets the UI options for the viewer using an actuate.viewer.UIOptions object.
Parameter
options
actuate.viewer.UIOptions object. Enables or disables various controls and features.
Example
To hide the toolbar for the viewer, use the following code:
uioptions.enableToolBar(false);
viewer.setUIOptions(uioptions);
viewer.submit( );
setViewingMode
Syntax
void Viewer.setViewingMode(string viewer)
Sets the dashboard viewing mode.
Parameter
viewer
actuate.Constant.ViewingMode constant. Legal values are NON_DASHBOARD, DASHBOARD_NORMAL, and DASHBOARD_MAX.
Example
To display content without dashboard features, use the following code:
viewer.setViewingMode(actuate.Constant.ViewingMode.NON_DASHBOARD);
setWidth
Syntax
void Viewer.setWidth(string width)
Sets the viewer width.
Parameter
width
String.
Example
To set the width of the viewer to 800 pixels, use the following code:
viewer.setWidth(800);
showDownloadReportDialog
Syntax
void Viewer.showDownloadReportDialog( )
Displays the export report dialog window.
Example
Use this code to display the report dialog window:
myViewer.showDownloadReportDialog( );
showDownloadResultSetDialog
Syntax
void Viewer.showDownloadResultSetDialog( )
Displays the export data dialog window.
Example
Use this code to display the result set download dialog window:
viewer.showDownloadResultSetDialog( );
showFacebookCommentPanel
Syntax
void Viewer.showFacebookCommentPanel( )
Displays the Facebook comments panel.
Example
Use this code to display the Facebook comments panel:
viewer.showFacebookCommentPanel( );
showParameterPanel
Syntax
void Viewer.showParameterPanel( )
Displays the parameter panel.
Example
Use this code to display the parameter panel:
viewer.showParameterPanel( );
showPrintDialog
Syntax
void Viewer.showPrintDialog( )
Displays the print dialog window.
Example
Use this code to display the print dialog window:
viewer.showPrintDialog( );
showTocPanel
Syntax
void Viewer.showTocPanel( )
Displays the table of contents panel.
Example
Use this code to display the table of contents panel:
viewer.showTocPanel( );
submit
Syntax
void Viewer.submit(function callback, boolean rerun)
Updates and reloads the viewer after submitting requests for the viewer. The submit( ) function triggers an AJAX request for all asynchronous operations. When the server finishes the processing, it returns a response and the results are rendered on the page in the viewer container. Calling submit( ) when a previous submit( ) is pending throws an exception.
Parameters
callback
Function. Optional. The function to execute after the asynchronous call processing is done.
rerun
Boolean. Optional. Indicates whether to re-run the report design when refreshing. Default to true.
Example
To open the Top 5 Sales Performers report, set the report by name and then call submit( ), as shown in the following example:
viewer.setReportName("/Public/BIRT and BIRT Studio Examples
/Top 5 Sales Performers.rptdesign");
viewer.submit( );