ActiveReports 15 .NET Edition
ActiveReports 15 User Guide / Preview Reports / JavaScript / JSViewer API
In This Topic
    JSViewer API
    In This Topic

    Initialization Options

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

    action

    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)

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

    availableExports

    Description: The array of export types available via the Export functionality of JSViewer. By default, the Mht, Pdf, Tiff, Xls, Xlsx, Csv, Doc, Docx, Json, and Xml exports are available for Page/RDL reports. The XlsxData and CsvData export options are also available for Page/RDL reports.

    For Section reports, the Mht, Pdf, Tiff, Xls, Xlsx, Rtf, and Txt exports are available by default.

    Type: Array

      
    Sample code
    Copy Code
    availableExports: ['Xml', 'Pdf', 'XlsxData', 'CsvData']
    

    displayMode

    Description: Set up single page or continuous page.

    Type:  String

    Accepted Value: 'single', 'continuous'

    Sample code
    Copy Code
    displayMode: 'Continuous'
    
     
    

    documentLoaded

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

    Type: function()

    Returns: Void

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

    element

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

    Type: String

    Sample code
    Copy Code
    element: '#viewerContainer'
    

    error

    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)

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

    locale

    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)

    Sample code
    Copy Code
    locale: 'ja-JP'
    

    localeData

    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

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

    localeUri

    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

    Sample code
    Copy Code
    localeUri: './custom-locale.json'
    

    Sample content of 'custom-locale.json':

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

    panelsLocation

    Description: Sets the location of the sidebar panel to the left side ('toolbar') or to the right side ('sidebar') of JSViewer. The default value is 'toolbar'.

    Type: String

    Accepted Value: 'toolbar', 'sidebar'

    Sample code
    Copy Code
    panelsLocation: 'sidebar'
    

    parametersPanel

    Description: Specifies the parameters panel settings.

    Type: String

    Sample code
    Copy Code
    parametersPanel: {
        * location: 'top'
    };
    

    renderMode

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

    Type: String

    Accepted Values: 'Galley', 'Paginated'       

    Sample code
    Copy Code
    renderMode: 'Galley'
    

    reportID

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

    Type: String

    Sample code
    Copy Code
    reportID: 'AnnualReport.rdlx'
    

    reportLoaded

    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)

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

    reportParameters

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

    Type: Array

    Sample code
    Copy Code
    reportParameters: [{ name: 'ReportParameter1', values: ['1']}]
    

    reportService

    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.

     

    Sample code to hide the default error panel
    Copy Code
    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

    backToParent()

    Description: Makes the viewer display the parent report of the drill-down report.
    Return type Description: Void

    Sample Code
    Copy Code
    viewer.backToParent()
    

    create()

    Description: Creates a new instance of the Viewer and renders it in the specified DOM element.
    Argument types Description:
    params – all properties
    Return type Description:
    Void

    Sample Code
    Copy Code
    <div id="viewerContainer">
    const viewer = GrapeCity.ActiveReports.JSViewer.create({
        element: '#viewerContainer,
        reportID: 'Report.rdlx',
        availableExports: ['Xml', 'Pdf'],
        // other properties
    }); 
    

    destroy()

    Description: Removes the viewer content from the element.
    Return type Description: Void

    Sample code
    Copy Code
    viewer.destroy()
    

    export(exportType, callback, saveAsDialog,settings)

    Description: Exports the currently displayed report
    Argument types description:

    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

    saveAsDialog: Indicates whether the save as dialog should be shown immediately once the export result is ready

    settings: The export settings are available for RenderingExtensions

    Return type description: Void

    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.

    Sample code
    Copy Code
    viewer.export('Pdf', downloadReport, true, { Title: '1997 Annual Report' })
     // function fetches the report from uri(callback function)
     var downloadReport = function (uri) {
     var newWin = null;
     // open uri in new window
     try {
           newWin = window.open(uri);
         } catch (e) { }
     // if browser rejects opening new window, open uri in current window
     if (!newWin) {
      window.location = uri;
     }
     };
    

    getToc()

    Description: Obtains the report TOC.
    Return type description:
    TOC Tree

    Sample code
    Copy Code
    console.log(viewer.getToc())
    

    goToPage(number, offset, callback)

    Description: Makes the viewer to display the specific page. Page numeration starts with 1.
    Argument types description:

    number: The number of pages to go to

    Return type description: Void

    Sample code
    Copy Code
    var pageNumber = 3;
    viewer.goToPage(pageNumber);
    

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

    Description: Opens a report.
    Argument types description:

    reportID: String(reportName)

    reportParameters: Array of Reports

    Return type description: Void

    Sample code
    Copy Code
    const reportName = "Report.rdlx";
    viewer.openReport(reportName);
    //Or
    //viewer.openReport(reportsArray[0]);
    

    print()

    Description: Prints the currently displayed report if any.
    Return type description:
    Void
               
    Sample code
    Copy Code
    viewer.print()
    

    refresh()

    Description: Refreshes the report preview
    Return type description:
    Void

    Sample code
    Copy Code
    viewer.refresh()
    

    GrapeCity.ActiveReports.JSViewer.version

    Description: A string that represents the current version of the JSViewer.
    Return type description:
    String

    Sample code
    Copy Code
    console.log(GrapeCity.ActiveReports.JSViewer.version)
    

    viewer.toolbar.desktop.addItem(button)

    Description: Adds a custom toolbar item (button) to the desktop's toolbar. Similarly,

    For fullscreen: viewer.toolbar.fullscreen.addItem()
    For mobile: viewer.toolbar.mobile.addItem()

    Argument types description: Belongs to ToolbarItem type, where

    type ToolbarItem = { key: string; /** * @deprecated use icon instead */ iconCssClass?: string; icon?: Icon; text?: string; title?: string; checked?: boolean; enabled?: boolean; action?: (curr?: ToolbarItem) => Partial | void; onUpdate?: (args: ChangedEventArgs, curr: ToolbarItem) => Partial | void; } ;

    Return type description:
    item: ToolbarItem

    Sample code
    Copy Code
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
    var pdfExportButton = {
    key: '$pdfExportButtonKey',
    iconCssClass: 'fa fa-file',
    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.desktop.addItem(pdfExportButton);
    // OR
    var btn = {
    key: '$openDesigner',
    iconCssClass: 'fa fa-folder',
    text: 'ClickToSave',
    enabled: true
     };
    viewer.toolbar.desktop.addItem(btn);
    

    viewer.toolbar.desktop.removeItem(buttonKey)

    Description:   Removes an existing item from the desktop's toolbar. Similarly,

    For fullscreen: viewer.toolbar.fullscreen.removeItem()
    For mobile: viewer.toolbar.mobile.removeItem()

    Argument types description: String
    Return type description: String

    Sample code
    Copy Code
    viewer.toolbar.desktop.removeItem('$pdfExportButtonKey');
    // pdfExportButtonKey is the button added using addItem() method
    

    viewer.toolbar.desktop.layout(layout)

    Description: Sets the keys of the visible desktop's toolbar items and their order. Similarly,

    For fullscreen: viewer.toolbar.fullscreen.layout()
    For mobile: viewer.toolbar.mobile.layout()

    Argument types description: Array of layout buttons

    Return type description: String

    Sample code
    Copy Code
    // Change the layout of the toolbar - change the positions of buttons in the toolbar
    var layout = ["$navigation", "$split", "$refresh", "$split", "$history", "$split", "$mousemode", "$zoom", "$fullscreen", "$split", "$print", "$singlepagemode", "$continuousmode", "$galleymode"]
    viewer.toolbar.desktop.layout(layout);
    

    viewer.toolbar.toggle(Boolean value)

    Description: Toggles the toolbar visibility (hides or shows the toolbar).

    Argument types description: boolean

    Return type description: Pass true to switch toolbar ON, and vise-versa. Do not pass any value to toggle visibility

    Sample code
    Copy Code
    viewer.toolbar.toggle(false);//hide toolbar
    viewer.toolbar.toggle(true);//show toolbar
    

    viewer.sidebar.toggle(Boolean value)

    Description: Toggles the sidebar visibility (hides or shows the sidebar).

    Argument types description: boolean

    Return type description: Pass true to switch sidebar ON, and vise-versa. Do not pass any value to toggle visibility

    Sample code
    Copy Code
    viewer.sidebar.toggle(false); //hide sidebar
    viewer.sidebar.toggle(true); //show sidebar
    

    viewer.toolbar.desktop.getKeys()

    Description: Returns identifiers of default and added buttons in the order in which they will be displayed in the toolbar.

    Return type description: String

    Sample code
    Copy Code
    // get the order of keys and reverse it
    viewer.toolbar.desktop.layout(viewer.toolbar.desktop.getKeys().reverse())
    

    Properties

    currentPage()

    Description: Gets the currently displayed page number.
    Return type description:
    An integer representing currently displayed page number

    Sample code
    Copy Code
    console.log(viewer.currentPage())
    

    pageCount()

    Description:  Gets the page count of the currently displayed report.
    Return type description:
    An integer representing page count

    Sample code
    Copy Code
    console.log(viewer.pageCount())
    
    See Also