Progress® Telerik® Reporting R2 2017

Report Viewer Initialization

The Telerik HTML5 Report Viewer is a jQuery plugin - jQuery.fn.telerik_ReportViewer(options). Below is a list of all options available during initialization.

Options

Parameter

Description

id

string, optional; Sets the unique identifier of the ReportViewer instance. If not specified, the id of the target HTML element will be used (if such is set). The id of the ReportViewer is used to identify the client session of the viewer when persistSession is enabled (true);

serviceUrl

string, required if reportServer not used; Sets the address of the Report REST Service;

reportServer

object, required if serviceUrl not used; Sets the configuration details for Telerik Report Server. Available properties:

  • url (string, required) - the URL to the Telerik Report Server instance.

  • username (string, optional) - a registered username in Report Server that will be used to get access to the reports. If omitted, the Report Server built-in Guest account will be used;

  • password (string, optional) - the password for the provided username. Can be omitted only when connecting with the Guest account.

templateUrl

string, optional; Sets the address of the html page that contains the viewer templates; If omitted, the default template will be downloaded from the REST service.

reportSource

object, optional; Sets the report and initial report parameter values for the viewer to be displayed. Available properties:

  • report - a string that represents a report on the server. On the server side this string will be converted to a ReportSource through an IReportResolver. That said this string may contain everything as far as the Telerik Reporting REST Services knows how to convert to a reports source that will be passed to the report engine for further processing. For example this may be an assembly qualified type name that can be converted to TypeReportSource, a path to a report definition file (.trdp/.trdx) as in the UriReportSource, or even a report id that a dedicated IReportSourceResolver will use to read the report definition stored in a database in xml format and converted to a XmlReportSource.

  • parameters - an object with properties name/value equal to the report parameters’ names and values used in the report definition;

scale

number, optional; Sets the scale factor for the report pages. The scale takes effect when scaleMode is set to “SPECIFIC”. Default value is 1.0 (100%);

scaleMode

string, optional; Sets how the report pages to be scaled. Available options are:

  • “FIT_PAGE_WIDTH” - the pages are scaled proportional to fit the entire width in the viewer’s view port;

  • “FIT_PAGE” - the pages are scaled proportional to fit the entire page in the view port;

  • “SPECIFIC” - the pages are scaled with the scale value;

Default value is: “FIT_PAGE”.

viewMode

string, optional; Sets if the report is displayed in interactive mode or in print preview. The available values are:

  • “INTERACTIVE” - enables drill-down interactivity, etc;

  • “PRINT_PREVIEW” - the report is paged according to the page settings;

For more information please see Interactive vs. Print Layout. Default value is: 'Interactive'.

persistSession

boolean|optional. Sets whether the viewer’s client session to be persisted between the page’s refreshes(ex. postback). The session is stored in the browser’s sessionStorage and is available for the duration of the page session. A page session lasts for as long as the browser is open and survives over page reloads and restores. Opening a page in a new tab or window will cause a new session to be initiated.

The viewer’s state is persisted in the global sessionStorage object under a key defined by the viewer’s id. In order to enable the correct session to be loaded on the next page reload please use the same id as in the first load. This means that if you need to persist the client session between page reloads you should set the viewer’s id (or the id of the target element) to a constant value that should not be changed dynamically during the page lifecycle.

Default Value is: false;

parameterEditors

array, optional; Allows user to defined custom editors for the report parameters.

authenticationToken

string, optional; If provided, a Bearer token will be set in the Authorization header for every request to the REST service.

ready

function();optional; A callback function that will be called when the viewer content has been loaded from the template and is ready to display reports or perform any other operations on it. The function is executed in the context of the ReportViewer object that is available through the this object.

printMode

string, optional. Specifies how the viewer should print reports. The available values are:

  • “AUTO_SELECT” - specifies that the viewer should automatically decide which option for printing to use depending on browser's version and whether the PDF plug-in is available or not. This is the default value;

  • “FORCE_PDF_FILE” - specifies that the document for printing will be downloaded as a file (in PDF format with a special 'print' script enabled);

  • “FORCE_PDF_PLUGIN” - specifies that the viewer should always use the PDF plug-in;

selector

A selector used in conjunction with the data- attributes. Whenever a command is attached to an element outside of the report viewer via the data- attributes this selector must be provided.

disabledButtonClass

A class used in conjunction with the data- attributes. Whenever a command is in the disabled state this class will be added to the respective button.

checkedButtonClass

A class used in conjunction with the data- attributes. Whenever a command is in the checked state this class will be added to the respective button.

exportBegin

function(e);optional; A callback function that will be called prior to starting the report export command.

exportEnd

function(e, args);optional; A callback function that will be called when the exported document is ready for download, but prior to the actual downloading.

printBegin

function(e);optional; A callback function that will be called prior to starting the print report command.

printEnd

function(e, args);optional; A callback function that will be called when the print document (Adobe PDF) is ready for download, but prior to being send to the printer.

renderingBegin

function(e);optional; A callback function that will be called when the rendering of the report begins.

renderingEnd

function(e, args);optional; A callback function that will be called when the rendering of the report ends.

updateUi

function(e);optional; A callback function that will be called every time the UI needs an update; can be used for changing the UI of the report viewer while interacting with the reports.

pageReady

function(e, args);optional; A callback function that will be called every time a page from the report is rendered and ready for display.

error

function(e, args);optional; A callback function that will be called when an error occurs.

viewerToolTipOpening

function(e, args);optional; A callback function that will be called when a tooltip is being opened.

Examples

To create a ReportViewer:

JavaScript
$("#reportViewer1").telerik_ReportViewer({
  serviceUrl: "../api/reports/",
  templateUrl: 'src/templates/telerikReportViewerTemplate-x.x.x.x.html',
  reportSource: { report: "product catalog.trdp" }
});

where x.x.x.x is the version of the HTML5 ReportViewer/Telerik Reporting (e.g. 8.1.14.618).

To get the ReportViewer object from the HTML element:

JavaScript
var reportViewer = $("#reportViewer1").data("telerik_ReportViewer");

See Also

Other Resources