JSViewer API

In This Topic

Show All

Hide All

Initialization Options

The following options can be set during initialization or at run time while working with the JSViewer.

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

Type: function(actionType, actionParams)

Example:

action: (actionType, actionParams) => console.log('Action type: ' + actionType + '; Action parameters: ' + actionParams)

Description: The array of export types available via Export functionality of JSViewer. By default, PDF, Excel, Word, JSON, XML, CSV, and Image exports are available.

Type: Array

Example:

availableExports: ['Xml', 'Pdf']

Description: Set up single page or continuous page.

Type: String

Accepted Value: 'single', 'continuous'

Example:

displayMode: 'Continuous'

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

Type: function()

Example:

documentLoaded: () => console.log('The document is loaded entirely on the server')

Returns: Void

Description: JQuery selector that specifies the element that hosts the JSViewer control.

Type: String

Example:

element: '#viewerContainer'

Description: The callback that is invoked when an error occurs in the process of displaying the report. The default error panel does not appear if the callback returns true. The error parameter is an object that has a message property which allows the users to customize the error message.

Type: function(error)

Example: To hide the default error panel:

error: (error) => {
    if(error.message) {
    // show error message.
    alert("Internal error! Please ask administrator.");
    // do not show default error message.
    }
}

Description: Specifies predefined locale used for displaying the viewer. If locale is not specified explicitly here, the locale corresponding to the browser preferences is used. Localization can be done in three languages:

Type: String

Accepted Values: 'en-US' (for English), 'ja-JP' (for Japanese), and 'zh-CN' (for Chinese)

Example:

locale: 'ja-JP'

Description: The JSON containing the localization strings. All strings are not necessary - missing values are displayed using EN localization data. It is like localeUri, but instead of the path to localization data, localization data itself via JSON object is specified.

Type: JSON

Example:


localeData: JSON.parse( `{
    "export":  {
      "boolTextFalse": "いいえ",
      "boolTextTrue": "はい"
    },
    "viewer": {
      "toolbar": {
        "refresh": "更新"
      }
    }
  }`
),

Description: The url of the file containing the localization strings (custom-locale.json file). Not all strings are necessary - missing values are displayed using EN localization data.

Type: String

Example:

localeUri: './custom-locale.json'

Content of custom-locale.json:


{
  "export": {
    "boolTextFalse": "いいえ",
    "boolTextTrue": "はい",
    ...
  },
  "exportcsv": {
    "friendlyName": "-CSV-",
    "settings": {
      "ColumnsDelimiter": {
        "label": "列の区切り",
        "category": "その他"
      },
      ...
    },
    ...
  },
  ...
}

Description: Set up initial render mode: 'Paginated' or 'Galley'. Default value is 'Paginated'.

Type: String

Accepted Values: 'Galley', 'Paginated'

Example:

renderMode: 'Galley'

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

Type: String

Example:

reportID: 'AnnualReport.rdlx'

Description: The callback that is invoked when the JSViewer 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:

reportLoaded: (reportInfo) => console.log('The report ' + reportInfo.name + ' was successfully loaded!')

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

Type: Array

Example:

reportParameters: [{ name: 'ReportParameter1', values: ['1']}]

Description: Set up the settings to connect the Web API.

Type: Object that has the following optional properties:

url: The url to connect the Web API.
Type: String
Example:

use prefix in url:
```
url: '/api/reporting' // default value
```
use full URL:
```
url: 'http:example.com/api/reporting'
```

securityToken: The security key required to access the Web API.
Type: String
Example:
```
securityToken: 'security_token'
```
onRequest: Callback before any request. Takes the init argument that allows you to add an option before fetch request, for example, to change the security token.
Type: function
Example:
```
onRequest: (init) => init.headers.Authorization = 'security_token' 
```
The init argument is an object that takes the following options:
- credentials: Set request's credentials.
- headers: Set request's headers.
- signal: Set request's signal.
Please see https://fetch.spec.whatwg.org/#requestinit for more information.

Example:

reportService: {
    url: 'http://example.com/api/reporting', //web service url
    securityToken: 'security_token', //provide securityToken
    onRequest: (init) => {        
         init.credentials = "include",
         init.headers = { "Cache-Control": "no-cache, no-store, must-revalidate", "Expires": "0", "Pragma": "no-cache", "Accept": "application/json" },
         init.signal = new AbortController().signal
         }        
    }

Public API Methods and Properties

Methods

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

Syntax: backToParent()Void

Example:

viewer.backToParent()

Return Value: Void

Description: Creates a new instance of the Viewer and renders it in the specified DOM element.

Syntax: create()Void

Parameters:

params

Example:

const viewer = GrapeCity.ActiveReports.JSViewer.create({
    element: '#root',
    reportID: 'AnnualReport.rdlx',
    availableExports: ['Xml', 'Pdf'],
    // other properties
});

Return Value: Void

Description: Removes the viewer content from the element.

Syntax: destroy()Void

Example:

viewer.destroy()

Return Value: Void

Description: Exports the currently displayed report.

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

Parameters:

exportType: Specifies export format.
settings: The export settings are available for RenderingExtensions.
Note: In section reports, the export settings are not enabled when exporting files using the rendering extensions. In Page report and RDL report, the export settings are not enabled when exporting files to PDF using the export filter.

Example:

viewer.export('Pdf', downloadReport, true, { Title: '1997 Annual Report' })

Return Value: Void

Description: Obtains the report TOC.

Syntax: viewer.getToc()

Example:

console.log(viewer.getToc())

Return Value: any

Description: Makes the viewer to display the specific page.

Syntax: goToPage(number, offset, callback)Void

Parameters:

number: The number of pages to go to.

Example:

viewer.goToPage(1)

Return Value: Void

Description: Opens a report.

Syntax: openReport(reportID: string, reportParameters?: Array<Parameter>): void

Parameters:

reportID: The id of the report.

Example:

viewer.openReport('Invoice.rdlx')

Return Value: Void

Description: Prints the currently displayed report if any.

Syntax: print()Void

Example:

viewer.print()

Return Value: Void

Description: Refreshes the report preview.

Syntax: option(name,[value])Object

Example:

viewer.refresh()

Return Value: Void

Description: A string that represents the current version of the JSViewer.

Syntax: GrapeCity.ActiveReports.JSViewer.version

Example:

console.log(GrapeCity.ActiveReports.JSViewer.version)

Return Value: string

Description: Adds a custom toolbar item (button) to the toolbar's end.

Type: item: ToolbarItem

Example:

ToolbarItem = {
    key: string;
    iconCssClass?: string;
    icon?: Icon;
    text?: string;
    title?: string;
    checked?: boolean;
    enabled?: boolean;
    action?: (toolbarItem) => function;
    onUpdate?: (args: ChangedEventArgs, toolbarItem) => function;
}
 
Icon = FontIcon | SVGIcon;
 
 
SVGIcon = {
    type: 'svg';
    content: any; //(string | JSX.element)
    size?: Size;
    rotate?: '90' | '180' | '270';
};
 
 
FontIcon = {
    type: 'font';
    iconCssClass: string;
    fontSize?: string;
}
 
var pdfExportButton = {
    key: '$pdfExportButtonKey',
    iconCssClass: 'mdi mdi-file-pdf',
    enabled: true,
    action: function(item) {
        console.log('Export to PDF function works here');
    },
    onUpdate: function(arg, item) {
        console.log('Something in viewer was updated, check/update button state here');
    }
};
 
 
//OR button with svg as icon
var icon = `
    
`;
 
var svgPdfExportButton = {
    key: '$pdfExportButtonKey',
    icon: {type: 'svg', content: icon},
    enabled: true,
    action: function(item) {
        console.log('Export to PDF function works here');
    },
    onUpdate: function(arg, item) {
        console.log('Something in viewer was updated, check/update button state here');
    }
}
 
 
viewer.toolbar.addItem(pdfExportButton);
//or
viewer.toolbar.addItem(svgPdfExportButton);

Description: Updates the layout/function/state for a specified single item.

Type: String: key, ToolbarItem item

Example:

var xlsxExportButton = {
    key: '$xlsxExportButtonKey',
    iconCssClass: 'mdi mdi-file-pdf',
    enabled: true,
    action: function(item) { console.log('Export to XLSX function works here'); },
    onUpdate: function(arg, item) { console.log('Something in viewer was updated, check/update button state here'); }
};
viewer.toolbar.updateItem('$pdfExportButtonKey', xlsxExportButton); //from now button will behave as described in new properties

Description: Removes a custom toolbar item from the toolbar. To remove the default one, you should use the updateLayout function.

Type: String: key

Example:

viewer.toolbar.removeItem('$pdfExportButtonKey');

Description: Toggles the sidebar panel (hides or shows it). If no parameter is passed, works as toggle.

Type: boolean

Example:

viewer.toggleSidebar();//hide sidebar

viewer.toggleSidebar(true);//show sidebar

Properties

Description: Gets the currently displayed page number.

Syntax: viewer.currentPage

Example:

console.log(viewer.currentPage())

Return Value: An integer representing currently displayed page number.

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.