Version

ReportPlus Web App

Embedding the ReportPlus Dashboard Viewer widget in an application

The web application referred to as ReportPlus Web App is an ASP.NET MVC web application. The main webpage hosts a jQuery widget named igDashboardViewer, which is responsible for interacting with the backend and rendering a requested dashboard.

This same widget can be hosted by other web applications in the same way it’s hosted by the ReportPlus Web App’s main webpage. The following sections will explain how to accomplish this.

Dependencies

To use the igDashboardViewer widget, the host web application must reference:

  • jQuery 1.9.1 or greater

  • jQuery UI 1.10.2 or greater

  • Modernizr 2.6.2 or greater

  • IgniteUI 16.2 or greater (Data Visualizations library is not needed. Only reference infragistics.core.js and infragistics.lobs.js)

Note
NOTE

It is recommended that you copy /dist/Vendor folder and its contents from the ReportPlus Server application root directory.

Steps

The ReportPlus Dashboard Viewer code has dependencies to controls which render the visualization for dashboards. Some of these controls include different types of charts, grids, and gauges.

To embed ReportPlus Dashboard Viewer inside a host web application, follow these steps:

  1. In the host application project, create a new folder and give it a name (e.g., rplus-embedded). This folder is where all the required assets (CSS, JavaScript, etc.) will be copied over from the ReportPlus Server.

  2. In the ReportPlus Server application root directory, look for the folder named rplus-embedded. This folder contains the minified and bundled version of the ReportPlus Dashboard viewer along with some .png and .svg files. Copy all of the files in this folder into the folder created during step 1.

    The source map files, *.map, facilitate debugging of the Dashboard Viewer in the browser’s console; these files are optional.

  3. In the ReportPlus Server application root directory, look for the folder named /dist/Vendor. This folder contains all the 3rd party dependencies for the Dashboard Viewer. Copy the Vendor folder and all of its contents into the folder created in step 1.

  4. Copy the themes folder from ReportPlus Server to your local web project. Any custom themes used also need to be copied to this folder. If a custom theme is missing, the default (The Blues Theme) will be used as a fallback.

  5. Reference the following stylesheets and scripts on the webpage where ReportPlus will be embedded:

    <link href="~/rplus-embedded/Vendor/igniteui/infragistics.css rel="stylesheet" />
    <link href="~/rplus-embedded/Vendor/igniteui/infragistics.theme.css" rel="stylesheet" />
    <link href="~/rplus-embedded/embedded.bundle.css" rel="stylesheet" />
    <script src="~/rplus-embedded/Vendor/jqueryui/jquery.min.js"></script>
    <script src="~/rplus-embedded/Vendor/jquery/jquery-ui-min.js"></script>
    <script src="~/rplus-embedded/Vendor/modernizr/modernizr.min.js"></script>
    <script src="~/rplus-embedded/Vendor/jqueryui/jquery.touchSwipe.min.js"></script>
    <script src="~/rplus-embedded/Vendor/igniteui/infragistics.core.js"></script>
    <script src="~/rplus-embedded/Vendor/igniteui/infragistics.lob.js"></script>
    <script src="~/rplus-embedded/rplus.embedded.bundle.js"></script>

Instantiate the igDashboardViewer jQuery widget.

$(function() {
  var defaultDashboard = 1;
  $("#dashboard").igDashboardViewer({
     dashboardSettings: {
        definitionUri: "[repository]" + defaultDashboard,
        serviceEndpointUri: serverUrl,
    });
});

Widget parameters

The widget can be instantiated with the following parameters:

  • definitionUri: the URI that specifies the dashboard to be rendered. The URI includes two parts:

    • The [repository], which means the browser is trying to open a dashboard saved in ReportPlus server repository.

    • The [Id] of the dashboard to load from the server repository.

  • serviceEndpointUri: The URL to the server hosting the embedding service. Accepts both HTTP and HTTPS.

  • hideAppHeader: Optional flag (defaults to false) to show or hide the header bar for the ReportPlus Dashbaord viewer.

  • showDashboardFilters: Optional flag (defaults to false) to show or hide the dashboard filter control.

  • hideSourceIcon: Optional flag (defaults to false) to show or hide the data source icon. When visible, the end user will be allowed to change their data source configuration for the dashboard. Any changes will be saved to the ReportPlus Server.

  • enableChangeVisualization: Optional flag (defaults to false) to show or hide the change visualization button. When visible, the end user will be able to switch between the normal state of a visualization and alternate visualizations of the data.

  • dashboardParameters: Optional (defaults to empty) of key value pairs that corresponds to one or more dashboard filters and the default values to filter data by. When applying filters to string or numeric columns the key is the name of the column being filtered and the filter values is an array of values from the column:

    "SingleSelection": ["Sales"],
    "MultiNoUnsel": [2, 4, 9, 1]

    When using a date filter, a DateFilterRule ("LastWeek", "LastYear", "CustomRange", etc.) should be specified instead. When using the "CustomRange", DateFilterRule, the "To" and "From" parameters should be specified with their values set to valid dates:

    "DateFilterRule": "CustomRange",
    "From": "8/29/2016 12:00:00 AM",
    "To": "12/5/2016" 12:00:00 AM"
  • securityToken: Optional string (defaults to null) that is only required when using SSO-based authentication. The token must be serialized as a JSON Web Token (JWT) with the correct supported claims for ReportPlus.

  • showExportButton: Optional boolean (defaults to false) to show or hide the export data button. When visible, the end user will be able to export the dashboard data to a csv file.

  • exportSettings: Optional object of Boolean flags which is used to apply granular control over which export settings are available to the end user. The available settings are listed below:

    • CsvExportEnabled: allow a user to export the dashboard to CSV.

    • ExportEnabled: enable or disable all exporting.

    • ImageExportEnabled: allow a user to export the dashboard to an image.

    • ImageProxyEnabled: allows a user to provide a URL for the company logo when exporting as PDF or PowerPoint.

    • PdfExportEnabled: allows a user to export the dashboard to PDF.

    • PowerPointEnabled: allows a user to export the dashboard to PowerPoint.

    • RplusFileExportEnabled: allows a user to export the entire dashboard as an Rplus file, including any local data sources that may be used.

    • ReportSettingsEditingEnabled: allows a user to edit user-specific settings when exporting to PowerPoint or PDF document. These settings include the number of tables and rows that can be displayed for a grid in the document, the logo displayed on each page or slide, the name of the company and author of the document, and the company color used in the document.

Generating the Security Token

To use Single Sign On (SSO) token authentication when embedding ReportPlus, a JSON Web Token (JWT) must be generated first. For more information on the JSON Web Token (JWT) see https://jwt.io/introduction/.

Creating a Security Token

To create the required JSON Web Token (JWT), create an application user using the standard ReportPlus user Interface. Go to the root folder in the enterprise repository and click on permissions. When the dialog is finished loading, select the apps tab and click on create a new app user.

Web-SSO-Token-ReportPlus-Permissions-Dialog

A security token key must be generated which is used to encrypt the JSON Web Token (JWT). To generate the token, a description and URL must be provided. To authenticate the security token, ReportPlus will verify the token was encrypted with the correct key and the specific URL matches the incoming request.

Web-Security-Security-Key

Once the key is generated, the JSON Web Token (JWT) must be constructed with the following claims included:

Claim

Description

version

The version of the app token, 1 is the current version.

userIdentifier

The User GUID provided when ReportPlus generated the token.

applicationName

The hosted (embedding) application name.

hostUri

The URL for the hosted (embedding) application.

Sample Server Code

The provided embed sample is an ASP.NET MVC application that includes the custom helper class TokenFactory that makes it easier to generate the JSON Web Token (JWT), this class has a dependency on the System.IdentityModel.Tokens.Jwt NuGet package provided by Microsoft. If preferred, any third party library to generate JSON Web Tokens. See https://jwt.io/ for more details about available libraries for generating security tokens.

public static class TokenFactory
    public static string CreateToken(TokenParameter parameter)s
    {
        var token = new JwtTokenService(parameter.Secret);
        token.CreateSigningCredentials();
        token.AddValue("version", 1);
        token.AddValue("userIdentifier", parameter.UserIdentifier);
        token.AddValue("applicationName", parameter.ApplicationName);
        token.AddValue("HostUri", parameter.HostUri);
        return token.SerializeToken();
    }