ActiveReports 12 Server User Guide
View Reports Using the HTML5 Viewer
ActiveReports 12 Server User Guide > How To > View Reports Using the HTML5 Viewer

This topic walks you through how to initialize the HTML5 Viewer in JavaScript. It also provides details on all public initialization options, plus all of the public API methods and properties that you can use with the viewer after you initialize it.

Initializing the HTML5 Viewer

  1. Copy the following files from the ...\ActiveReports 12 Server\SDK\HTML5 Viewer.Source folder to a folder accessible from the target HTML page:
    • GrapeCity.ActiveReports.Viewer.Html.js
    • GrapeCity.ActiveReports.Viewer.Html.min.js
    • GrapeCity.ActiveReports.Viewer.Html.cs
  2. In the target HTML page, add the references to the GrapeCity.ActiveReports.Viewer.Html.css, GrapeCity.ActiveReports.Viewer.Html.js and its dependencies:
    • jQuery 1.9.0 or higher
    • Bootstrap 3.0
    • Knockout.js 2.3.0 or higher
    Note: You can access the dependencies like jQuery in a Content Delivery Network (CDN) or copy them locally.
    HTML
    Copy Code
    <link rel="stylesheet" href="GrapeCity.ActiveReports.Viewer.Html.css" >
    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
    <script src="//netdna.bootstrapcdn.com/bootstrap/3.0.3/js/bootstrap.min.js"></script>
    <script src="http://cdnjs.cloudflare.com/ajax/libs/knockout/2.3.0/knockout-min.js" type="text/javascript"></script>
    <script src="Scripts/GrapeCity.ActiveReports.Viewer.Html.js" type="text/javascript"></script>
    <script type="text/javascript">
    </script>
    
  3. In the target HTML page, add the DIV element that will contain the HTML5 Viewer.
    HTML
    Copy Code
    <div id="viewer" style="width:600px;height:480px;"></div>                                               
    
  4. Add the following code to initialize the HTML5 Viewer. The code might vary depending on the technology that you use to develop the HTML5 Viewer component. To learn how to get a security token for the reportService, see Get a Security Token.
    Javascript
    Copy Code
    $(function ()
    {
       var viewer = GrapeCity.ActiveReports.Viewer(
       {
          element: '#viewer',
          report: {
             id: "myreport"
    
          },
          
          reportService: {
              url: 'http://myAR12server.com/ReportService.svc/json/', 
              securityToken: securityToken, 
              resourceHandler : 'http://myAR12server.com/cache/'
          },
          uiType: 'desktop',
          documentLoaded: function reportLoaded()
          {
             console.log(viewer.pageCount);
          },
          reportLoaded: function (reportInfo)
          {
             console.log(reportInfo.parameters);
          },
    
          error: function (error)
          {
             console.log("error");
          }
    
       });
    });
    

    Alternatively, you can use the REST API endpoint URL for the HTML5 Viewer initialization.

    Javascript
    Copy Code
    $(function ()
    {
       var viewer = GrapeCity.ActiveReports.Viewer(
       {
          element: '#viewer',
          report: {
             id: "myreport"
    
          },
          
          reportService: {
              url: 'http://myAR12server.com/api/', 
              securityToken: securityToken, 
              resourceHandler : 'http://myAR12server.com/cache/'
          },
          uiType: 'desktop',
          documentLoaded: function reportLoaded()
          {
             console.log(viewer.pageCount);
          },
          reportLoaded: function (reportInfo)
          {
             console.log(reportInfo.parameters);
          },
    
          error: function (error)
          {
             console.log("error");
          }
    
       });
    });
    
  5. Add the following code to the system.webServer section of the web.config file of your ActiveReports 12 Server web site.
    XML
    Copy Code
    <system.webServer>
    
            <httpProtocol>
    
                    <customHeaders>
    
                            <add name="Access-Control-Allow-Origin" value="*" />
    
                            <add name="Access-Control-Allow-Headers" value="AuthToken, Authorization, Origin, Content-Type, Accept, X-Requested-With" />
    
                    </customHeaders>
    
            </httpProtocol>
    
    ...
    
    </system.webServer>
    

Initialization Options

The following options can be set during initialization or at runtime while working with the HTML5 Viewer.

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 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 12 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 log in to ActiveReports Server.

Type: String

Example:
reportService: {
   securityToken: '42A9CD80A4F3445A9BB60A221D042FCC'
};

reportService.resourceHandler

Description: The URL of the ActiveReports Server resource handler.

Type: String

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

report

Description: The report that is displayed in ActiveReports 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:

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, Excel, and CSV 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

print

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

search

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();