416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
Dashboard v5.0

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

Using the HTML Viewer in ASP.NET Applications

Hide navigation
RSS
Modified on Thu, 06 Mar 2014 01:28 PM Categorized as HTML, Level-Advanced, Level-Intermediate, Viewer
Click to return to: Documentation | Using the Dashboard Viewer in Your Applications


Overview

This article shows how to create a basic ASP.NET Web Application project that will embed the Dundas Dashboard HTML Viewer. Technically, there isn't a specific HTML Viewer control for you to embed - the HTML Viewer is just a URL that produces HTML5 output. So, to integrate HTML5 dashboards into your own ASP.NET application, you simply add an iframe to your ASP.NET web page and set its src attribute to point to the appropriate HTML Viewer URL. However, the detail that needs to be considered is the issue of logging in, such as creating a server-side Dundas Dashboard login session. This article shows two different ways to handle login.

Setup

Prerequisites

Make sure you have the following prerequisites installed on your computer:

  • Visual Studio 2010 or Visual Studio 2010 Express
  • Microsoft .NET Framework 4.0
  • IIS web server running ASP.NET 2.0 or greater
  • Dundas Dashboard 4.0 or greater

Add a viewer user in Dundas Dashboard

The ASP.NET application will need to be able to log in to your Dundas Dashboard server via a specific local user account that has privileges to view dashboards. The source code which will be presented later is actually hard-coded with an expected local user name and password. You can change these credentials in the code (as will be shown later), or log in to Dundas Dashboard as an administrator and create the expected local user account as follows:

  • Username: viewer
  • Password: 1234
  • Role: Viewer. Make sure you uncheck the option “Reserve a viewer license for this user”. This will set up the user as a floating viewer.

See the articles on Managing Users and Licensing for more details.

Obtain the GUID of a dashboard for viewing

The ASP.NET application will essentially load an existing dashboard for viewing. The source code presented later is hard-coded with an example dashboard GUID which you must replace (as will be shown later).

For now, simply log in and obtain the GUID of any existing dashboard on your Dundas Dashboard server. Save the GUID value in Notepad for later use.

See the example from this article which shows how to obtain the GUID of the Sonatica Executive dashboard (e.g. 7bcebd59-d425-4f29-9ea4-73033d50d515).

Creating the web application

Create a new ASP.NET Web Application project in Visual Studio

Launch Visual Studio and create a new project as follows:

  1. In the New Project screen, select the option to create a new ASP.NET Empty Web Application project.
  2. Enter the following settings, then click OK:
    • Name (of project): HtmlViewerInWebPage
    • Location: C:\visual studio 2010\Projects (or location of your choice)
    • Solution name: HtmlViewerInWebPage
    • Create directory for solution: Yes
      New Project in Visual Studio.
  3. The HtmlViewerInWebPage project and solution are created. In the project, add a New Item of type Web Form and name it as Default.aspx.
  4. Add references to the following assemblies from the Program Files\Dundas Data Visualization Inc\Dundas Dashboard\{InstanceName}\SDK\lib\Server\ folder:
    • Dundas.Dashboard.Extensibility.Server.dll
    • Dundas.Dashboard.Server.Integration.dll
    • ICSharpCode.SharpZipLib.dll

A typical project structure will look like this:

Typical structure for the ASP.NET Web Application project.

Typical structure for the ASP.NET Web Application project.


Add an iframe to the Default.aspx web page

Add an iframe element to the Default.aspx markup:

...
<iframe id="frame1" style="width:980px;height:750px;" runat="server"></iframe>
...

Add code-behind to the Default.aspx web page

Follow the steps below to add code-behind to the Default.aspx web page. The code demonstrates two options for logging in. Option 2 (creating a server-side login session) is enabled by default.

  1. Open the Default.aspx.cs file to edit the code-behind so that it resembles the code shown below.
  2. Change the serverUrl value to the server URL for your Dundas Dashboard instance. Note that this URL must have the slash character at the end.
  3. Change the dashboardId value to the GUID of a dashboard to be loaded (which you obtained previously).
  4. Compile and build the solution.

The viewerUsername and viewerPassword values should already be correct if you followed all of the setup steps presented earlier.

Tip: If you encounter formatting problems when copying the following code listing to Visual Studio, try copying and pasting to Microsoft WordPad first, then copy and paste from WordPad to Visual Studio.

using System;
using Dundas.Dashboard;
using Dundas.Dashboard.Integration;
using Dundas.Dashboard.Integration.Business;

namespace HtmlViewerInWebPage { public partial class Default : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { // This is the HTML Viewer URL which we will set later. string htmlViewerUrl = string.Empty;

// Your Dundas Dashboard server URL. Must have a slash character at the end. string serverUrl = "http://dashsvr:7001/";

// Your dashboard to be displayed. string dashboardId = "7bcebd59-d425-4f29-9ea4-73033d50d515";

// Use automatic login or create a server-side login session. bool useHtmlAutoLogin = false;

if (useHtmlAutoLogin) { // OPTION 1: USE HTML AUTO LOGIN (must be enabled from DD config file)

// Compose the HTML Viewer URL. htmlViewerUrl = string.Format("{0}HtmlViewer.ashx?Dd_ContentId={1}", serverUrl, dashboardId); } else { // OPTION 2: CREATE SERVER-SIDE LOGIN SESSION

// Initialize the viewer username/password. string viewerUsername = "viewer"; string viewerPassword = "1234";

// If there are no more licenses, automatically delete other sessions. bool deleteOtherSessions = true;

// Attempt to log in using username and password. IntegrationHelper.ServerUri = new Uri(serverUrl); LoginStatus loginStatus = IntegrationHelper.LoginLocal(viewerUsername, viewerPassword, deleteOtherSessions);

// Ensure no failures are encountered logging in viewer user. if (loginStatus.LoginFailureReason != LoginFailureReason.None) { throw new ArgumentException("Could not create session: " + loginStatus.LoginFailureReason.ToString(), "dwSessionId"); }

// Retrieve the login session's Id. Guid sessionId = loginStatus.SessionId;

// Compose the HTML Viewer URL. htmlViewerUrl = string.Format("{0}HtmlViewer.ashx?Dd_ContentId={1}&Dd_SessionId={2}", serverUrl, dashboardId, sessionId); }

// Set the iframe's src attribute. frame1.Attributes["src"] = htmlViewerUrl; } } }

Using automatic login

The automatic login option is useful if you plan on setting up a public demo or kiosk for displaying HTML5 dashboards without requiring users to log in first.

Referring to the previous section's code listing, in order to use Option 1 (automatic login), you must enable it not only in the code above but also in the Dundas Dashboard Configuration File.

Specifically, go to the HTML SETTINGS section near the end of the config file, uncomment the three HtmlAutoLogin keys and set their values as shown below:

...
  <key name="HtmlAutoLogin" value="True"/>
  <!-- Specifies the username used for the auto login.-->
  <key name="HtmlAutoLoginUsername" value="viewer"/>
  <!-- Specifies the password used for the auto login.-->
  <key name="HtmlAutoLoginPassword" value="1234"/>
...

Afterwards, you must restart the Dundas Dashboard website for the changes to take effect.

Testing the web application in a browser

You can now publish the web application project and test it from a web browser that supports HTML5 and SVG.

HTML5 dashboard displayed in an iframe.

HTML5 dashboard displayed in an iframe.


If you see a blank page, check the Notes section for troubleshooting tips.

Dashboard parameters

A typical dashboard displays KPIs that have public filters, and provides dashboard parameter controls (e.g. a dropdown list) for users to manipulate filter values. The example presented in this section shows how to control dashboard parameter values from the ASP.NET web application, which allows you to display HTML5 dashboards in a desired filtered state.

In this example, assume the availability of a KPI with the following definition:

  • KPI name: Downloads By Date
  • KPI measure: Number of Downloads
  • KPI dimension: Download Date (instant, datetime, appears on visualization/x-axis)
  • KPI dimension: Product SKU (instant, string, used for filtering)
  • KPI filter: Public, single-valued filter on Product SKU instant dimension
  • Preferred visualization: Line Chart

A dashboard displays this KPI along with a dashboard parameter control (dropdown list) which filters the data based on Product SKU. The dashboard parameter is named, Parameter1.

A filterable dashboard as viewed from within Dundas Dashboard.

A filterable dashboard as viewed from within Dundas Dashboard.


The above dashboard is shown in its default filter state. The sections that follow show how to append additional information to the HTML Viewer URL so that the HTML view of the dashboard will be displayed with its filter set to a specific value (e.g. SOSL):

Goal: Embedded HTML dashboard with filter set to a specific value.

Goal: Embedded HTML dashboard with filter set to a specific value.


Using Dd_Parameters

From the Default.aspx code-behind presented earlier, you can see that the HTML Viewer URL supports these URL query string parameters:

  • Dd_ContentId - Specifies the GUID of a dashboard.
  • Dd_SessionId - Specifies the GUID of a server-side login session.

Additionally, you can pass the following URL parameter which contains dashboard parameter/filter information:

  • Dd_Parameters - Dashboard parameter/filter information encoded as a (long) string.

The easiest way to determine the Dd_Parameters value which corresponds to a desired filter state is to:

  1. Log into Dundas Dashboard and view your (Silverlight) dashboard.
  2. Set the filter/parameter control values on the dashboard as desired.
  3. Go to the toolbar and click the Share button.
  4. Choose the Share this dashboard or mashup as a link for Silverlight or HTML option, then click Next.
  5. Under the HTML link to this Dashboard section, click Open this link in a new browser window.
  6. Copy the HTML Viewer URL from the browser's address bar and paste it into Notepad.

You can now copy the Dd_Parameters section of the HTML Viewer URL (e.g. from Notepad) and append it to the htmlViewerUrl variable in the Default.aspx code-behind. For example, add code such as this:

htmlViewerUrl += "&Dd_Parameters=...some long string...";

You can now publish and test the web application again to see the dashboard filtered with a specific value.

Determining Dd_Parameters programmatically

Suppose you want to set the filter value in the example dashboard to SOSL specifically. The following shows the code changes you need to make to the Default.aspx code-behind to achieve this result.

...
                // Compose the HTML Viewer URL.
                htmlViewerUrl = string.Format("{0}HtmlViewer.ashx?Dd_ContentId={1}&Dd_SessionId={2}", serverUrl, dashboardId, sessionId);
                htmlViewerUrl += "&" + GetParameterString(dashboardId);  
            }

// Set the iframe's src attribute. frame1.Attributes["src"] = htmlViewerUrl; }

private string GetParameterString(string dashboardId) { // Create a parameter collection. ParameterInfoCollection paramInfoColl = new ParameterInfoCollection();

// Create the parameter. ParameterInfo paramInfo = new ParameterInfo(); paramInfo.ParameterName = "Parameter1";

// Create a filter value. DashboardFilterValueData fvd = new DashboardFilterValueData(); fvd.SingleValue = "SOSL";

// Add filter value data to filter values. paramInfo.FilterValues.Add(fvd);

// Add parameter to collection. paramInfoColl.Add(paramInfo);

// Get the dashboard viewer URL corresponding to this dashboard and its filter state. Uri linkUri = IntegrationHelper.GetLinkUri(IntegrationHelper.ServerUri, new Guid(dashboardId), ViewerContentItemType.Dashboard, paramInfoColl); // Return just the Dd_Parameters section of the URL. string[] uriItems = linkUri.Query.Split('&'); return uriItems[3]; } } }

The above is just a simple example for the case of a single-value, instant dimension filter/parameter. For more details on this and other dashboard parameter scenarios, see the article on Passing Parameters from a ASP.NET Application to your Dashboard. That article concerns embedding the Silverlight Viewer but its information on handling parameters also applies here.

Notes

P3P issue with Internet Explorer

With Internet Explorer, if you see a blank page when trying to view a dashboard in the ASP.NET application, this could be the result of a P3P (Platform for Privacy Preferences) issue regarding hosting a page in an iframe that is in a different domain.

To workaround this issue (for IIS 7):

  1. Start IIS Manager.
  2. Navigate to and select your Dundas Dashboard instance (e.g. web site).
  3. In the Features View, double-click HTTP Response Headers.
  4. Right-click and select Add to add a custom HTTP response header:
    • Name: P3P
    • Value: CP="CAO DSP COR CURa ADMa DEVa PSAa PSDa IVAi IVDi CONi OUR OTRi IND PHY ONL UNI FIN COM NAV INT DEM STA"

If you are using IIS 6:

  1. Start IIS Manager.
  2. Right-click on your Dundas Dashboard web site or directory and select Properties.
  3. Go to the HTTP Headers tab.
  4. Click Add.
  5. Enter the Custom Header Name and Custom Header Value as in the case for IIS 7.

Handling long HTML Viewer URLs

If you are passing a lot of filter/parameter values in the query string, the resulting HTML Viewer URL may become too long, resulting in an error when you try to view the embedded dashboard.

In Dundas Dashboard 5.0.2 or later, you can use the IntegrationHelper method, GetShortLinkId, to obtain an id which can be used to compose a shortened URL for launching the HTML Viewer (similar to the URL links you get when you use the share functionality).

The GetShortLinkId method takes the dashboard ID, the content type, the parameters, and the base URL for where you want it to go. Include your query string parameter, viewer features, and anything else you want.

For example, with the returned id, you can compose short links such as:

  • go.ashx?l=id
  • HtmlViewer.ashx?l=id

Related topics


Click to return to: Documentation | Using the Dashboard Viewer in Your Applications

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2014 Dundas Data Visualization, Inc.