416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
This is the support page for the legacy Dundas Dashboard application. For assistance with the current Dundas BI application please click here.
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 Enhanced Viewer in Silverlight Applications

Hide navigation
RSS
Modified on Mon, 27 May 2013 01:32 PM Categorized as Samples, Viewer
Click to return to: Documentation | Using the Dashboard Viewer in Your Applications


Overview

This article shows how to create a bare-bones Silverlight Application using Visual Studio 2010 that will embed the Dundas Dashboard Enhanced Viewer. As well, the article shows how to control the visibility of elements in the viewer (e.g. hiding toolbar icons, hiding navigation pane, etc.) and passing parameters to a dashboard.

The code in this article is based on the Viewer Integration Sample which is included when you install Dundas Dashboard.

Setup

Prerequisites

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


Add a viewer user in Dundas Dashboard

The Silverlight 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 with option “Reserve a viewer license for this user” selected.

Once you've created the new user account, it is recommended to log in once as this user, and then log out.

See the article on Managing Users for more details.

Obtain the GUID of a dashboard for viewing

The Silverlight application will essentially load an existing dashboard into the viewer. 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 Silverlight application

Create a new Silverlight 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 Silverlight Application project.
  2. Enter the following settings, then click OK:
    • Name (of project): EnhancedViewerInSilverlight
    • Location: C:\visual studio 2010\Projects (or location of your choice)
    • Solution name: EnhancedViewerInSilverlight
    • Create directory for solution: Yes
      Creating a new Silverlight Application project in Visual Studio.
  3. In the New Silverlight Application dialog, leave the default settings, then click OK to add a new web application project to host the Silverlight control.
    Creating a Web Application project to host the Silverlight control
  4. For the Silverlight application project (EnhancedViewerInSilverlight), add references to the following assemblies from the Program Files\Dundas Data Visualization Inc\Dundas Dashboard\{InstanceName}\SDK\lib\Client\ folder:
    • Dundas.Dashboard.Client.dll
    • Dundas.Dashboard.Plugins.dll
  5. For the Web application project (EnhancedViewerInSilverlight.Web), 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
  6. Make sure that the web application project (EnhancedViewerInSilverlight.Web) is set as the StartUp Project.

You now have a solution consisting of two projects:

  • EnhancedViewerInSilverlight - This is the Silverlight application project which will load a dashboard for viewing.
  • EnhancedViewerInSilverlight.Web - This is a web application project which hosts the Silverlight application. This must be set as the StartUp project for the solution.

Typical structure of the two projects in the solution.

Typical structure of the two projects in the solution.


Add an Enhanced Viewer placeholder to the Silverlight application

To add the Enhanced Viewer to the Silverlight application, you must create a placeholder control which will contain the Enhanced Viewer. The Enhanced Viewer control will be created dynamically at runtime.

  1. Open the MainPage.xaml file in order to edit the XAML markup.
  2. Replace the content of this file with the markup listed below. The ContentControl element is the placeholder for the Enhanced Viewer control.



Add code-behind to the Silverlight control

Add code-behind to initialize the client, create a viewer, and load the viewer with a specified dashboard:

  1. Edit the MainPage.xaml.cs file and replace its content with the code listed below.
  2. Compile and build the solution.

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 System.Collections.ObjectModel; using System.Linq; using System.Windows; using System.Windows.Controls; using Dundas.Dashboard; using Dundas.Dashboard.Business; using Dundas.Dashboard.Controls; using Dundas.Dashboard.UIFramework.Viewer;

namespace EnhancedViewerInSilverlight { public partial class MainPage : UserControl { #region Fields /// /// The Enhanced Viewer control /// private EnhancedViewer MyViewer; #endregion

public MainPage() { InitializeComponent();

this.Loaded += new RoutedEventHandler(this.MainPage_Loaded); this.Unloaded += new RoutedEventHandler(MainPage_Unloaded); }

private void MainPage_Loaded(object sender, RoutedEventArgs e) { // Only do this once, so unsubscribe from the event this.Loaded -= new RoutedEventHandler(this.MainPage_Loaded);

// Extract the Dundas Dashboard server URI and session ID from the applications initParams this.ServerUri = new Uri(Application.Current.Host.InitParams["serverUri"]);

// Get the startup Dashboard's content Id this.DashboardContentId = new Guid(Application.Current.Host.InitParams["dashboardContentId"]);

// Get the session Id this.DashboardSessionId = new Guid(Application.Current.Host.InitParams["dashboardSessionId"]);

// Initialize the Dundas Dashboard client IntegrationHelper.InitializeClientFromSessionIdAsync(this.ServerUri, this.DashboardSessionId, new OnCompleted(this.OnDashboardClientInitialized)); }

void MainPage_Unloaded(object sender, RoutedEventArgs e) { // Only do this once, so unsubscribe from the event this.Unloaded -= new RoutedEventHandler(this.MainPage_Loaded);

// Dispose the viewer this.MyViewer.Dispose(); }

/// /// Called when Dashboard has initialized /// /// An exception if there was an error iniializing Dashboard. private void OnDashboardClientInitialized(DDException exception) { // Fail if there was a problem initializing the client if (exception != null) { throw exception; }

// The client is now initialized, so it's safe to create and load the viewer - adding it to the visual tree.

// Create the viewer control this.MyViewer = new EnhancedViewer();

// Handle the viewer loaded event so parameters can be passed to the dashboard this.MyViewer.ViewerSourceLoaded += new EventHandler(MyViewer_ViewerSourceLoaded);

// Set the source of the viewer to be the dashboard ID passed from the server. this.MyViewer.ViewerSource = new ViewerSource(this.DashboardContentId, ViewerContentItemType.Dashboard);

// Example of hiding toolbar items this.HideToolbarItems("Annotate", "FilterAnnotationGroups", "ManageContent");

// Examples of controlling visibility of elements in the viewer this.MyViewer.IsToolbarVisible = false; // Hide the toolbar at the top this.MyViewer.IsNavigationVisible = false; // Hide the navigation pane at the bottom this.MyViewer.IsLogoVisible = false; // Hide the logo

// Assign the enhanced viewer object to the content container this.ViewerPlaceholder.Content = this.MyViewer; }

/// /// Handles the ViewerSourceLoaded event of the MyViewer control. /// /// The source of the event. /// The instance containing the event data. void MyViewer_ViewerSourceLoaded(object sender, ViewerEventArgs e) { // Example of passing parameters to the Dashboard ParameterInfo paramInfo = new ParameterInfo { ParameterName = "Country", FilterValues = new Collection() };

paramInfo.FilterValues.Add(new DashboardFilterValueData { SingleValue = "Canada" });

// Add the parameter info to the parameters on the Dashboard ParameterInfoCollection paramInfoCol = new ParameterInfoCollection(); paramInfoCol.Add(paramInfo);

// Set the parameters this.MyViewer.SetParameters(paramInfoCol); }

/// /// Hides toolbar items. /// /// An array of command ids to hide. /// /// Available IDs of the icons on the toolbar: FilterAnnotationGroups, Annotate, SaveMashup, ManageContent, Bookmark, Export, Print, Share, Logout, Help, Notification, PerformanceInfo /// private void HideToolbarItems(params string[] commandIds) { this.MyViewer.ToolbarCommands = this.MyViewer.ToolbarCommands.Where(c => !commandIds.Contains(c.Id)); }

#region Properties /// /// Gets or sets the server URI. /// /// The server URI. private Uri ServerUri { get; set; }

/// /// Gets or sets the dashboard content id. /// /// The dashboard content id. private Guid DashboardContentId { get; set; }

/// /// Gets or sets the dashboard session id. /// /// The dashboard session id. private Guid DashboardSessionId { get; set; } #endregion } }


Note: In the above code, it is important to note that the client must be initialized before issuing any Dundas Dashboard API calls. Using any API call before initialization is complete is not supported.

Customizing the Enhanced Viewer

You have the option of customizing the Enhanced Viewer when you embed it into a Silverlight application.

Within your MainPage.xaml.cs file, locate where it creates a new instance of the Enhanced Viewer, do a right-click on the EnhancedViewer type, then select Go To Definition from the menu. This will show all of the properties that are available within the Enhanced Viewer.

Go To Definition of EnhancedViewer class.

Go To Definition of EnhancedViewer class.


The code listed below shows where the Enhanced Viewer is instantiated.

private void OnDashboardClientInitialized(DDException exception) { ... // Create the viewer control this.MyViewer = new EnhancedViewer(); ... }

Modifying the web application project

Add Silverlight to the Default.aspx web page

Add Silverlight to the Default.aspx web page by using HTML:

  1. Open the Default.aspx file in order to edit the web page's markup.
  2. Refer to the article How to: Add Silverlight to a Web Page by Using HTML. Copy the markup presented in the Code section and use it to update the markup in your Default.aspx. Be careful not to overwrite the Page directive which is the first line of your Default.aspx file.
  3. Modify the div element by replacing it with the markup listed below (take note of the source parameter referencing the Silverlight application control and the the dynamic parameters passed to initParams).



Add code-behind to the Default.aspx web page

Follow these steps to add code-behind to the Default.aspx web page:

  1. Open the Default.aspx.cs file to edit the code-behind so that it resembles the code shown below.
  2. Change the serverUri 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 dashboardContentId value to the GUID of a dashboard to be loaded (which you obtained previously).
  4. Compile and build the solution.

The dashboardViewerUsername and dashboardViewerPassword 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;

namespace EnhancedViewerInSilverlight.Web { public partial class Default : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { // Initialize server parameters to where Dundas Dashboard is installed and where the viewer's XAP file is Uri serverUri = new Uri("http://dashsvr:7000/");

// Initialize the viewer username/password string dashboardViewerUsername = "viewer"; string dashboardViewerPassword = "1234";

// Initialize the startup Dashboard Id (this Dashboard will be displayed when Viewer first loads) Guid dashboardContentId = new Guid("7bcebd59-d425-4f29-9ea4-73033d50d515");

// Initialize the Dundas Dashboard integration interface IntegrationHelper.ServerUri = serverUri;

// Create a new session and store the Id LoginStatus loginStatus = IntegrationHelper.LoginLocal(dashboardViewerUsername, dashboardViewerPassword, true);

// 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 dashboardSessionId = loginStatus.SessionId;

// Build the init params. // For additional parameters, refer to: http://support.dundas.com/Dashboard4.EnhancedViewer_Vieweraspx.ashx this.InitParams = string.Format("ddAppLoaderModule=1,serverUri={0},dashboardSessionId={1},dashboardContentId={2}", serverUri, dashboardSessionId, dashboardContentId); }

#region Properties /// /// Gets or sets the init params. /// /// The init params. public string InitParams { get; set; } #endregion } }


Testing the Silverlight application in a web browser

You can now publish the web application project and test the Silverlight application in a web browser:

  1. Deploy the web application project (EnhancedViewerInSilverlight.Web] to IIS.
  2. If Dundas Dashboard is running on a different port or server than where your Enhanced Viewer project is, you may need to create a Cross-Domain Policy file. For more details about cross-domain security, also see the Viewer Integration Sample.
  3. If you're updating an existing Silverlight application to work with the latest version of Dundas Dashboard, it is a good idea to clear your web browser cache (in case it has cached old copies of XAP files).

As an example, on a server running IIS7, the web application project can be deployed under the same website where Dundas Dashboard is setup:

IIS application for Enhanced Viewer project.

IIS application for Enhanced Viewer project.


Testing the Silverlight application in a web browser.

Testing the Silverlight application in a web browser.


Examples

Hiding a dashboard

To hide a dashboard in the Enhanced Viewer, set its ViewerSource property to null.

Note: Do this whenever you navigate away from the EnhancedViewer.

Executing toolbar commands from a control (button, label etc.) within your MainPage.xaml

In some scenarios, you may want to hide the Dundas Dashboard toolbar in the viewer and add your own button(s) that will offer extra functionalities to your users, such as setting a dashboard as a favorite on page load. In this case, you can completely hide the default toolbar and create you own. The same method can be applied if you want to customize the style of the toolbar.

Here is the sample method that handles the Print button click event:

private void PrintButton_Click(object sender, RoutedEventArgs e) { Command cmd = this.MyViewer.ToolbarCommands.FirstOrDefault(c => c.Id.Equals("Print")); cmd.Execute(); }

And this is the code within your MainPage.xaml file:

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

Copyright © 2009-2014 Dundas Data Visualization, Inc.