Initialization Options

Following are the options, methods and properties available to work with HTML5 Viewer using the Javascript.

uiType

Description: Sets the UI mode of the HTML5 Viewer.

Type: String

Accepted Value: 'Custom', 'Mobile' or 'Desktop'

Example:

viewer.option('uiType', 'Mobile');

element

Description: JQuery selector that specifies the element that hosts the HTML5 Viewer control.

Note: This option is used during initialization only.

Type: String

Example:

var viewer = GrapeCity.ActiveReports.Viewer(
{
   element: '#viewerContainer2',
   reportService: {
      url: '/ActiveReports.ReportService.asmx'
   },
});

reportService

Description: The report service that can use ActiveReports 9 Server or ActiveReports Web Report Service.

Type: Object that has the url and optional securityToken properties

Example:

reportService: {
   url: 'http://remote-ar-server.com',
   securityToken: '42A9CD80A4F3445A9BB60A221D042FCC',
   resourceHandler: 'http://remote-ar-server.com/resourceHandler.aspx'
};

reportService.url

Description: The url of ActiveReports 9 Server instance of the ActiveReports Web service that provides the reportInfo and output.

Type: String

Example:

reportService: {
   url: 'http://remote-ar-server.com'
};

reportService.securityToken

Description: The security key needed to login to the ActiveReports 9 Server.

Type: String

Example:

reportService: {
   securityToken: '42A9CD80A4F3445A9BB60A221D042FCC'
};

reportService.resourceHandler

Description: The url of the ActiveReports 9 Server resource handler.

Type: String

Example:

reportService: {
   resourceHandler: 'http://remote-ar-server.com/resourceHandler.aspx'
};

report

Description: The report that is displayed in ActiveReports 9 Server or ActiveReports Web Report Service.

Type: An object that has id and parameters properties.

Example:

report: {
   id: 'CustomersList',
   parameters: [
   {
      name: 'CustomerID',
      value: 'ALFKI'
   }]
};

reportID

Description: The id of the report to be shown by the HTML5 Viewer.

Type: String

Example:

report: {
   id: 'CustomersList',
   parameters: [
   {
      name: 'CustomerID',
      value: 'ALFKI'
   }]
};

reportParameters

Description: The array of the {name, value} pairs that describe the parameters values used to run the report.

Type: Array

Example:

report: {
   id: 'CustomersList',
   parameters: [
   {
      name: 'CustomerID',
      value: 'ALFKI'
   }]
};

reportLoaded

Description: The callback that is invoked when the HTML5 Viewer obtains the information about the requested report. The reportInfo object is passed in the callback including the TOC info, Parameters info and the link to the rendered report result.

Type: function(reportInfo)

Example:

var reportLoaded = function reportLoaded(reportInfo)
   {
      console.log(reportInfo.parameters);
   }
viewer.option('reportLoaded', reportLoaded);

action

Description: The callback that is invoked before the HTML5 Viewer opens the hyperlink, bookmark link, drill down report or toggles the report control visibility.

Type: function(actionType, actionParams)

Example:

function onAction(actionType, actionParams)
{
   if (actionType === 0)
   {
      window.open(params.url, "Linked from report", "height=200,width=200");
   }
}
viewer.option('action', onAction);

availableExports

Description: The array of export types available via Export functionality of HTML5 Viewer. By default, PDF, Word, Image, Mht, and Excel exports are available.

Type: Array

Example:

viewer.option("availableExports", ['Pdf']);

maxSearchResults

Description: The number of search results received for a single search invoke.

Type: Number

Example:

maxSearchResults: 10

error

Description: The callback that is invoked when an error occurs in the process of displaying the report. The error message can be customized.

Type: function(error)

Example:

var options = {
  error: function(error){ 
    error.message = "My error message";
  },
  // other properties
};
var viewer = GrapeCity.ActiveReports.Viewer(options);

documentLoaded

Description: The callback that is invoked when a document is loaded entirely on the server.

Type: function()

Example:

var documentLoaded = function documentLoaded()
   {
      setPaginator();
   }
viewer.option('documentLoaded', documentLoaded);

localeUri

Description: The url of the file containing the localization strings.

Note: This option is used during initialization only.

Type: String

Example:

var viewer = GrapeCity.ActiveReports.Viewer(
{
   localeUri: 'Scripts/i18n/ru.txt'
});

Public API Methods and Properties

After initializing the HTML5 Viewer, the following API methods and properties can be used.

Methods

option

Description: Gets or sets the option value by name if the value parameter is specified.

Syntax: option(name,[value])Object

Parameters:

name: The option name to get or set.
value: (optional) The option value to set. If this argument is omitted than the method returns the current option value.

Example:

viewer.option('uiType', 'mobile');
viewer.option('report', {
   id: 'my report'
});

Return Value: The current option value.

refresh

Description: Refreshes the report preview.

Syntax: option(name,[value])Object

Example:

viewer.refresh()

Return Value: Void

Description: Prints the currently displayed report if any.

Syntax: print()Void

Example:

viewer.print()

Return Value: Void

goToPage

Description: Makes the viewer to display the specific page, scroll to the specific offset (optional) and invokes the callback once it's done.

Syntax: goToPage(number, offset, callback)Void

Parameters:

number: The number of pages to go to.
offset object: The object such as {left:12.2, top:15}.
callback: The function to call after perform action.

Example:

viewer.goToPage(1, {
   2, 3
}, function onPageOpened()
{});

Return Value: Void

backToParent

Description: Makes the viewer to display the parent report of the drill-down report.

Syntax: backToParent()Void

Example:

viewer.backToParent()

Return Value: Void

destroy

Description: Removes the viewer content from the element.

Syntax: destroy()Void

Example:

viewer.destroy()

Return Value: Void

export

Description: Exports the currently displayed report.

Syntax: export(exportType,callback,saveAsDialog,settings)Void

Parameters:

exportType: Specifies export format.
callback: Function that is invoked once the export result is available (its Url is passed in the callback).
saveAsDialog: Indicates whether the save as dialog should be shown immediately once the export result is ready.
settings: The export settings, vary for each export type.

Example:

viewer.export('Word', function ()
{
   console.log('export callback');
}, true, {
   FileName: 'Document.doc'
})

Return Value: Void

Description: Performs the search of a specific term with specific search options (match case, whole word) and invokes the specific callback with the search result passed.

Syntax: search(searchTerm, searchOptions, callback)Void

Parameters:

searchTerm: String to find.
searchOptions: The object optionally defines the search options:
- matchCase: Whether the search should respect the case.
- wholePhrase: Whether the search should look for a whole phrase.
callback: The function to call after performing search.

Example:

viewer.search('a', {
   matchCase: true,
   wholePhrase: false
}, function (results)
{
   console.log(results);
});

Return Value: Void

getToc

Description: Obtains the part of the report TOC specified by parent(node), startChild(index), count parameters and invokes callback function passing the result as parameter.

Syntax: getToc(callback) Void

Parameters:

callback: The callback to handle TOC tree.

Example:

viewer.getToc(function (toc)
{
   console.log(toc);
})

Return Value: Void

Properties

pageCount

Description: Gets the page count of the currently displayed report.

Syntax: viewer.pageCount

Example:

console.log(viewer.pageCount)

Return Value: An integer representing page count.

currentPage

Description: Gets the currently displayed page number.

Syntax: viewer.currentPage

Example:

console.log(viewer.currentPage)

Return Value: An integer representing currently displayed page number.

Toolbar

Description: Returns the HTML element that displays the toolbar in desktop UI mode. The developer may use it to add the custom elements or remove the existing ones using jQuery/Html/Css capabilities.

Syntax: viewer.Toolbar

Example:

// Toolbar, MobileToolbarTop, MobileToolbarBottom
$(viewer.toolbar).hide();
$(viewer.toolbarTop).hide();
$(viewer.toolbarBottom).hide();

ToolbarTop

Description: Returns the HTML element that displays the top toolbar in mobile UI mode. The developer may use it to add the custom elements or remove the existing ones using jQuery/Html/Css capabilities.

Syntax: viewer.ToolbarTop

Example:

// Toolbar, MobileToolbarTop, MobileToolbarBottom
$(viewer.toolbar).hide();
$(viewer.toolbarTop).hide();
$(viewer.toolbarBottom).hide();

ToolbarBottom

Description: Returns the HTML element that displays the bottom toolbar in mobile UI mode. The developer may use it to add the custom elements or remove the existing ones using jQuery/Html/Css capabilities.

Syntax: viewer.ToolbarBottom

Example:

// Toolbar, MobileToolbarTop, MobileToolbarBottom
$(viewer.toolbar).hide();
$(viewer.toolbarTop).hide();
$(viewer.toolbarBottom).hide();