Embedding Reports / Displaying Reports / Web Application / HTML5 Report Viewer / API Reference

New to Telerik Reporting? Download free 30-day trial

Initializing the HTML5 Report Viewer

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; Sets the address of the Report REST Service;
reportServer JSON, required if; 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 the 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 JSON, 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 IReportSourceResolver. That said this string may contain everything as far as the Telerik Reporting REST Service knows how to convert to the source of a report 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.
    When using the viewer with Report Server, the report should be provided in the format: report: "{Category}/{ReportName}", where {Category} and {ReportName} are the actual names of the category and report as explained in Using the HTML5 Report Viewer with the Report Server.
  • parameters - a JSON object with properties name/value equal to the report parameters’ names and values used in the report definition;
sendEmail object, required to show the; Available properties:
  • enabled (bool, required) - Indicates whether to show the Send Mail Message toolbar button.
    Default value: false;
  • from (string, optional) - E-mail address used for the MailMessage FROM value;
  • to (string, optional) - E-mail address used for the MailMessage TO value;
  • cc (string, optional) - E-mail address used for the MailMessage Carbon Copy value;
  • subject (string, optional) - A string used for the MailMessage Subject value;
  • body (string, optional) - Sentences used for the MailMessage Content value;
  • format (string, optional) - The preselected report document format.
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'.
pageMode string, optional; Sets if the report is displayed in Single page or Continuous scroll mode.
The available values are:
  • “SINGLE_PAGE” - only one page is loaded in the view port;
  • “CONTINUOUS_SCROLL” - more than one page could be loaded in the view port;
    Default value is: 'CONTINUOUS_SCROLL'.
printMode string, optional; Specifies whether the viewer will use the PDF plug-in of the browser for printing, or will directly export to a PDF file containing a special 'print' script.
The available values are:
  • "AUTO_SELECT" - the widget will try to automatically determine whether to export the report document or use the browser's PDF plug-in. First, the viewer widget tries to use the PDF plug-in of the browser for printing. When it is not available or not supported, the widget falls back to exporting to a PDF file containing a special 'print' script;
  • "FORCE_PDF_PLUGIN" - the widget will always try to use the PDF plug-in of the browser. If the browser doesn't have a PDF plug-in or it does not support the 'print' script nothing will happen;
  • "FORCE_PDF_FILE" - the widget will always export the report document to a PDF file with a special 'print' script;
Default value is: "AUTO_SELECT".
parametersAreaPosition string, optional. Specifies where the Parameters Area should be displayed.
The available values are:
  • “RIGHT”
  • “TOP”
  • “LEFT”
  • “BOTTOM”
Default value: RIGHT;
documentMapAreaPosition string, optional. Specifies where the Document Map should be displayed.
The available values are:
  • “RIGHT”
  • “LEFT”
Default value: LEFT;
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. 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;
parameters object, optional; Allows the user to define parameter options for the report parameters.
Option Description
editors object, optional; Allows the user to define editors type for the report parameters.
The available editors are:
  • singleSelect (string, optional) - defines the editor type for the single select parameters.
    The available values are: Default value is: 'LIST_VIEW'
  • multiSelect (string, optional) - defineds the editor type for the multi select parameters.
    The available values are: Default value is: 'LIST_VIEW' 
$("#reportViewer1").telerik_ReportViewer({...parameters: {editors: {multiSelect: telerikReportViewer.ParameterEditorTypes.COMBO_BOX,}}});
parameterEditors array, optional; Allows the user to define custom editors for the report parameters.
authenticationToken string, optional; If provided, a Bearer token will be set in the Authorization header for requests to the REST service. The token is not sent only when requesting document resources. The reason is that the resources like images are referenced with relative URLs in the HTML of the report document, hence the requests for them are made by the browser.
enableAccessibility boolean, optional. Determines whether the viewer should provide support for accessibility features. You can find more detailed information in the article Accessibility Overview.
Default value: false;
parametersAreaVisible boolean, optional. Determines whether the viewer's parameters area is displayed if any parameter editor exists.
Default value: true;
documentMapVisible boolean, optional. Determines whether the viewer's document map is displayed if any bookmark is defined.
Default value: true;
searchMetadataOnDemand boolean, optional. Determines whether the search metadata will be delivered on demand (true) or by default (false).
Default value: false;
initialPageAreaImageUrl string, optional. The image URL for the PageArea background image. Used only when the parameter values are missing or invalid. The image should be in PNG, GIF, or JPG file format.
keepClientAlive boolean, optional. Determines whether the client will be kept alive. When set to true expiration of the client will be prevented by continually sending a request to the server, determined by the Reporting REST service's ClientSessionTimeout.
Default Value is: true;
selector string, optional. 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 string, optional. 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 string, optional. 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.
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.
exportBegin function(e, args);optional; A callback function that will be called before 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 before the actual downloading.
printBegin function(e, args);optional; A callback function that will be called before 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 before being sent to the printer.
sendEmailBegin function(e, args);optional; A callback function that will be called before the report is exported and the E-mail message is sent.
sendEmailEnd function(e, args);optional; A callback function that will be called after the report is exported and before the E-mail message is sent.
renderingBegin function(e, args);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.
interactiveActionExecuting function(e, args);optional; A callback function that will be called before an interactive action is executed, providing the ability to cancel the execution..
interactiveActionEnter function(e, args);optional; A callback function that will be called when the mouse cursor enters the area of an interactive action.
interactiveActionLeave function(e, args);optional; A callback function that will be called when the mouse cursor leaves the area of an interactive action.

Examples

To create a ReportViewer:

$("#reportViewer1").telerik_ReportViewer({
    serviceUrl: "api/reports",
    templateUrl: 'src/templates/telerikReportViewerTemplate-18.3.24.1218.html',
    reportSource: { report: "Product Catalog.trdp" }
});

To get the ReportViewer object from the HTML element:

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

See Also

In this article
Related articles
Not finding the help you need? Improve this article