SharpShooter Reports.WinRT: viewer API

SharpShooter Reports.WinRT viewer API

The basic properties and methods

Properties

  • ReportName sets the name for the report to be rendered. The report with a given name should be registered by ReportManager in WCF Report Service. The default value is empty. The value is mandatory for successful rendering.
  • ServiceUrl sets the full path to WCF Report Service. The default value is empty. The value is mandatory for successful rendering.

It has the following syntax:

<protocol>://<server>:<port>/<path>/<ServiceName>.svc

where

protocol –a protocol used: http or https (if SSL is used). The value is mandatory.

server – a name of the server with the deployed report service. The value is mandatory.

port – a port used by report service.  A port indication can be omitted if the default ports are used (80 for http or 443 for https).

path – a path to report service. The value can be empty if the service is located in the root of site or application.

serviceName – a name of report service. The value is mandatory.

The examples of correct URL’s:

http://localhost:5555/ReportService.svc

https://www.MyServer.com/Services/MyReportService.svc

If the service name and the configuration of report service are set correctly, then after the server application has been started,

the welcome page of svc service is displayed in a web browser when accessing the specified service URL.


  • DebugMode – specifies the level of detail for error messages. The default value is “Simple”.

It can have the following values:

Value

Description

Simple 

Informs a user that an error has occurred. No details displayed.

Message 

The error message is displayed.

Full 

The full information on the error is displayed (includes the error message and stack trace, if available).

 

  • Parameters – allows setting report parameters (see “Parameters” section).
  • ExportMode – allows setting export mode. The default value is “SaveToFile”.

It can have the following values:

Value

Description

UserSelected 

When performing an export a user can choose from two options: either use the sharing mechanism or simply save the result to a file.

Share 

After export, the result will be passed to share charms for further processing. The user will need to select an application to receive the result of exports.

SaveToFile 

After export, the result will be saved to a file. The user will need to select the file type to save the result to.

For more information refer to “Export” section.

  • HideDefaultToolbars – allows hiding the default toolbars. This property can be used when customizing the interface. For more information on customizing see “Appearance customization” section.
  • RestoreBookmarks – sets the value defining whether the viewer should open the last viewed page when re-opening the bookmark tree. If the set value is “false”, then the root bookmark folder will be used.

Methods

  • RenderDocument() – starts report rendering. It is mandatory to set the value for ReportName and ServiceUrl properties for successful rendering.
  • RenderReport(HistoryOptions historyOption) –  performs the same action as RenderDocument  method, but additionally allows affecting  the navigation history.
  • Print() – prints the current report.
  • Export(string exportFormat, ExportMode mode) – exports the current report to the specified format (exportFormat), processes the export results according to the specified mode  (mode: a UserSelected value cannot be used in this function).

Events

  • DocumentLoaded – occurs after the document is loaded.  The link to the document can be retrieved through event arguments. When the event occurs, the document’s pages do not have any content yet. Once the loading of content is initiated, a PageLoaded event is triggered
  • PageLoaded – occurs after the page content has been retrieved. The link to the document (that already has the content loaded) and the number of loaded page can be retrieved through event arguments.
  • HandlingError – is fired whenever any error occurs. The report viewer switches to Error View in this case.
  • ExportStarted – occurs at export initialization. It is possible to set “ShowToastNotification = True” in event arguments if toast notification is required while performing export (The toast notification is used by default when SaveToFile export value is set and it doesn’t show when Share value is selected). It is also possible to set State value which will be passed to the ExportEnded event.
  • ExportEnded – occurs after the export process is ended.  A State value that was set in ExportStarted event can be passed through the arguments.
  • PrintStarted –  fires before the printing is initiated.
  • PrintEnded – fires after the printing is ended.
  • HyperlinkClick – occurs upon click on the element that contains hyperlink.

Optimization mechanisms

                These mechanisms allow reducing page loading time when switching between pages with the help of preload function, as well as reducing memory usage when viewing large size reports by removing adjacent pages located out of user’s field of view.

These mechanisms are configured through the following properties:

  • PreloadedPageCount – specifies number of pages to be preloaded before and after the current page in order to speed up the process of switching between pages.
  • UsePageBuffer – enables or disables the limitation on the number of pages loaded into memory.
  • PageBufferLengthAfter – specifies number of pages after the current page that will not be unloaded from memory.
  • PageBufferLengthBefore – specifies number of pages before the current page that will not be unloaded from memory.

Hyperlink click handling

                Report Viewer supports three types of hyperlinks:

  • Bookmark – a link to some report element. This type of link is automatically handled by the viewer.
  • Hyperlink, represented as standard URL – is passed to a system for resource opening. For example, http-link is opened in the web browser, mailto-link is opened in the mail client application and so on.
  • Any other value which cannot be correctly processed by the viewer. In such case link handling procedure is performed by the user.

ReportViewer uses special HyperlinkClick event for custom user links or custom handling of standard links. For example, if we need to go to the first page of the report using “Back” hyperlink, we can do this with the following code. To begin with, we need to subscribe to an event:

// Subscribe for the event
reportViewer.HyperlinkClick += reportViewer_HyperlinkClick;

Then, using the event handler we can invoke GoToFirstPageCommand so that the viewer is switched to the first page:

private void reportViewer_HyperlinkClick(object sender,
                PerpetuumSoft.WinRT.Viewer.ReportHyperlinkEventArgs e)
       {
           if (e.Hyperlink.ToLower() == "back")
           {
               reportViewer.Commands.GoToFirstPageCommand.Execute(null);
               e.Handled = true;
           }
       }

NOTE: Event arguments are used for getting the link value. To make the viewer not to handle such links in a usual way, we need to set “Handled” property as ‘true” after handling.

Drill Through

Using a Drill Through functionality we can retrieve detailed report information. The reports should be properly prepared to take full advantage of Drill Through. A user should create at least two reports: the first report will represent a truncated form, while the other will be a detailed description of some section in a represented truncated report. Moving from one report to another is performed with the help of hyperlinks. To be able to do this a user should add hyperlinks to a report and subscribe to a HyperlinkClick event. The logic of moving from one report to another is implemented in HyperlinkClick handler:

reportViewer.HyperlinkClick += reportViewer_HyperlinkClick;
...
void reportViewer_HyperlinkClick(object sender, PerpetuumSoft.WinRT.Viewer.ReportHyperlinkEventArgs e)
        {
            if (e.Hyperlink == "GotoDetailedReport")
            {
                reportViewer.ReportName = "DetailedReport";
                reportViewer.RenderReport();
                e.Handled = true;
            }
        }

Navigation history

Navigation history allows a user to navigate between the reports. While previewing the report in the viewer it is possible to navigate

between reports using Drill Through function or by setting the other report name inside the code and invoking RenderReport method.

When referring to the RenderReport method, the currently displayed report is placed in the navigation history so that a user is able to

return to it either by clicking on the appropriate button of the viewer,

 

or by executing one of the following viewer commands:

reportViewer.Commands.ForwardCommand.Execute(null);
 
reportViewer.Commands.BackwardCommand.Execute(null);

The RenderReport method with the following parameter is invoked in case a user needs to move to the next report without adding the previous report to navigation history:

reportViewer.RenderReport(PerpetuumSoft.WinRT.Viewer.HistoryOptions.NotSave)

ReportViewer commands

ReportViewer provides a user with a set of commands (Commands property).

Each command implements IExtendedCommand interface (which is inherited from ICommand). The interface has an additional GetIsSupported() method, which allows a user to find out whether this command is supported.

Command

Function

Applied to

Commands for report generation

RenderReportCommand 

(requires RenderOptions as parameter)

To generate a report

Invokes in RenderReport() method

RefreshReportCommand

 

To re-generate the current report

RefreshReportButton, ReportParametersMenu

Commands for navigation

BackwardCommand

Go to the previous report in navigation history

BackwardButton, ReportNaviagationPanel

ForwardComand

Go to the next report in navigation history

ForwardButton, ReportNaviagationPanel

GoToFirstPageCommand

 

Go to the first page of the current report

GoToFirstPageButton, ReportNaviagationPanel

GoToLastPageCommand

 

Go to the last page of the current report

GoToLastPageButton, ReportNaviagationPanel

GoToNextPageCommand

 

Go to the next page of the current report

GoToNextPageButton, ReportNaviagationPanel

GoToPreviousPageCommand

 

Go to the previous page of the current report

GoToPreviousPageButton, ReportNaviagationPanel

Search commands

FindTextCommand

 

Finds the first occurrence of text or word specified in the search field

FindButton,

ReportSearchPanel

FindNextTextCommand

 

Finds the next occurrence of text or word specified in the search field (The search is cyclic. If the end of the document is reached, the search is started from the beginning)

FindNextButton,

ReportSearchPanel

FindPreviousTextCommand

 

Finds the previous occurrence of text or word specified in the search field (The search is cyclic. If the beginning of the document is reached, the search is started from the end)

FindPrevButton,

ReportSearchPanel

Commands for report viewing

SwitchToSemanticZoomViewCommand

 

Switches to SemanticZoom View mode

SemanticZoomViewButton, ReportViewModePanel

SwitchToGridViewCommand

 

Switches to Grid View mode

GridViewButton, ReportViewModePanel

SwitchToFlipViewCommand (requires a page index as parameter)

 

Switches to Flip View mode

FlipViewButton, ReportViewModePanel

ShowThumbnailsPanelCommand

 

Displays the thumbnail panel

ThumbnailsButton, ReportViewModePanel

ShowBookmarksTreeCommand

 

Displays the bookmark tree (if available)

BookmarksButton, ReportViewModePanel

GoToPageContentCommand (requires a page index as parameter)

Switches from Thumbnail to Grid View mode

ViewerGridItem for Grid View and thumbnail panel


Other commands

PrintCommand

 

Sends a document to print (prepares a page to be printed)

PrintButton, ReportPrintPanel

ShowParametersPanelCommand

 

Displays panel with report parameters (if available)

ParametersButton, ReportParametersMenu

Add Feedback