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.

Creating HTML Add-On Controls

Hide navigation
RSS
Modified on Mon, 27 May 2013 02:37 PM Categorized as Add-ons, Level-Advanced, Level-Expert, Open APIs
Click to return to: Documentation


Introduction

When you use the Dashboard Control API to develop a new dashboard control add-on, that add-on will only work with the Silverlight-based viewer, and not the HTML viewer. In order to have the same or similar functionality in the HTML viewer, you must develop a corresponding HTML add-on control.

This article is a guide to the design and creation of HTML add-on controls for the Dundas Dashboard HTML viewer.

Overview

An add-on control for Silverlight consists of two parts: a class called the wrapper which is responsible for interfacing with Dundas Dashboard and a Silverlight control called the visual that is created and initialized by the wrapper and provides the visual representation of the add-on control.

HTML add-on controls extend this concept with an additional class called the HTML wrapper which is responsible for interfacing with the Dundas Dashboard HTML framework. The original wrapper is still required (⪚ for data binding, scripting, &etc;) and is wrapped by the HTML wrapper. Inclusion of the original visual is optional and depends on what the HTML wrapper chooses to render. If the original visual is to be included, it must be ported from Silverlight to WPF.

HTML add-ons have full control over what is rendered to the browser. They are also able to include various resources such as CSS, JavaScript, and images. The add-on can choose whether to render HTML equivalents (⪚ dropdownlist, button) for its control or have the control rendered as SVG (⪚ a complex visual such as a chart) or a mix of both. The HTML add-on can also optionally specify that a JavaScript class should be attached to its control in order to provide additional interactivity on the browser.

HTML add-on controls are implemented as a new add-on type and as such are separate from Silverlight add-on controls. Porting an existing Silverlight add-on control to HTML requires creating a new class library project which includes the original wrapper, visual, and a new HTML wrapper. The Dundas.Dashboard.Html.Core assembly defines all the dashboard types used by dashboard add-ons so porting the wrapper simply requires including the source in the new class library project and re-compiling. Porting the visual from Silverlight to WPF is also usually as simple as including and re-compiling the source (since WPF is a superset of Silverlight and has equivalents for most of its types). If both the Silverlight and HTML add-ons are to be maintained, the best practice is to share the wrapper and visual code between the two projects and use conditional compilation symbols (⪚ SILVERLIGHT, HTML) to work around any compilation differences.

The compiled project output is then packaged and deployed as with other dashboard add-ons.

Details

The HTML wrapper

The HTML wrapper is a class that inherits from DashboardHtmlElement (or one of the other base classes) defined in Dundas.Dashboard.Html.Core. It interfaces with the Dundas Dashboard HTML framework and is responsible for rendering the control markup to the browser. The class has access to an instance of the original wrapper and can use its properties when deciding what to render. The HTML wrapper can also create a script class that will be instantiated on the browser to provide enhanced interactivity for the rendered content. If the original wrapper included a complex visual, the HTML wrapper can optionally render it to SVG.

The HTML add-on control package uses an attribute to specify the original dashboard control type and the HTML wrapper that will represent it. The HTML framework builds a mapping of dashboard controls to HTML wrappers and uses this mapping to create the appropriate HTML wrappers when loading a dashboard. If a dashboard control type is encountered for which there no HTML wrapper is defined, it is assigned a default wrapper which will render a placeholder to the client.

The following is a list of useful members on this class:

  • CssClass property - Specifies the CSS class given to the DOM element. Included CSS resources can reference the class to provide styling.
  • ScriptClassType property (optional) - Specifies the name of a script class that will be instantiated on the browser. A JavaScript resource must be included which will specify the implementation of the class.
  • Wrapper property - Returns the original wrapper instance mapped to this HTML control. The HTML wrapper can use the properties on this value in its rendering.
  • OnInitializeView method - Place code here to do any initial setup of the control.
  • OnCompleteView method - Place code here to perform the final rendering of the control.
  • OnCreateStyle method - Place code here to control the inline style applied to the DOM element for the control.

The script class

The HTML wrapper can optionally register a script class to provide additional functionality on the browser. The script class is written in JavaScript and will be able to manipulate the markup rendered by the HTML add-on. The following are the steps required to include a script class:

  1. Override the ScriptClassType property on the HTML wrapper and specify a class name.
  2. Override the OnGetScriptClassParameters method on the HTML wrapper to provide any data you wish to pass down to the client class. The data will be serialized as JSON.
  3. Add a JavaScript file as an embedded resource to the HTML wrapper project.
  4. In the JavaScript file, declare a class which extends the Control base class and uses the name declared via the ScriptClassType property. See below for a skeleton script class definition:

Dundas.Dashboard. DashboardVideoPlayer = Dundas.Dashboard.Control.extend(
{
    init: function ()
    {
        // This field will be initialized with any value with a matching name from the server
        this._myFieldFromServer = null;
    },

    onLoaded: function ()
    {
        // Do main work here
        // Use the TargetElement property to access the video player DOM element
        var element = this.TargetElement;
        this.bindEvent(element, ‘click’, function() { alert(‘you clicked’); });
    }
});

Creating an HTML add-on control

High-level process

  1. Create a new .NET class library project.
  2. Add a new class to represent the HTML wrapper.
  3. Include the source code for the dashboard wrapper from the Silverlight add-on.
  4. Add a HtmlWrapperAttribute to the project assembly to map the original dashboard wrapper type to the new HTML wrapper type.
  5. If you wish to render the Silverlight visual, then you must port the visual control to WPF and include it in the project.
  6. Add logic to the HTML wrapper class based on what you want to render. You can also include various HTML resources such as images, CSS, and JavaScript.
  7. Package the project output into a .plugin file.
  8. Place the .plugin file into the Plugins\DashboardControlsHtml folder of the Dundas Dashboard web application.
  9. Restart the web application.
  10. View a dashboard containing the original dashboard control in the HTML viewer.

Detailed process - Simple data visualization control

The following are the steps required to port a data-visualization control such as the Tag Cloud add-on. We will assume the control has no client-side functionality and so the core work required is porting of the wrapper and rendering the output.

  1. Create a new solution and add a Class Library project.
  2. Add a reference to the Dundas.Dashboard.Html.Core, DashWorks.Business, and Dundas.Controls.DataVisualization server-side assemblies.
  3. Add a new class called DashboardHtmlTagCloud that will represent the HTML wrapper.
  4. Make the class inherit from DashboardHtmlDataVisualizationControl.
  5. Add the code for the original TagCloud wrapper.
  6. We will port the visual so we need to add references to the WPF assemblies: PresentationCore, PresentationFramework, and WindowsBase. These are included with the .NET framework.
  7. Add the code for the TagCloud visual and make any adjustments for WPF.
  8. Add an HtmlWrapperAttribute to the assembly to establish the mapping between the original wrapper and the new HTML wrapper.
    [assembly: HtmlWrapper(DashboardTypeNamespace = HtmlWrapperAttribute.DvControlsNamespace, DashboardTypeName = "DashboardTagCloud", HtmlWrapperType = typeof(DashboardHtmlTagCloud))]
  9. In the HTML wrapper, override the RenderSvg property and return true. This will cause the HTML framework to render our TagCloud WPF visual as SVG.
  10. Compile the project.
  11. Use the plugin packager utility to create a plugin file as with other plugin types. The type argument for HTML controls is “dch”.
  12. Place the plugin file in the Plugins\DashboardControlsHtml folder of the Dundas Dashboard installation.
  13. Restart the Dundas Dashboard web application.
  14. Use the HTML viewer to render a dashboard that has a DashboardTagCloud control on it.
  15. The HTML viewer creates the DashboardHtmlTagCloud wrapper for the DashboardTagCloud and the rendered SVG is rendered to the browser.

Detailed process - DashboardVideoPlayer

The following are the steps required to port the Dashboard VideoPlayer add-on. In this case, HTML has an equivalent video tag that we will use in our rendering so we don’t really need to port the original visual. We will use the instance of the original wrapper (via the Wrapper property) to retrieve the video source and render it as a src attribute on the video tag. We will also declare a script class and include CSS and JavaScript to add some enhanced interactivity.

  1. Create a new solution and add a Class Library project.
  2. Add a reference to the Dundas.Dashboard.Server and Dundas.Dashboard.Html.Core assemblies.
  3. Add a new class that for the HTML wrapper (⪚ DashboardHtmlVideoPlayer).
  4. Make the class inherit from DashboardHtmlControl.
  5. Include the source for the original Silverlight wrapper into the project.
  6. Add an HtmlWrapperAttribute to the assembly to establish the mapping between the original wrapper and the new HTML wrapper.
    The following code creates a mapping between the Dundas.Dashboard.DashboardControls.DashboardVideoPlayer wrapper and the DashboardHtmlVideoPlayer HTML wrapper.
    [assembly: HtmlWrapper(DashboardTypeNamespace = HtmlWrapperAttribute.ControlsNamespace, DashboardTypeName = "DashboardVideoPlayer", HtmlWrapperType = typeof(DashboardHtmlVideoPlayer))]
  7. Include the source for the visual which in this case is the VideoPlayer control. We won’t be rendering this control so a dummy control could have been used here.
  8. Add a folder called ‘Resources’.
  9. Add a CSS file to the Resources folder and make it an embedded resource.
  10. Add a simple CSS declaration such as: .DashboardVideoPlayer {color:blue;}
  11. Add a JavaScript file to the Resources folder and make it an embedded resource.
  12. Override the HTML wrapper OnInitializeView method and register the CSS and JavaScript resource to be included in the rendering via the base.RegisterResourceInclude method. The path is the path to the file minus the assembly name and extension. For example for a file in \Resources\Style.css the path is Resources.Style.
  13. Override the CssClass property on the HTML wrapper and specify a class of ‘DashboardVideoPlayer’ which will be referenced in the included CSS resource to provide styling.
  14. Override the ScriptClassType property and specify a value of ‘DashboardVideoPlayer’. We will declare a class with this name in the included JavaScript resource.
  15. In the HTML wrapper OnCompleteView method, render the markup for the video tag using the Src property from the wrapper. We could optionally have also rendered the video player visual to SVG here but we don’t need to in this case.
  16. Compile the project.
  17. Use the plugin packager utility to create a plugin file as with other plugin types. The type argument for HTML controls is “dch”.
  18. Place the plugin file in the Plugins\DashboardControlsHtml folder of the Dundas Dashboard installation.
  19. Restart the Dundas Dashboard web application.
  20. Use the HTML viewer to render a dashboard that contains the original wrapper.

Related topics


Click to return to: Documentation

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

Copyright © 2009-2014 Dundas Data Visualization, Inc.