BIRT Data Analyzer API classes : Class actuate.XTabAnalyzer

Class actuate.XTabAnalyzer

Description

The actuate.XTabAnalyzer class represents a XTabAnalyzer viewer.

Constructor

Syntax

actuate.XTabAnalyzer( )

Constructs a new Data Analyzer object.

actuate.XTabAnalyzer(object xtabContainer, actuate.xtabanalyzer.UIOptions uiOptions)
actuate.XTabAnalyzer(string xtabContainerId, actuate.xtabanalyzer.UIOptions uiOptions)

Constructs a new Data Analyzer object in the specified container.

Parameters

xtabContainer

Object. A document object referencing the HTML <div> element that contains the xTabAnalyzer viewer.

xtabContainerId

String. The value of the ID parameter for the HTML <div> element which holds the xTabAnalyzer viewer. For example, with 'containerName' as the xtabContainer parameter, a <DIV ID='containerName' /> tag on the page displays the viewer at the location of the <div> element.

uiOptions

actuate.xtabanalyzer.UIOptions object. Optional. UIOptions references display options for the viewer.

Function summary

Table 5-2 lists actuate.XTabAnalyzer functions.

Table 5-2  actuate.XTabAnalyzer functions 
Function
Description
commit( )
Commits all changes to the report design.
forceSoftRestart( )
Forces the viewer to restart.
getCurrentPageContent( )
Returns the current page content object.
getCurrentPageNum( )
Returns the current page number.
getGadgetId
Returns the gadget ID of the shown cross tab.
getHeight( )
Returns the viewer height.
getId( )
Returns the ID of the object.
getIportalUrl( )
Returns the Actuate web application URL that the viewer accesses.
getLeft( )
Returns the viewer left margin.
getPosition( )
Returns the CSS position attribute value.
getRequestOptions( )
Returns the request options.
getTop( )
Returns the viewer top margin.
getTotalPageCount( )
Returns the total page count.
getUIOptions( )
Returns the actuate.xtabanalyzer.UIOptions object assigned to this viewer.
getViewer( )
Gets a viewer within a container.
getWidth( )
Returns the viewer width.
getXTabBookmark( )
Returns the bookmark of the cross tab displayed in the viewer.
getXTabIid( )
Returns the instance ID of the cross tab displayed in the viewer.
isActive( )
Checks if current viewer popup is active.
isDashboard( )
Checks if the current viewer popup is a dashboard.
registerEventHandler( )
Registers an event handler.
removeEventHandler( )
Removes an event handler.
reset( )
Resets the viewer object.
resizeTo( )
Resizes the viewer.
rollback( )
Rolls back all changes in the viewer and refreshes its content.
setGadgetId
Sets the gadget id of the cross tab.
setHeight( )
Sets the viewer height.
setIVMode( )
Sets whether the viewer is in IV mode.
setLeft( )
Sets the viewer left margin.
setOnClosed( )
Set callback when popup window is closed.
setPosition( )
Sets the CSS position attribute.
setReportletDocumentMode( )
Sets a reportlet to document mode.
setReportName( )
Sets the report file for the viewer.
setService( )
Sets the Information Console and request options.
setSupportSVG( )
Sets whether or not the client browser supports SVG.
setTop( )
Sets the top margin.
setUIOptions( )
Sets the user interface options for the viewer.
setWidth( )
Sets the viewer width.
setXTabBookmark( )
Sets a bookmark for the cross tab.
setXTabIid( )
Sets the instance ID of the cross tab.
submit( )
Submits asynchronous operations and renders the requested components.

actuate.XTabAnalyzer.commit

Syntax

void XTabAnalyzer.commit(function callback)

Commits all design changes to a generated document as a single operation. If ivMode is not set to true, call setIVMode( ) to set the value of ivMode to true before calling commit( ).

Parameter

callback

Function. The callback function called after the commit is completed.

Example

This example opens a design with a cross tab and pivots the cross tab.

function pivot( ){
// make a change to the cross tab.
  crosstab.pivot( );
  crosstab.submit( );
  viewer.commit( );
}

actuate.XTabAnalyzer.forceSoftRestart

Syntax

void XTabAnalyzer.forceSoftRestart( )

Forces the viewer to restart.

Example

This example restarts the viewer.

this.onclick = function(event){
  forceSoftRestart( );
}

actuate.XTabAnalyzer.getCurrentPageContent

Syntax

actuate.xtabanalyzer.PageContent XTabAnalyzer.getCurrentPageContent( )

Returns the current page content object.

Returns

actuate.xtabanalyzer.PageContent object.

Example

This example calls getCurrentPageContent( ) to retrieve a pointer to the cross tab on the page.

function getCrosstab(analyzerViewer){
  var content = analyzerViewer.getCurrentPageContent( );
  return content.getCrosstabByBookmark( );
}

actuate.XTabAnalyzer.getCurrentPageNum

Syntax

integer XTabAnalyzer.getCurrentPageNum( )

Returns the current page content object.

Returns

integer. current page number.

Example

This example retrieves the page number.

function retrievePageNum( ){
  return analyzerViewer.getCurrentPageNum( );
}

actuate.XTabAnalyzer.getGadgetId

Syntax

string XTabAnalyzer.getGadgetId( )

Returns the gadget ID of the shown cross tab. This function is used for dashboard integration.

Returns

String.

Example

This example retrieves the gadget ID.

function retrieveGadgetID( ){
  return analyzerViewer.getGadgetId( );
}

actuate.XTabAnalyzer.getHeight

Syntax

integer XTabAnalyzer.getHeight( )

Returns the height of the viewer.

Returns

Integer.

Example

This example retrieves the current height of the viewer and doubles the height if the current height is lower than 630 pixels.

function doubleHeight( ){
  var height = viewer.getHeight( );
  if (height < 630)
  {
    height = height * 2;
    viewer.setHeight(height);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.getId

Syntax

string XTabAnalyzer.getId( )

Returns the ID of the viewer.

Returns

String.

Example

This example retrieves the viewer ID.

function retrieveID( ){
  return viewer.getId( );
}

actuate.XTabAnalyzer.getIportalUrl

Syntax

string XTabAnalyzer.getIportalUrl( )

Returns the Deployment Kit for BIRT Reports or Information Console URL.

Returns

String.

Example

This example retrieves the Iportal URL.

function retrieveIPortalURL( ){
  return viewer.getIportalUrl( );
}

actuate.XTabAnalyzer.getLeft

Syntax

integer XTabAnalyzer.getLeft( )

Returns the left margin of the viewer.

Returns

Integer.

Example

This example retrieves the position of the viewer’s left margin and moves the margin 20 pixels to the right if the left margin is fewer than 45 pixels from the left edge of the screen.

function moveLeftMargin( ){
  var left = viewer.getLeft( );
  if (left < 45){
    left = left + 20;
    viewer.setLeft(left);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.getPosition

Syntax

string XTabAnalyzer.getPosition( )

Returns the CSS position attribute for the viewer.

Returns

String.

Example

This example changes the CSS positioning type from relative to absolute.

function changePosition( ){
  var pos = viewer.getPosition( );
  if (pos == 'relative'){
    pos = 'absolute';
    viewer.setPosition(pos);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.getRequestOptions

Syntax

actuate.RequestOptions XTabAnalyzer.getRequestOptions( )

Returns a requestOptions object.

Returns

actuate.RequestOptions object.

Example

This example retrieves the request options.

function retrieveRequestOptions( ){
  return viewer.getRequestOptions( );
}

actuate.XTabAnalyzer.getTop

Syntax

integer XTabAnalyzer.getTop( )

Returns the top margin of the viewer.

Returns  

Integer.

Example

This example retrieves the value for the viewer’s top margin and moves the margin 20 pixels down the screen if the margin was fewer than 45 pixels from the top of the screen.

function moveTopMargin( ){
  var top = viewer.getTop( );
  if (top < 45)  {
    top = top + 20;
    viewer.setTop(top);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.getTotalPageCount

Syntax

integer XTabAnalyzer.getTotalPageCount( )

Returns the total page count.

Returns

Integer.

Example

This example displays an alert with the total page count from viewer.

alert("Total pages: " + viewer.getTotalPageCount( ));

actuate.XTabAnalyzer.getUIOptions

Syntax

actuate.xtabanalyzer.UIOptions getUIOptions( )

Returns the user interface options object for the cross tab analyzer. The UIOptions object specifies what features are used within the viewer.

Returns

actuate.xtabanalyzer.UIOptions object.

Example

This example retrieves the user interface options and sets one of the UIOptions values.

function resetUIOptions( ){
  var options = viewer.getUIOptions( );
  options.enableToolbar(false);
  viewer.setUIOptions(options);
}

actuate.XTabAnalyzer.getViewer

Syntax

static XTabAnalyzer.getViewer(string container)

Returns a viewer by container. To retrieve the viewer for the current object, do not specify a container. This function is useful to retrieve the instance ID for a specific viewer when there are multiple viewers on a page.

Parameters

container

String. The container instance ID from which to retrieve the object.

Returns

XTabAnalyzer object.

Example

This example retrieves the viewer.

function retrieveViewer( ){
  return viewer.getViewer( );
}

actuate.XTabAnalyzer.getWidth

Syntax

string XTabAnalyzer.getWidth( )

Returns the width value of the viewer.

Returns

String.

Example

This example retrieves the width of the viewer, then alters it based on the size.

function doubleWidth( ){
  var width = viewer.getWidth( );
  if (width < 630){
    width = width * 2;
    viewer.setWidth(width);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.getXTabBookmark

Syntax

string XTabAnalyzer.getXTabBookmark( )

Returns the bookmark name for the cross tab that was set by setXTabBookmark( ).

Returns

String.

Example

This example retrieves the bookmark that the cross tab is associated with, changes the bookmark, and resets the bookmark. This functionality supports the use of multiple cross tab elements within a single design.

function changeBookmark( ){
// Save the old bookmark.
  var oldBookMark = viewer.getXTabBookmark( );
  // Associate the viewer to another bookmarked cross tab
  viewer.setXTabBookmark("crosstab2");
  viewer.submit( );
}

actuate.XTabAnalyzer.getXTabIid

Syntax

string XTabAnalyzer.getXTabIid( )

Returns the current instance ID of the crosstab analyzer. This function is useful in integration with the Interactive Viewer and supports the ability of the Interactive Viewer to obtain and use the cross tab instance ID.

Returns

String.

Example

This example retrieves the cross instance ID.

function retrieveXTablid( ){
  return viewer.getXTablid( );
}

actuate.XTabAnalyzer.isActive

Syntax

boolean XTabAnalyzer.isActive( )

Returns true when a popup containing a cross tab analyzer is active and false in all other cases.

Returns    

Boolean.

Example

This example checks if a viewer exists by checking two conditions: the viewer variable exists, or isActive( ) returns true. When both conditions fail, the example code creates a new viewer object within a container.

function checkViewer( ){
  if(!viewer || !viewer.isActive( )){
    viewer = new actuate.XTabAnalyzer(container);  
  }
}

actuate.XTabAnalyzer.isDashboard

Syntax

boolean XTabAnalyzer.isDashboard( )

Returns true when dashboard mode is active and false in all other cases.

Returns    

Boolean.

actuate.XTabAnalyzer.registerEventHandler

Syntax

void XTabAnalyzer.registerEventHandler(string viewerEvent, function handler)

Registers an event handler for the specified event. This function throws actuate.xtabanalyzer.Exception when invalid arguments are passed.

Parameters  

viewerEvent

String. Specifies the event that triggers the handler call. For a list of supported events, see actuate.xtabanalyzer.EventConstants.

handler

Function. Called when the event occurs.

Example

This example changes an event handler from one function to another.

function changeEventHandler( event ){
// Remove the event handler for ON_CONTENT_CHANGED.
  viewer.removeEventHandler(actuate.xtabanalyzer.EventConstants.ON_CONTENT_CHANGED, oldChangedHandler);
// Add a different event handler for the event.
  viewer.registerEventHandler(actuate.xtabanalyzer.EventConstants.ON_CONTENT_CHANGED, newChangedHandler);
}

actuate.XTabAnalyzer.removeEventHandler

Syntax

void XTabAnalyzer.removeEventHandler(string viewerEvent, function handler)

Removes an event handler from the specified event. This function throws actuate.xtabanalyzer.Exception when invalid arguments are passed.

Parameters  

viewerEvent

String. Specifies the event from which to remove the event handler. For a list of supported events see actuate.xtabanalyzer.EventConstants.

handler

Function. The function to deregister from the event.

Example

This example changes an event handler from one function to another.

function changeEventHandler( event ){
 
// Remove the event handler for ON_CONTENT_CHANGED.
  viewer.removeEventHandler(actuate.xtabanalyzer.EventConstants.ON_CONTENT_CHANGED, oldChangedHandler);
// Add a different event handler for the event.
  viewer.registerEventHandler(actuate.xtabanalyzer.EventConstants.ON_CONTENT_CHANGED, newChangedHandler);
}

actuate.XTabAnalyzer.reset

Syntax

void XTabAnalyzer.reset( )

Resets the viewer to its initial state.

Example

This example resets the viewer. All changes to the viewer made prior to this call are lost.

function resetViewer( ){
  viewer.reset( );
}

actuate.XTabAnalyzer.resizeTo

Syntax

void XTabAnalyzer.resizeTo(integer width, integer height)

Resizes the viewer to the specified height and width.

Parameters  

width

Integer. The width to set the viewer to.

height

Integer. The height to set the viewer to.

Example

This example resizes the viewer when the new width is fewer than 1000 pixels and the new height is fewer than 650 pixels.

function resizeViewer(width,height){
  if ((width < 1000) && (height < 650))  {
    viewer.resizeTo(width,height);
  }
}

actuate.XTabAnalyzer.rollback

Syntax

void XTabAnalyzer.rollback( )

Rolls back all changes in the viewer since the last commit( ) call and refreshes the viewer’s content. The value of ivMode must be true for rollback( ) to function.

Example

This example rolls back all changes to the viewer made since the last commit or submit function call.

function rollbackViewer( ){
  viewer.rollback( );
}

actuate.XTabAnalyzer.setGadgetId

Syntax

void XTabAnalyzer.setGadgetId(string gadgetId)

Sets the cross tab gadget ID. This function is used for dashboard integration.

Parameters

gadgetId

String. The gadget ID of the cross tab.

Example

This example sets the gadget ID.

function setGadgetID(id){
  viewer.setGadgetId(id);
}

actuate.XTabAnalyzer.setHeight

Syntax

void XTabAnalyzer.setHeight(integer height)

Changes the height of the viewer.

Parameters

height

Integer. The height to set the viewer to.

Example

This example retrieves the viewer’s current height. When the current height is fewer than 630 pixels, the example code doubles the viewer’s height.

function doubleHeight( ){
  var height = viewer.getHeight( );
  if (height < 630)  {
    height = height * 2;
    viewer.setHeight(height);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.setIVMode

Syntax

void XTabAnalyzer.setIVMode(boolean ivMode)

Sets IVMode for the viewer. Integrating a Data Analytics viewer with the Interactive Viewer affects the undo/redo feature. When set to true, all changes to the Data Analytics viewer must be committed as one transaction. The Interactive Viewer can undo or redo the entire batch.

Parameters

ivMode

Boolean. Set to true if using IV mode.

Example

This example sets IVMode for the viewer.

function setViewerMode(mode){
  viewer.setIVMode(mode);
}

actuate.XTabAnalyzer.setLeft

Syntax

void XTabAnalyzer.setLeft(integer left)

Sets the position of the viewer’s left margin.

Parameters

left

Integer. The left margin for the viewer.

Example

This example retrieves the left margin of the viewer and moves the margin 20 pixels to the right when the margin is less than 45 pixels from the edge of the screen.

function moveLeftMargin( ){
  var left = viewer.getLeft( );
  if (left < 45){
    left = left + 20;
    viewer.setLeft(left);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.setOnClosed

Syntax

void XTabAnalyzer.setOnClosed(function callback)

Sets a callback function to call when a viewer popup closes.

Parameters  

callback

Function. The function to call when the popup closes.

Example

This example checks to see if a popup window is active and sets a callback function to trigger when the popup closes.

function setPopupCloser( ){
  if(viewer.isActive( )){
    viewer.setOnClosed(closerCallbackFunctionName);
  }
}

actuate.XTabAnalyzer.setPosition

Syntax

void XTabAnalyzer.setPosition(string position)

Sets the CSS position attribute.

Parameters  

position

String. The value for the CSS position attribute.

Example

This example changes the type of CSS positioning in use.

function changePosition( ){
  var pos = viewer.getPosition( );
  if (pos == 'relative')  {
    pos = 'absolute';
    viewer.setPosition(pos);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.setReportletDocumentMode

Syntax

void XTabAnalyzer.setReportletDocumentMode(boolean reportletMode)

Set whether it is under Reportlet document mode

Parameters

reportletMode

Boolean. True or false.

actuate.XTabAnalyzer.setReportName

Syntax

void XTabAnalyzer.setReportName(string reportName)

Sets the report file name for the viewer. The file must be a document file.

Parameters

reportName

String. The name of the report file.

Example

This example initializes Data Analytics and opens a report file. The value of acviewer is the name of the <div> where the cross tab viewer appears.

actuate.load("xtabAnalyzer");
actuate.load("dialog");
actuate.initialize("../../",null,null,null,run);
var viewer;
var container;
function run( ){
  container = document.getElementById("acviewer");
  viewer = new actuate.XTabAnalyzer(container);  
  viewer.setReportName("reportfile.rptdocument");
  viewer.submit( );
}

actuate.XTabAnalyzer.setService

Syntax

void XTabAnalyzer.setService(string iPortalURL, actuate.RequestOptions requestOptions)

Sets the Actuate web application URL. This function can request options for that URL.

Parameters

iPortalURL

String. The URL of the Actuate web application.

requestOptions

actuate.RequestOptions object. Request options for the web application. This parameter is optional.

Example

This example sets the service and request options.

function setServerOptions(URL,options){
  viewer.setService(URL,options);
}

actuate.XTabAnalyzer.setSupportSVG

Syntax

void XTabAnalyzer.setSupportSVG(boolean svgFlag)

Sets a flag indicating whether or not the browser supports SVG.

Parameters

svgFlag

Boolean. Flag indicating SVG support in the browser. This parameter’s value is true when the browser supports SVG and false in all other cases.

Example

This example returns the browser’s level of SVG support.

function setSVG(flag){
  viewer.setSupportSVG(flag);
}

actuate.XTabAnalyzer.setTop

Syntax

void XTabAnalyzer.setTop(integer top)

Sets the top margin for the viewer.

Parameters

top

Integer. The top margin for the viewer.

Example

This example retrieves the current top margin for the viewer and moves the margin 20 pixels down the screen when the current position of the margin is fewer than 45 pixels from the top of the screen.

function moveTopMargin( ){
  var top = viewer.getTop( );
  if (top < 45){
    top = top + 20;
    viewer.setTop(top);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.setUIOptions

Syntax

void XTabAnalyzer.setUIOptions(actuate.xtabanalyzer.uioptions options)

Sets the options available to the viewer

Parameters

options

Actuate.xtabanalyzer.uioptions object. The options object for the viewer.

Example

This example retrieves the user interface options and sets one of the UIOptions values.

function resetUIOptions( ){
  var options = viewer.getUIOptions( );
  options.enableToolbar(false);
  viewer.setUIOptions(options);
}

actuate.XTabAnalyzer.setWidth

Syntax

void XTabAnalyzer.setWidth(integer width)

Sets the width for the viewer.

Parameters

width

Integer. The width for the viewer.

Example

This example retrieves the width of the viewer. When the viewer is fewer than 630 pixels wide, the example code doubles the viewer’s width.

function doubleWidth( ){
  var width = viewer.getWidth( );
  if (width < 630){
    width = width * 2;
    viewer.setWidth(width);
    viewer.submit( );
  }
}

actuate.XTabAnalyzer.setXTabBookmark

Syntax

void XTabAnalyzer.setXTabBookmark(string bookmark)

Sets a bookmark for the viewer.

Parameters

bookmark

String. The viewer bookmark.

Example

This example retrieves the bookmark for the cross tab the viewer is associated with, changes the bookmark, and reloads the bookmark. This functionality enables the use of multiple cross tab elements within a single design.

function changeBookmark( ){
  // Save the old bookmark.
  var oldBookMark = viewer.getXTabBookmark( );
  // Associate the viewer to another bookmarked cross tab
  viewer.setXTabBookmark("crosstab2");
  viewer.submit( );
}

actuate.XTabAnalyzer.setXTabIid

Syntax

void XTabAnalyzer.setXTabIid(string id)

Sets the instance ID for viewer rendering. This function is useful in integration with the Interactive Viewer, and supports the ability of the Interactive Viewer to obtain and use the cross tab instance ID.

Parameters

id

String. The instance ID.

Example

This example sets the cross tab instance ID.

function setxtabInstance(id){
  viewer.setXTablid(id);
}

actuate.XTabAnalyzer.submit

Syntax

void XTabAnalyzer.submit(function callback)

Submits requests to the server for the Data Analyzer viewer. This method triggers an AJAX request to submit all pending operations for this object. The server returns a response after processing the pending operations. The results render on the page in the Data Analyzer container. The submit( ) function throws an exception when another submit( ) operation is pending. A CONTENT_CHANGED event fires when the data analyzer content changes.

Parameters

callback

Function. An optional function called when submit completes. This function receives the current XTabAnalyzer object as a parameter.

Example

This example retrieves the left margin of the viewer and expands the margin. The change does not take effect until submit( ) executes. The submit( ) function calls the function in the submitCallback parameter when submit( ) finishes executing. The callback function contains any processing that must occur after submit( ) finishes. Do not place such code after the submit( ) call because submit( ) is asynchronous.

function moveLeftMargin( ){
  var left = viewer.getLeft( );
  if (left < 45)  {
    left = left + 20;
    viewer.setLeft(left);
    viewer.submit(submitCallback);
  }
}
(c) Copyright Actuate Corporation 2011