Class actuate.Viewer

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 11‑11 lists actuate.Viewer functions.

Table 11‑11 actuate.Viewer functions
Function	Description
downloadReport( )	Exports a report using the specified format
getClientHeight( )	Gets the viewer’s height
getClientWidth( )	Gets the viewer’s width
getContentMargin( )	Gets the margin dimensions of the content in pixels
getCurrentPageNum( )	Returns the current page number
getHeight( )	Returns the viewer height setting
getHelpBase( )	Gets the help URL
getId( )	Returns the ID of this object
getIportalUrl( )	Returns the Actuate web application URL that this Viewer accesses
getReportletBookmark( )	Returns the bookmark of a Reportlet displayed in the viewer
getReportName( )	Returns the report file displayed in the viewer
getRequestOptions( )	Returns the viewer’s request options
getTotalPageCount( )	Returns the total number of pages
getViewer( )	Returns a viewer object containing the given bookmarked element
getWidth( )	Returns the viewer width setting
gotoBookmark( )	Goes to the position in the report specified by the bookmark
gotoPage( )	Goes to the specified page
setContentMargin( )	Sets the viewer content margin
setHeight( )	Sets the viewer height
setHelpBase( )	Sets the base help URL
setParameters( )	Sets the parameters to run a report using a list of literal string pairs
setParameterValues( )	Sets the parameters to run a report using a generated object
setReportName( )	Sets the report file to render within this Viewer
setService( )	Sets the target service URL
setSize( )	Sets the size of the viewer
setWidth( )	Sets the width of the viewer
showDownloadReportDialog( )	Enables the export report dialog window
showFacebookCommentPanel( )	Shows the Facebook comments panel.
showParameterPanel( )	Shows the parameter panel
showPrintDialog( )	Enables the print dialog window
submit( )	Submits all the asynchronous operations that the user has requested on this Viewer and renders the viewer component on the page

actuate.Viewer.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

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);

actuate.Viewer.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);

}

actuate.Viewer.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);

}

actuate.Viewer.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( ));

actuate.Viewer.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);

actuate.Viewer.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);

actuate.Viewer.getHelpBase

Syntax

string Viewer.getHelpBase( )

Returns the URL of the help base. The help base is the base URL for the product help documentation.

Returns

String. The base URL of the help documentation.

Example

This example displays the help base URL in an alert box:

alert("The help base URL is " + myViewer.getHelpBase( ))

actuate.Viewer.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( ));

actuate.Viewer.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( ));

actuate.Viewer.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( ));

actuate.Viewer.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");

}

actuate.Viewer.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);

actuate.Viewer.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);

actuate.Viewer.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);

actuate.Viewer.setContentMarg

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. A single 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);

actuate.Viewer.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);

actuate.Viewer.setHelpBase

Syntax

void Viewer.setHelpBase(string helpBase)

Sets the URL of the help base. The help base is the base URL for the product help documentation.

Parameter

helpBase

String. The URL where the help documentation is located.

Example

This example sets the help base URL to http://www.actuate.com/documentation/R11:

myViewer.setHelpBase("http://www.actuate.com/documentation/R11");

myViewer.submit( );

actuate.Viewer.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"});

actuate.Viewer.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);

actuate.Viewer.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/Customer Dashboard.rptdocument");

viewer.setReportletBookmark("Top 5 Customers");

viewer.submit( );

actuate.Viewer.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.

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/Top 5 Sales Performers.rptdesign");

viewer.submit( );

actuate.Viewer.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.

Parameter

iPortalURL

String. The target Actuate web application URL.

requestOptions

actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send with the authentication request. The URL can also include custom parameters.

Example

This example sets the URL for the Actuate web application service:

myViewer.setService("http://localhost:8700/iportal", myRequestOptions);

actuate.Viewer.setSize

Syntax

void Viewer.setSize(integer width, integer height)

Resizes the viewer’s width and height.

Parameter

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);

actuate.Viewer.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);

actuate.Viewer.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);

actuate.Viewer.showDownloadReportDialog

Syntax

void Viewer.showDownloadReportDialog( )

Displays the export report dialog window.

Example

Use this code to display the report dialog window:

myViewer.showDownloadReportDialog( );

actuate.Viewer.showFacebookCommentPanel

Syntax

void Viewer.showFacebookCommentPanel( )

Displays the Facebook comments panel.

Example

Use this code to display the Facebook comments panel:

viewer.showFacebookCommentPanel( );

actuate.Viewer.showParameterPanel

Syntax

void Viewer.showParameterPanel( )

Displays the parameter panel.

Example

Use this code to display the parameter panel:

viewer.showParameterPanel( );

actuate.Viewer.showPrintDialog

Syntax

void Viewer.showPrintDialog( )

Displays the print dialog window.

Example

Use this code to display the print dialog window:

viewer.showPrintDialog( );

actuate.Viewer.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/Top 5 Sales Performers.rptdesign");

viewer.submit( );