TechBubble

Continuing my series on DotNetNuke Widgets, here is Part 3 where I provide insights into how you can develop your own Widgets for DotNetNuke. If you haven’t already done so, read Part 1 (overview of DotNetNuke Widgets) and Part 2 (DotNetNuke Widgets reference) to better understand the concepts explored in this post. Let’s get started.

Widgets are located in two places: ~/Resources/Widgets/DNN for Core Widgets and ~/Resources/Widgets/User/<CompanyName> for user Widgets. The Widget file names are <WidgetName>.js for Core Widgets and <CompanyName>.Widgets.<WidgetName>.js for user Widgets.

Let’s walk through the three basic sections of code that constitute a Widget:

Namespace, Inheritance and Constructor

Using the ASP.NET AJAX library, we register the namespace for our widget and define its inheritance from the BaseWidget class. Finally, we define the constructor.

Type.registerNamespace("YourCompany.Widgets");
YourCompany.Widgets.SampleWidget.inheritsFrom(DotNetNuke.UI.WebControls.Widgets.BaseWidget);
YourCompany.Widgets.SampleWidget = function(widget)
{
    YourCompany.Widgets.SampleWidget.initializeBase(this, [widget]);
}

Render Method

Every Widget must implement the render() method. Typically, this method will follow a pattern consisting of two steps: (1) enumerate the parameters specified in the Widget declaration (i.e. <param> elements) and assign them to local variables, (2) do some processing based on the parameters and call the render() method. When you call the render() method in Step 2, you pass in a DOM element that you create. The framework will replace the <object> element with which the Widget was defined with your DOM element and assign it the original ID that the <object> element was given. What your code does during Step #2 in order to populate the contents of the DOM element you create or manipulate other elements of the page is entirely up to you. Your Widget has access to any DOM element and can make calls to any other custom scripts, ASP.NET AJAX library functions, jQuery plugins etc.

YourCompany.Widgets.SampleWidget.prototype =
{
   render:
   function()
   {
      var params = this._widget.childNodes;
      if (params != null)
      {
          // Do something
      }

      var div = document.createElement("div");
      // Do some work here to add content to the div
      YourCompany.Widgets.SampleWidget.callBaseMethod(this, "render", [div]);
   }
}

Registration and Rendering

The last thing you have to do in your Widget is to register its class and tell the Widget framework that it can render all instances of your Widget present on the page.

YourCompany.Widgets.SampleWidget.registerClass("YourCompany.Widgets.SampleWidget", DotNetNuke.UI.WebControls.Widgets.BaseWidget);
DotNetNuke.UI.WebControls.Widgets.renderWidgetType("YourCompany.Widgets.SampleWidget");

The above is all you need in order to create the basic scaffolding for a Widget. Add your custom code, save the file following the expected name and location conventions and you can start using your Widget right away (you’ll have to do some more work to package the Widget if you want it to be installable using the DotNetNuke Extension Wizard).

If you would like to see the code for a functional user Widget, you can download and install the Module Print Widget. The module displays a dropdown that allows a page viewer to select from a list of modules on the page and print any single module thus eliminating the need to display a print icon on every module.

Stay tuned for the last part in this series where I take you step-by-step through the process of building a Product Catalog Widget that makes use of third-party jQuery plugins, injects stylesheets dynamically and renders a nice UI using the jQuery UI extensions.

This is Part 2 of my four-part series on DotNetNuke Widgets. In Part 1 of the series, I covered some fundamental concepts related to DotNetNuke Widgets. In this post, I will introduce you to a few of the Widgets that are included with the DotNetNuke distribution. Before getting started I’d like to make one observation…these widgets were created prior to the inclusion of jQuery within the DotNetNuke Core. While the Widgets are production-ready, they could use some refactoring to take advantage of jQuery’s efficient engine for selecting and manipulating DOM elements.

All Widgets follow the same format for embedding in any extension (module, skin, skin object, container)

<object codebase="{WidgetType}" codetype="dotnetnuke/client" id="{WidgetId}">
	<param name="{WidgetParameterName}" value="{WidgetParameterValue}" />
</object>

{WidgetType} (required) = fully qualified Type name of the Widget
{WidgetId} (required) = arbitrary ID for the Widget’s DOM element (must be unique on the page)

A Widget can have zero or more child elements, each with a “name” and “value” attribute with corresponding {WidgetParameterName} and {WidgetParameterValue} values. Widget parameter names are case-insensitive. Widget parameter values are always case-sensitive.

The purpose of this Widget is to “scrub” the appearance of a DotNetNuke page by removing undesirable attributes from specific elements on the page. For example, you may have a module that has a hard-coded “style” or “width” attribute that is disrupting the appearance of a page. You don’t really want to change the source code for the module (if it’s available) and you really want to use the module. This is where StyleScrubber Widget comes to the rescue. It enumerates a series of rules you provide and removes the undesirable attributes allowing elements to be fully styled with CSS. This Widget may appear any number of times on a page.

Parameters

classNames (required) – A list of class names separated by semi-colons. The Widget will only act on elements with a matching “class” attribute. At least one value must be specified. Example: head; normal; topic

tag (optional) – A HTML element tag name which acts as a filter in selecting elements. The default value is * which implies all elements. Example: div

removeAttribute (optional) – The name of the attribute which should be stripped from all elements that match the classNames and tag conditions. The removeAttribute parameter may be repeated multiple times to specify more than one attribute that should be removed. Example: style (strips the “style” attribute)

recursive (optional) – Value of true or false to indicate if the scrubbing cascades indiscriminately through all child elements of a matched element. Default is false.

Example

Remove all “width” and “style” attributes from TABLE elements that have a class value of “Normal” or “NormalBold”

<object codebase="StyleScrubberWidget" codetype="dotnetnuke/client" id="ScrubTable">
	<param name="classNames" value="Normal;NormalBold" />
	<param name="tag" value="table" />
	<param name="removeAttribute" value="width" />
	<param name="removeAttribute" value="style" />
</object>

The purpose of this Widget is to move or “relocate” content so that they visual location of the content differs from the physical location of the content in the page. The primary use-case is SEO. Using the RelocationWidget it is possible to have content as close to the top of the page as possible while moving the navigation lower down on the page. Since search bots do not run scripts, this arrangement is optimal for them. Users with script-enabled browsers will see the navigation in its intended location. This Widget may appear any number of times on a page.

Parameters

sourceId (required) – ID of the DOM element that contains the HTML content that will be relocated. It is recommended that you apply a CSS style of “display:none” to this element so it is not initially visible in the user’s browser.

targetId (required) – ID of the DOM element where the HTML content from the sourceId element will be moved. It is recommended that you apply a CSS style for “width” and “height” matching the dimensions that the relocated content will occupy. Doing so prevents other elements on the page from visually moving around when the Widget performs its action.

Example

Move all content from element “NavTemp” to “Nav”

<object codebase="RelocationWidget" codetype="dotnetnuke/client" id="MoveIt">
	<param name="sourceId" value="NavTemp" />
	<param name="targetId" value="Nav" />
</object>

Changes content within an element at a pre-defined interval. The content can be sourced from a location on the page, an RSS feed or sequentially numbered images. This widget is ideal for scenarios in which the content to be rotated is not known ahead of time and no interactivity is desired from the end-user. This Widget may appear any number of times on a page.

Parameters

elementId (required) – ID of the DOM element where the rotating content will be rendered.

height (required) – Height of the rotated content in pixels.

width (required) – Width of the rotated content in pixels

interval (optional) – Time interval in milliseconds for content rotation. Default is 2500 milliseconds.

direction (optional) – Direction in which new content slides. Values are UP, DOWN, RIGHT, LEFT (default), BLEND

transition (optional, experimental) – Transition effect for new content. Values are SLIDE, SNAP (default)

The RotatorWidget can rotate content from three sources. Content from all the sources is aggregated, then displayed so you can combine multiple sources in the same RotatorWidget instance if desired.

RSS Feed Source

feedUrl (required for RSS feeds) - URL of the RSS 2.0 feed from which content will be sourced

feedAttribute (required for RSS feeds) - Name of the element that contains the content to be rotated. Yahoo Pipes is used to retrieve the feed.

Sequential Image Source

imageUrl (required for images) – The base URL where the images to be rotated are located. Must end in slash (“/”).

imageTemplate (required for images) – The file name template for each image. The token {INDEX} may be used to indicate where the sequence number will be injected. The sequence begins at 1. Example: portrait{INDEX}.jpg for images names portrait1.jpg, portrait2.jpg, portrait3.jpg etc.

imageCount (required for images) – The number of images available for rotation.

imageScale (optional) – Indicates if images should be scaled by width or by height. Values are WIDTH and HEIGHT or blank (default) for no scaling.

Page Content Source

contentElementId (required for content) – ID of the DOM element that contains the content to be rotated. The Widget expects the DOM element to have zero or more child elements. The content of each child element is treated as a separate rotation item. Example: A <UL> element with multiple <LI> elements where each <LI> element contains one item of content.

Example

Rotate 10 images stored in a folder at an interval of 5 seconds.

<object codebase="RotatorWidget" codetype="dotnetnuke/client" id="Animate">
	<param name="elementId" value="PageHeader" />
	<param name="height" value="100" />
	<param name="width" value="400" />
	<param name="interval" value="5000" />
	<param name="imageUrl" value="/Portals/0/HeaderImages/" />
	<param name="imageTemplate" value="header{INDEX}.png" />
	<param name="imageCount" value="10" />
</object>

The purpose of this Widget is to provide a user interface that enables users to switch stylesheets in order to customize their browsing experience. This Widget may appear any number of times on a page.

Parameters

template (required) – The StyleSheetWidget renders an interface element for each stylesheet that the user can select from. The template parameter is used to specify the HTML markup that will be rendered for each stylesheet in the set. The HTML markup must be encoded and can use the tokens {TEXT} (replaced with the name of each stylesheet as specified in other parameters), {ID} (replaced with a unique identifier for each interface element that is rendered) and {CLASS} (replaced with “class” attribute and value). Example: <div title=”{TEXT}” {ID} {CLASS}></div>

default (required) – The value of the stylesheet that should be selected by default.

baseUrl (required) – The URL where the stylesheets are located.

cssClass (required) – The CSS class value to be used on interface elements corresponding to a stylesheet that is not selected.

selectedCssClass (required) – The CSS class value to be used on the interface element corresponding to the selected stylesheet.

In addition to the above, one parameter (name and value) is required for each stylesheet. The “name” attribute should contain the stylesheet filename and the “value” attribute should contain the human-friendly label associated with the stylesheet.

Example

Allow the user to select from five different color palettes.

<object codebase="StyleSheetWidget" codetype="dotnetnuke/client" id="ColorSelector">
	<param name="template" value="<div title="{TEXT}" {ID} {CLASS}></div>" />
	<param name="default" value="blue" />
	<param name="baseUrl" value="<%= SkinPath %>css/" />
	<param name="cssClass" value="Icon" />
	<param name="selectedCssClass" value="Icon-Selected" />
	<param name="red" value="Fire-engine Red" />
	<param name="blue" value="Midnight Blue" />
	<param name="yellow" value="Sunflower Yellow" />
</object>

This Widget is somewhat unique in that its purpose is to provide a standard way for embedding any embeddable content from other websites. Using this Widget, you create a “snippet” for any such content once using whatever unique requirements the source site may have. Once the snippet is created, you can then use the embeddable content multiple times within DotNetNuke using the standard Widget embedding syntax.

Parameters

publisher (required for user content) – This parameter tells the EmbedWidget where to look for the embeddable content. If it is not specified, the Widget looks for content in the folder “~/Resources/Widgets/DNN/EmbedWidgetResources/{type parameter value}/” If this parameter is specified, the Widget looks for content in the folder “~/Resources/Widgets/User/{publisher parameter value}/EmbedWidgetResources/{type parameter value}/”

type (required) – The type of content to embed. This value must correspond to a file named “{lowercase type parameter value}.snippet.htm” in the folder location specified above. The file must be a plain-text file containing solely the HTML markup necessary for rendering the content.

In addition to the above parameters, you can specify and arbitrary number of name/value parameters that are passed to the content snippet file when the content is rendered by the Widget. The value may be a single value or multiple values concatenated using a delimiter character. The default delimiter is “;”. You can overrride the delimiter by specifying the “multiValueDelimiter” parameter described below. Review the individual snippet file for each type of embeddable content for supported parameters specific to that content type.

multiValueDelimiter (optional) – Character used to delimit multi-value parameters.

When the Widget is rendered, the snippet file is parsed and token substitution is performed using values specified in the parameters. The syntax for tokens is:

{ parameter name : token template : default template }

For each token, the Widget checks to see if a corresponding named parameter is available. If so, it replaces the token with the token template otherwise it uses the default template. In order to substitute parameter values in the token template, placeholders are used. Placeholders are numeric and in the format {0}, {1}, {2} etc. The Widget substitutes values in the order they are specified.

For example: { width : width=”{0}” : width=”500″ } OR { coordinates : x={0},y={1} : x=100,y=100 }

Example

Embed a Flickr slideshow

<object codebase="EmbedWidget" codetype="dotnetnuke/client" id="Flickr">
	<param name="type" value="Flickr" />
</object>

The purpose of this Widget is to enable an HTML element on a page to toggle the visibility of a container element located elsewhere on the page. The Widget included with DotNetNuke is now deprecated. Joe Brinkman has updated the Widget’s code and the updated one will be available in a future DotNetNuke release. You can read all about Joe’s enhancements in his blog post DotNetNuke Tips and Tricks #15: DotNetNuke Visibility Widget.