• University departments, offices, student groups
• Government
• Open Source projects
• Internet startups by category

More examples on this blog: Ten Examples of the Subway Map Metaphor.

Fast-forward to now. Finally, with the advent of HTML5 <canvas> element and jQuery, I felt it was now possible to implement this in a way that with a little bit of effort, anyone who knows HTML can easily create a subway map. I felt a jQuery plugin was the way to go as I had never created one before and also it seemed like the most well-suited for the task. My goals:

• Anyone should be able to create a beautiful, interactive subway map visualization for their website using HTML markup
• The map should be as faithful as possible to the London Underground map style with smooth curves and interchange connectors and 45-degree diagonals
• The map size, line width and colors should all be customizable
• Stations, interchanges and linked interchanges should be distinguishable from each other
• The markup used to create the map should be search engine friendly

With these goals in mind, I started creating my jQuery plugin. A few days of concentrated effort later, I had a working subwayMap plugin and am quite pleased with the result. You can download the plugin below and documentation follows in this post. I hope you will give the plugin a try and find it useful.

Demo

I was the keynote speaker at a regional conference for the DotNetNuke Open Source Project and created a comprehensive subway map of the project ecosystem for my presentation using the subwayMap plugin. The map uses every feature of the plugin and is a good practical example of how to use the plugin. Click the image to view the map.

Download

Note: There is a file embedded within this post, please visit this post to download the file.

Step-by-Step Guide

Here is a guide to using the Subway Map Visualization jQuery Plugin. Before you get started, there’s one thing you’ll want to keep in mind — beautiful subway maps are never automatic; they are almost always the result of care in design and placement to ensure that the resulting map is functional, legible and beautiful. This plugin is just a tool…you will still need to plan and design your map in order to produce a good result.

Referencing the Plugin

The subwayMap plugin is referenced similar to other jQuery plugins by adding a script element to the HTML markup.

<script src="http://code.jquery.com/jquery-1.4.2.min.js" type="text/javascript"></script>
<script src="jquery.subwayMap-0.5.0.js" type="text/javascript">

Using the Plugin

The subwayMap plugin is called using a jQuery selector as follows:

$("#sampleselector").subwayMap({ debug: true });

The only supported option (at present) is “debug” which has a default value of “false”. Setting it to true will display some debug statements in the JS console.

HTML Markup for Plugin

Like most navigation plugins, subwayMap uses an unordered list. The basic markup consists of the following:

• An outer DIV element to control general placement, background etc.
• One UL element for each “line” desired in the map.
• For each UL element, one or more LI elements with either plain text or an A element with plain text. An LI element provides coordinates for drawing lines and/or markers on the map.

Each of the DIV, UL and LI elements make use of custom attributes to convey how the map should be rendered. These are explained in the Step-by-Step section below.

Map Rendering

The subwayMap plugin renders the map on a grid with the origin at top left (i.e. X coordinates extend from left to right and Y coordinates extend from top to bottom). The size of this grid depends on a value you define called “cellSize.” For example, if you define a cellSize of 50 and specify a grid of 20 columns by 10 rows, then you will have a map that is 1000 pixels wide and 500 pixels high. For each UL element, a <canvas> element that is the size of the grid is created and positioned at (0,0). Subsequent <canvas> elements are stacked on top of the prior <canvas> elements. Station and interchange markers for each line are also created in separate, stacked <canvas> elements, however their z-Index is always higher than that of the <canvas> elements containing the lines. Finally, all labels are added as elements with the highest z-Index of all the elements in the map.

Creating a SubwayMap Step-by-Step

Now that the basics are out of the way, let’s step through the process of creating a subway map from scratch. I am using jQuery UI as my mapping subject, creating a line for Widgets, Interactions and Effects. Here’s a map and the markup used to create it:

<div data-columns="12" data-rows="10" data-cellSize="40" data-legendId="legend" data-textClass="text" data-gridNumbers="true" data-grid="true" data-lineWidth="8">
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<li data-coords="2,2"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li>
<li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">Autocomplete</a></li>
</ul>
</div>
<div id="legend"></div>

<script type="text/javascript">
$(".subway-map").subwayMap({ debug: true });
</script>

This code looks way more complicated than it actually is. Most of the verbosity comes from the many “data-*” attributes that the plugin uses for all customizations. Here are the attributes being used in the code above:

(DIV) data-columns: The number of columns the map will display (12 in this example)

(DIV) data-rows: The number of rows the map will display (10 in this example)

(DIV) data-cellSize: The width and height of each cell in pixels (40 in this example, resulting in a grid that is 480px wide by 400px tall)

(DIV) data-legendId: The ID of an HTML element into which the map legend will be appended (“legend” in this example)

(DIV) data-textClass: The CSS class to use for text labels in the map (“text” in this example)

(DIV) data-grid: True or false, to show or hide a grid that is useful during map construction. The default is false (“true” in this example)

(DIV) data-gridNumbers: True or false, to show or hide numbers on the grid. Only applies if data-grid=”true” (“true” in this example)

(DIV) data-lineWidth: The width in pixels for each line. The default is 10 pixels. (8 in this example)

(UL) data-color: The color of the line in standard CSS RGB notation (#ff4db2 in this example)

(UL) data-label: The label for the line that will be displayed in the legend (“jQuery Widgets” in this example)

(LI) data-coords: The X,Y coordinate pair where the line should be drawn to from its last location (or the starting location if it’s the first LI element)

As you can see from the illustration, the result of the sample markup was a grid with numbers, a line drawn from (2,2) to (4,2) and finally markers at both coordinate locations. The markers are automatically added whenever you have any content in your LI element and later, we’ll see how you can override the marker type.

Now, let’s extend this line a bit, by adding a few more LI elements. For brevity, I will omit the overall definition and just show the LI elements here:

<li data-coords="2,2"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li>
<li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">Autocomplete</a></li>
<li data-coords="5,4"></li>
<li data-coords="7,4"></li>
<li data-coords="8,2"></li>

The resulting image is as you would expect. However, it is not very pretty to look at. To make it nicer, we need to add some curves. The plugin provides four directional curves that can be used anytime the difference between both X and Y start and end coordinates is exactly 1. Think of it like plumbing pipes…in order to make a right angle, you introduce an elbow joint. This is somewhat similar. In order to make a smooth, 90-degree curve, you use one cell for the curve as illustrated below:

To make a curve, you add a “data-dir” attribute to the LI element that defines the coordinates for the end of the curve. The value of this attribute is directional – E, W, N or S – indicating the direction in which the line will first go before making a right-angle to the coordinate referenced by that LI element. Let’s continue with our example to see this in action:

<li data-coords="2,2"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li>
<li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">Autocomplete</a></li>
<li data-coords="5,3" data-dir="E"></li>
<li data-coords="6,4" data-dir="S"></li>
<li data-coords="7,4"></li>
<li data-coords="8,3" data-dir="E"></li>
<li data-coords="8,2"></li>

To get the curves, some of the coordinates had to be changed in order to achieve the X and Y coordinate difference of exactly “1″. Note the additional “data-dir” attribute that determines the direction of the curve. The final result is a line that is similar, but not the same as the original and definitely more pleasing to the eye.

Let’s make the line loop around a bit and then go south on a diagonal run.

<li data-coords="2,2"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li>
<li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">Autocomplete</a></li>
<li data-coords="5,3" data-dir="E"></li>
<li data-coords="6,4" data-dir="S"></li>
<li data-coords="7,4"></li>
<li data-coords="8,3" data-dir="E"></li>
<li data-coords="8,2"></li>

The diagonal line was drawn correctly, but notice the small curves at the beginning and end. These are automatically added when the difference between the X and Y coordinates of the start and end are equal and greater than 1 (i.e. a diagonal). Unfortunately, this isn’t pretty to look at. To correct this we have to reduce our diagonal by one row and one column and introduce a curve like this:

<li data-coords="2,2"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li>
<li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">Autocomplete</a></li>
<li data-coords="5,3" data-dir="E"></li>
<li data-coords="6,4" data-dir="S"></li>
<li data-coords="7,4"></li>
<li data-coords="8,3" data-dir="E"></li>
<li data-coords="8,2"></li>

And there we have it, nice curves again and no sharp turns. Let’s wrap-up this line (no pun intended) and move on to multiple lines, markers and labels. I have now updated the markup to extend the first line a little and then added a second line shown in green labeled “jQuery Interactions.”

<div data-columns="12" data-rows="10" data-cellsize="40" data-legendid="legend" data-textclass="text" data-gridnumbers="true" data-grid="true" data-linewidth="8">
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<ul data-color="#ff4db2" data-label="jQuery Widgets"><li data-coords="2,2"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li></ul>
</ul>
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<ul data-color="#ff4db2" data-label="jQuery Widgets"><li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">Autocomplete</a></li></ul>
</ul>
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<ul data-color="#ff4db2" data-label="jQuery Widgets"><li data-coords="5,3" data-dir="E"></li></ul>
</ul>
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<ul data-color="#ff4db2" data-label="jQuery Widgets"><li data-coords="6,4" data-dir="S"></li></ul>
</ul>
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<ul data-color="#ff4db2" data-label="jQuery Widgets"><li data-coords="7,4"></li></ul>
</ul>
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<ul data-color="#ff4db2" data-label="jQuery Widgets"><li data-coords="8,3" data-dir="E"></li></ul>
</ul>
<ul data-color="#ff4db2" data-label="jQuery Widgets"><li data-coords="8,2"></li></ul>
</div>

In this map, there is a portion where both lines overlap. This is a fairly common situation and if you do nothing, the line that is drawn last will be at the top. This is less than ideal for communicating information, let alone train routes. To solve this problem, the plugin allows you to “shift” a line in X and/or Y directions by a multiple of the chosen line thickness.

(UL) data-shiftCoords: The number of line-widths by which line should be shifted in any direction specified as an X,Y pair with negative values indicating shift closer to the origin (0,0). You could manually do the shift by specifying precise coordinates, however this can make the line more complicated to define.  (Example: data-shiftCoords=”-1,0″ means move the line to the left by 1 line width.)

<ul data-color="#00ff00" data-label="jQuery Interactions" data-shiftCoords="0,-1">

With the above change, our map now looks like this:

Much nicer and simpler since we did not have to make any changes to the individual  line coordinates. Next, let’s add some markers. The plugin supports three types of markers: stations, interchanges and extended interchanges. These are always black-and-white (or white-and-black) and can be placed anywhere on a line. The attributes for markers are:

(UL) data-reverseMarkers: If the markers should be rendered white on black instead of the default, black on white. The default is “false”.

(LI) data-marker: Can be either “station” or “interchange.” Will produce a different marker for each. Value may be prefixed by “@” to indicate that the LI element is solely for indicating the position of the marker and should not be used as a coordinate defining the path of the line. (Examples: data-marker=”station” or data-marker=”@interchange”)

IMPORTANT:  Markers are displayed only if the LI element contains content. Interchange markers ignore any coordinate shift values specified for the line.

(LI) data-markerInfo: For “interchange” or “@interchange” markers, this attribute is used to define scenarios in which the interchange marker has to “stretch” across multiple lines or connect lines that are not next to each other. The attribute value consists of a letter “v” for vertical or “h” for horizontal, followed by a number representing the number of line widths to stretch (example: v3 or h4). The marker is rendered at the coordinate position specified and extends either vertically upwards or horizontally to the right.

While it is easy and convenient to use the LI elements that define line coordinates to also define markers, sometimes this does not yield the best result. The marker may appear off by a few pixels. In these cases, it is best to add an LI element for the marker, use the “@” prefix and provide precise coordinates with decimal places (Example: 1.5,2.25).

Here is the markup and map again, updated with station and interchange markers.

<div data-columns="12" data-rows="10" data-cellSize="40" data-legendId="legend" data-textClass="text" data-gridNumbers="true" data-grid="false" data-lineWidth="8">
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<li data-coords="2,2" data-marker="interchange"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li>
<li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">X</a></li>
<li data-coords="5,3" data-dir="E"></li>
<li data-coords="5,7" data-marker="@station">X</li> <!-- marker-only node -->
<li data-coords="6,4" data-dir="S" data-marker="interchange" data-markerInfo="h5">X</li>
<li data-coords="7,4"></li>
<li data-coords="7.15,8" data-marker="@station">X</li>  <!-- marker-only node, moved to the right by 0.15 -->
<li data-coords="8,3" data-dir="E"></li>
<li data-coords="8,2"></li>
<li data-coords="9,1" data-dir="N"></li>
<li data-coords="10,2" data-dir="E" data-marker="interchange">X</li>
<li data-coords="10,5"></li>
<li data-coords="9,6" data-dir="S" data-marker="station">X</li>
<li data-coords="6,9"></li>
<li data-coords="5,8" data-dir="W"></li>
<li data-coords="5,7"></li>
<li data-coords="4,6" data-dir="N"></li>
<li data-coords="2,6">Tabs</li>
</ul>

<ul data-color="#00ff00" data-label="jQuery Interactions" data-shiftCoords="0,-1">
<li data-coords="2,6"></li>
<li data-coords="2,5.9" data-marker="@interchange"> </li> <!-- marker-only node, moved up by 0.10 -->
<li data-coords="5,6" data-marker="@station">X</li>
<li data-coords="6,6"></li>
<li data-coords="7,3" data-marker="@station">X</li>
<li data-coords="7,5" data-dir="E" data-marker="station">X</li>
<li data-coords="7,1" data-marker="interchange">X</li>
</ul>

</div>
<div id="legend"></div>

I used the label “X” for all the station or interchange names. The only thing left to do is change the labels and also position them so they don’t appear on top of the line. The attribute used for positioning the labels is:

(LI) data-labelPos: Specifies where the label should be displayed using a directional abbreviation. Supported values are N, E, S, W, NE, NW, SE, SW. (Default is “S”). Sometimes your label may be too long and text-wrap may be needed. To do this, you can use “\n” within the text of the label (<br />will not work since the only markup supported for a label is the <a> element).

Labels are added as absolutely positioned <span> elements and when the map is added inside a DOM element with a complex, CSS layout, they may not always appear in the right place.

Let’s set the label text and position, turn off the grid and look at the final markup and rendered map.

<div data-columns="12" data-rows="10" data-cellSize="40" data-legendId="legend" data-textClass="text" data-gridNumbers="true" data-grid="false" data-lineWidth="8">
<ul data-color="#ff4db2" data-label="jQuery Widgets">
<li data-coords="2,2" data-marker="interchange"><a href="http://jqueryui.com/demos/accordion/">Accordion</a></li>
<li data-coords="4,2"><a href="http://jqueryui.com/demos/autocomplete/">Auto\ncomplete</a></li>
<li data-coords="5,3" data-dir="E"></li>
<li data-coords="5,7" data-marker="@station" data-labelPos="W">Slider</li> <!-- marker-only node -->
<li data-coords="6,4" data-dir="S" data-marker="interchange" data-markerInfo="h5">Date\npicker</li>
<li data-coords="7,4"></li>
<li data-coords="7.15,8" data-marker="@station" data-labelPos="E">Dialog</li>  <!-- marker-only node, moved to the right by 0.15 -->
<li data-coords="8,3" data-dir="E"></li>
<li data-coords="8,2"></li>
<li data-coords="9,1" data-dir="N"></li>
<li data-coords="10,2" data-dir="E" data-marker="interchange" data-labelPos="E">Button</li>
<li data-coords="10,5"></li>
<li data-coords="9,6" data-dir="S" data-marker="station">Progress\nbar</li>
<li data-coords="6,9"></li>
<li data-coords="5,8" data-dir="W"></li>
<li data-coords="5,7"></li>
<li data-coords="4,6" data-dir="N"></li>
<li data-coords="2,6">Tabs</li>
</ul>

<ul data-color="#00ff00" data-label="jQuery Interactions" data-shiftCoords="0,-1">
<li data-coords="2,6"></li>
<li data-coords="2,5.9" data-marker="@interchange"> </li> <!-- marker-only node, moved up by 0.10 -->
<li data-coords="5,6" data-marker="@station" data-labelPos="N">Selectable</li>
<li data-coords="6,6"></li>
<li data-coords="7,3" data-marker="@station" data-labelPos="W">Resizeable</li>
<li data-coords="7,5" data-dir="E" data-marker="station" data-labelPos="E">Droppable</li>
<li data-coords="7,1" data-marker="interchange" data-labelPos="W">Draggable</li>
</ul>

</div>
<div id="legend"></div>

There you have it…a map that faithfully reproduces the style of the London Underground map, but hopefully, is not too difficult for you to create once you get familiar with the custom attributes required in the HTML markup to render the map. Enjoy!

Reference

(DIV) data-columns: The number of columns the map will display (default=10)

(DIV) data-rows: The number of rows the map will display (default=10)

(DIV) data-cellSize: The width and height of each cell in pixels (default=100)

(DIV) data-legendId: The ID of an HTML element into which the map legend will be appended

(DIV) data-textClass: The CSS class to use for text labels in the map

(DIV) data-grid: True or false, to show or hide a grid that is useful during map construction (default=false)

(DIV) data-gridNumbers: True or false, to show or hide numbers on the grid. Only applies if data-grid=”true” (default=true)

(DIV) data-lineWidth: The width in pixels for each line (default=10)

(UL) data-color: The color of the line in standard CSS RGB notation

(UL) data-label: The label for the line that will be displayed in the legend

(UL) data-shiftCoords: The number of line-widths by which line should be shifted in any direction specified as an X,Y pair with negative values indicating shift closer to the origin (default=0,0)

(UL) data-reverseMarkers: If the markers should be rendered white on black instead of the default, black on white (default=false)

(LI) data-coords: The X,Y coordinate pair where the line should be drawn to from its last location (or the starting location if it’s the first LI element)

(LI) data-marker: Can be either “station” or “interchange.” Will produce a different marker for each. Value may be prefixed by “@” to indicate that the LI element is solely for indicating the position of the marker and should not be used as a coordinate defining the path of the line

(LI) data-markerInfo: For “interchange” or “@interchange” markers, this attribute is used to define scenarios in which the interchange marker has to “stretch” across multiple lines or connect lines that are not next to each other. The attribute value consists of a letter “v” for vertical or “h” for horizontal, followed by a number representing the number of line widths to stretch (example: v3 or h4). The marker is rendered at the coordinate position specified and extends either vertically upwards or horizontally to the right.

(LI) data-labelPos: Specifies where the label should be displayed using a directional abbreviation. Supported values are N, E, S, W, NE, NW, SE, SW (default=S)

Download the PDF version of the presentation here: Day of DNN Chicago Keynote.pdf (10.2 MB)
Download the PPTX version of the presentation here: Day of DNN Chicago Keynote.pptx (162.8 MB — includes embedded videos)

Here’s the DotNetNuke Ecosystem Interactive Map I presented during the session. (You can view source and download the jQuery plugin to create your own map…blog post with technical details to follow.)

Let’s start with the Seven Sins of DotNetNuke Module Developers:

Sin: Using inline style attrbutes in your HTML markup is probably the single, biggest problem you can create for your end-users. Since such attributes cannot be overridden with CSS, users are forced to edit the markup, use Javascript or the StyleScrubber Widget to neutralize the impact of a module’s inline style attribute on other elements of a page.

Sin Level: Annoyance

Absolution: Avoid using in-line style attributes in your module’s static and dynamic HTML markup. Instead, create style definitions in your module.css file that target your module’s markup. While you can use “class” and “ID” attributes throughout your markup, it is best to keep your markup clean and use the various CSS selectors to achieve the desired styles. An approach that works well is to create a “wrapper” DIV for your module’s markup with a “class” attribute value that closely matches your module name (for example: <div class=”Acme-Survey-Module”>). You can then have styles in your module.css like this:

.Acme-Survey-Module div  {
       padding-bottom: 10px;
}

And since we are on the topic of style-related sins, please do not specify any font-related style attributes in your style definitions. Let the page skin’s font definitions rule. If you absolutely must change the text size, at least use “em” units instead of pixel or point units so that the text size is relative instead of absolute.

Sin: Assuming that user input is safe and processing or persisting it without filtering, potentially compromising security and making a user’s DotNetNuke installation, server and network vulnerable to attacks.

Sin Level: Deadly

Absolution: DotNetNuke has built-in features, including an input filter that is incredibly easy to use for filtering strings. Use it to filter user input and make your modules more secure.

Sin: Hard-coding user interface text in HTML markup or in code, preventing localization and customization of text.

Sin Level: Aggravating

Absolution: Do not assume that everyone speaks the same language as you, and even if so, that they like the error prompt “Yo…you messed-up, fix it already.” Ensure that all user interface text follows well-established best-practices for DotNetNuke Localization.

Sin: Using an UpdatePanel instead of writing the code necessary to properly implement AJAX functionality. If your module is doing something trivial, by all means, use UpdatePanel. But for a module that is potentially going to be used in high-traffic scenarios, UpdatePanel is a no-go. UpdatePanel was intended to be a quick and easy way to implement AJAX functionality — it would not be a stretch to call the UpdatePanel solution LAJAX (lazy AJAX). Unfortunately, it has become the standard way in which most ASP.NET developers implement AJAX functionality. For every AJAX request, UpdatePanel causes the entire page life-cycle to be repeated on the server. As a result, a module that has lots of AJAX functionality implemented using UpdatePanel is going to cause significant performance issues and unnecessary resource utilization when used in a high-traffic environment.

Sin Level: Aggravating

Absolution: As I mentioned, if your module is doing something trivial, UpdatePanel is a reasonable solution. For anything else, it’s better to use ASP.NET AJAX or jQuery on the client-side making requests to an HttpHandler or Webservice to obtain the needed information for the UI in JSON or XML format. Here’s an example of how this can be done in a DotNetNuke module.

Sin: Using HTML markup for layout, instead of CSS, provides no semantic cues to user agents (browsers) as to the intended purpose of content. Most online discussions about semantic HTML markup degrade very quickly into near-religious arguments about TABLE versus DIV element. Such discussions are akin to throwing the baby out with the bath-water. Semantic markup is not solely about using tables for layout. The bigger issue is that HTML was never intended to convey presentation fidelity to the degree seen on modern web pages. Its primary purpose was to give semantic meaning to text so that user agents could then render the text in the most appropriate way for that agent. When markup is created with an emphasis on layout, it strays from this purpose. For instance, if your module markup uses an H1 element for content that is not the primary headline on the page, your markup is non-semantic and is misguiding user agents such as screen readers.

Sin Level: Annoyance

Absolution: I don’t view the issue of semantic HTML markup as a black-and-white one. I think it’s OK to take occasional liberties with markup to save time, after all time is money. But every developer should make a good-faith attempt to produce more semantic markup. Take a look at your module code and see if there are opportunities to replace HTML markup used for layout with CSS (without giving yourself a case of DIVitis). Low hanging fruit includes H*, B and I tags and input forms. For forms, try ditching the all-too-common TABLE found in most DotNetNuke module forms and replacing it with the FIELDSET element along with some CSS. For a good example of this, refer to the DotNetNuke Blueprint project.

Sin: Using a custom, non-standard user interface for managing module settings.

Sin Level: Aggravating

Absolution: DotNetNuke provides a simple and automatic mechanism for module developers to implement a user interface for managing module settings. Developers should not circumvent it as it adversely impacts usability of the platform. It takes time for users to get familiar and comfortable with standard behaviors. Each time a user encounters a module that ignores the standard and does something custom with the user interface, it causes the user to get frustrated with the platform (i.e. DotNetNuke). This is because, contextually, he/she has no knowledge of the separation between the platform and the module. As far as the user is concerned, DotNetNuke appears to have an inconsistent user interface (which it well might, but that’s another discussion). Why force the user to click on a custom link or button to configure your module’s settings? Let the framework do its thing and inject your settings control at the end of the standard module settings so that the user can customize module settings in the same way, no matter which module they are using.

Sin: Using “dbo” in module SQL scripts instead of {objectQualifier} and {databaseOwner}. If your module SQL scripts use “dbo” for the object owner your module cannot be easily installed in environments where the SQL connection uses a different database owner. If your module SQL scripts do not use the {objectQualifier} prefix for database objects, your module cannot be used in shared database scenarios.

Sin Level: Aggravating

Absolution: Follow DotNetNuke best practices for SQL scripts by using {objectQualifier} and {databaseOwner} prefixes in your module’s SQL scripts to ensure that your module can be installed in any environment where DotNetNuke is able to function.

There you have it…the seven sins of DotNetNuke module developers. What other cringe-worthy things have you seen in DotNetNuke modules?

Next up, the seven sins of DotNetNuke Skin Designers.

Step 1: Install the UrlRewrite module for IIS: http://www.iis.net/expand/URLRewrite

Step 2: Add the following rule to your applications web.config file:

<configuration>
 <system.webServer>
    <rewrite>
      <rules>
        <clear />
        <rule name="Redirect from www" stopProcessing="true">
           <match url=".*" />
           <conditions>
              <add input="{HTTP_HOST}" pattern="^www.yoursite.com$" />
           </conditions>
           <action type="Redirect" url="http://yoursite.com/{R:0}" redirectType="Permanent" />
        </rule>
     </rules>
   </rewrite>
 </system.webServer>
</configuration>

IMPORTANT: When using the above code, take care to merge it with your existing web.config without duplicating any existing elements.

I like my URL’s to be in the format http://mysite.com. If you prefer http://www.mysite.com, simply remove “www.” from the <add> element and add it to the <action> element’s “url” attribute.

• Part 1 – Overview of DotNetNuke Widgets
• Part 2 – DotNetNuke Widgets reference
• Part 3 – Insights into how you can develop your own Widgets for DotNetNuke

In this post, I’ll walk you through the code of the TechBubble CatalogWidget. This Widget displays a carousel of Product thumbnail images. You can click on any thumbnail to see a larger version of the image. You can then move your cursor over any portion of the larger image to see a zoomed in image of the area below the cursor. I created this Widget to convey multiple concepts:

• Passing data through Widget markup parameters
• Using a Widget to integrate multiple jQuery plugins seamlessly
• Using behavior injection to dynamically add event-handling to UI elements
• Dynamically injecting stylesheets and scripts into the page
• Using jQuery UI themes

Let’s start by looking at a mockup of the Widget (created using my favorite mockup tool – Balsamiq).

In order to implement this UI, I decided to use two jQuery plugins:

• ImageCarousel
• jqZoom

(These are arbitrary choices…I am sure that there are other plugins that would work equally well or better.)

I have setup two live demos of the Widget so you can get a feel for the Widget’s UI:

• Demo with default data (Ducati bikes)
• Demo with custom data (Maxim’s 10 Hottest Women)

You can download the Widget at the link below and follow along with the technical discussion that follows. I have also included a short slideshow that shows a screen grab of the installation process and the two demos.

[smooth=id:1;]

Here are the properties that supported by the CatalogWidget:

photoUrl (required) – A URL to the location where the images for the Widget will be found. The Widget uses the following convention for image names: {label}.{extension} for hi-res image displayed in zoom area, {label}_thumb.{extension} for thumbnail image and {label}_small.{extension} for small image displayed when thumbnail is clicked. {label} and {extension} are explained in the description for other parameters.

theme (optional, default=ui-lightness) – Name of the jQuery UI theme that should be loaded from Google’s CDN for jQuery themes. The list of supported themes can be found on the jQuery Themeroller page. The theme name should match the defined name on the Themeroller page, with spaces in the name replaced with the hyphen character.

carouselWidth (optional, default=500) – Width of the carousel used to display the thumbnails in pixels. The number of thumbnails displayed will depend on the width of each thumbnail and the value of this parameter.

zoomWidth (optional, default=250) – Width of the zoomed image area in pixels.

zoomHeight (optional, default=250) – Height of the zoomed image area in pixels.

moreInfoHandler (optional) - Name of a function that will be called with a parameter of {label} when the information icon that appears to the right of the product name link is clicked. If this parameter is not specified, the information icon will not be displayed.

extension (optional, default=jpg) – The file extension for all images.

Product Data – In addition to these parameters, the Widget supports an unlimited number of additional product data parameters. Any parameter specified other than the above, is treated as product data. The value of the “name” attribute of the parameter will be used for the product {label} and the value of the “value” attribute will be used for the product’s descriptive name. Example: <param name=”ABC1000″ value=”ABC 1000 Super Duper Product” />.

OK, now we have that out of the way, let’s get started with building the Widget. The Widget is going to exist in the namespace “TechBubble.Widgets,” so by convention, the Widget file will be named “TechBubble.Widgets.CatalogWidget.js” and it will be located in ~/Resources/Widgets/User/TechBubble. All resources for this Widget will be in ~/Resources/Widgets/User/TechBubble/CatalogWidgetResources. Here’s the code for namespace registration and the Widget constructor:

Type.registerNamespace("TechBubble.Widgets");
TechBubble.Widgets.CatalogWidget = function(widget)
{
    TechBubble.Widgets.CatalogWidget.initializeBase(this, [widget]);
    this.catalogResourcesUrl =
                    $dnn.baseResourcesUrl +
                    "Widgets/User/TechBubble/CatalogWidgetResources/";
    this.photoUrl = "";
    this.theme = "ui-lightness";
    this.carouselWidth = "800";
    this.zoomWidth = "250";
    this.zoomHeight = "250";
    this.moreInfoHandler = "";
    this.extension = "jpg";
    this.products = [];
    this.hasProducts = false;

    if (!TechBubble.Widgets.CatalogWidget.Initialized)
    {
        $.getScript(this.catalogResourcesUrl +
                    "scripts/jQuery-ui-1.7.2.custom.min.js");

        $.getScript(this.catalogResourcesUrl +
                    "scripts/jquery.metadata.js");

        TechBubble.Widgets.CatalogWidget.Initialized = true;
    }
}
TechBubble.Widgets.CatalogWidget.inheritsFrom(
            DotNetNuke.UI.WebControls.Widgets.BaseWidget);
TechBubble.Widgets.CatalogWidget.registerClass(
            "TechBubble.Widgets.CatalogWidget",
            DotNetNuke.UI.WebControls.Widgets.BaseWidget);

In the constructor, we define default values for the various properties (parameters) that the Widget supports. In addition the variable TechBubble.Widgets.CatalogWidget.Initialized is used as a flag to prevent the jQuery UI and jQuery metadata plugin from being loaded. A nice optimization for this code would be to check for the actual existence of the plugin, instead of using a flag. In addition to the constructor, the calls to inheritsFrom() and registerClass() are standard calls for every Widget for setting inheritance and registering the class.

TechBubble.Widgets.CatalogWidget.prototype =
{
    render:
        function()
        {
            // Parse widget parameters
            this._getParams();

            // Load some sample data to display if none
            // has been specified
            if (!this.hasProducts)
                this._getSampleData();

            // Create a DIV element and swap out the Widget's
            // defining <object> element with it by calling
            // the base render() method (can't use jQuery
            // shortcut to create element)
            var div =document.createElement("div");
            div.setAttribute("style","width:" + this.carouselWidth + "px");
            TechBubble.Widgets.CatalogWidget.callBaseMethod(this, "render", [div]);

            this._renderCarousel();

            this._renderZoomer();
        },

        _getParams:
        function()
        {
		// Enumerate and retrieve parameters
		// . . . code omitted
        },

        _renderCarousel:
        function()
        {
		// Render the Carousel plugin
		// . . . code omitted
        },

        _renderZoomer:
        function()
        {
		// Render the Zoomer plugin
		// . . . code omitted
        },

        _injectStyleSheet:
        function(name, isTheme)
        {
		// Inject a stylesheet into the page
		// . . . code omitted
        },

        _getThumbnailList:
        function(list, photoUrl)
        {
            return(productList);
        },

         _getSampleData:
         function()
         {
		// Use and display Widget with sample data
		// . . . code omitted
         }
}

Next, let’s review the code for the Widget’s prototype where the required method render() is declared along with various private methods (prefixed with underscore). In the render() method, we start by getting the parameters. Then, if no products are defined, we use some sample product information. Next, we swap out the <object> element defining the Widget with a <div> element. This <div> element will become the parent container for the rest of the Widget which is rendered in the _renderCarousel() and the _renderZoomer() methods. Next in the code are a number of helper methods. I won’t go into a line-by-line explanation, but highlight a few things I think are noteworthy:

Script Injection: I use the jQuery method $.getScript(scriptUrl, anonymous function) in several places. This is a useful method when you want to inject a script into the DOM and want to ensure that any dependent code is not executed until the asynchronous loading of the script is completed. By putting all the dependent code in an anonymous function defined in the second parameter of this method I could achieve this goal.

Behavior Injection: In _renderZoomer(), I iterate through each thumbnail in the carousel and use the shortcut for the jQuery bind() method $(this).click() to inject a click handler for each of the thumbnail images. This is cleaner and more efficient than adding an onClick attribute when defining the HTML markup for each thumbnail.

DotNetNuke.UI.WebControls.Widgets.renderWidgetType("TechBubble.Widgets.CatalogWidget");

We wrap-up the Widget code by telling the Widget framework to render all Widgets of the type TechBubble.Widgets.CatalogWidget.

This also wraps-up my series on DotNetNuke Widgets. I hope you found the content and examples useful and are inspired to build your own DotNetNuke Widgets.

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.

A couple hours of hacking later I present to you the ModulePrintWidget for DotNetNuke. It’s simple and easy to use. When added to a page, it creates a drop-down list of each module on the page. A user can select a module from the list to see a preview, then click a Print icon to print the contents of that module. Here’s a short 45-second YouTube video that demonstrates the Widget in action: TechBubble ModulePrintWidget

You can download the Widget package at the link below (install as Superuser from the Extensions page):

You can also see a live demo of the ModulePrintWidget.

To use the Widget, add the following HTML so that it appears once on a page. You can add the markup anywhere that HTML is supported (module, skin, skin object, container):

<object id="MyWidget" codetype="dotnetnuke/client" codebase="TechBubble.Widgets.ModulePrintWidget"></object>

If you want to customize the appearance and language, use the optional parameters:

<object id="MyWidget" codetype="dotnetnuke/client" codebase="TechBubble.Widgets.ModulePrintWidget">
 <param name="selectorCssClass" value="Class-to-style-dropdown" />
 <param name="selectText" value="Default-text-for-dropdown" />
</object>

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.

DotNetNuke skins require the presence of a container HTML element with an ID of “ContentPane” and a runat=”Server” attribute. This is fine for most skins as it’s no big deal to define an area that serves as the default location for content (i.e. ContentPane). In the case of dynamic skin proxies (i.e. skins that load a layout based on some arbitrary set of conditions) this requirement is a problem since different layouts may want the ContentPane to be located in different places within the layout HTML.

In any event, as a result of my tinkering with skin proxies I found a clean solution for this problem. Ultimately I decided not to use it for Skinfigurator (more about the how/why in another post), however the technique is still quite useful. I promised Armand I would share it with him, and although I have been slow in making this post, it’s better late than never

The solution is trivially simple and involves just one file — the skin proxy layout. Basically what this proxy does is tap into the Init event in the page life-cycle to dynamically load the skin layout control. Since this event happens prior to the point where the DotNetNuke framework skin loader does its thing, you don’t have to bother with creating ContentPane elements in the skin proxy layout. All you need is the logic for dynamically selecting which layout to display to the user. Your Here’s the code for the skin proxy layout (I called mine LayoutSelector.ascx)

<%@ Control language="vb" AutoEventWireup="false" Explicit="True" Inherits="DotNetNuke.UI.Skins.Skin" %>
<script runat="server">
	Protected Overrides Sub OnInit(ByVal e As System.EventArgs)

		Dim layout = "Portal.ascx"
		If (Request.Querystring("layout") <> "") Then
			layout = Request.Querystring("layout") + ".ascx"
		End If
		Controls.Add(LoadControl(TemplateSourceDirectory + "/layouts/" + layout))
	End Sub
</script>

In my example, I have the code checking for a querystring variable and loading a control based on the value provided. Of course, this is not something you will want to do in production use. More likely you will want to have conditional logic based on the user, portal, browser, tab or some other controlling factor that determines which skin layout will be loaded.

There is one other thing to be aware of that is related to usability. By default, DotNetNuke lists all layouts (i.e. user controls) it finds in a skin folder in any skin layout selector in the UI. To ensure that your proxy logic is used, you will want your proxy layout control to be the only control in the skin’s root folder. All the dynamically selectable layouts should be in a sub-folder. In my example, I use a sub-folder called “layouts.” The folder structure for your skin will look something like this:

[MyCoolSkin]
– LayoutSelector.ascx
– skin.css
– [layouts]
—– Portal.ascx
—– Portal2.ascx
—– Portal3.ascx

Using this approach, the user will only be able to choose “LayoutSelector” and the Portal, Portal2 and Portal3 layouts will be hidden from the skin layout selector UI.

Widget Fundamentals

Just as you can add modules to a DotNetNuke page to add application functionality, so also can you add Widgets to DotNetNuke skins and modules to add interactivity. For example, in a skin, Widgets may enable a user to dynamically switch a stylesheet to change page appearance, add a photo gallery, embed a video etc. In a module, Widgets can provide interface elements for navigation, drag-and-drop sorting capabilities etc. Widgets are first-class citizens of DotNetNuke’s extensibility model and can therefore be packaged individually or in combination with DotNetNuke modules and skins using the familiar DotNetNuke manifest and zip file model. Widgets are created using Javascript code that builds on the Microsoft ASP.NET AJAX client-side library and can leverage jQuery or any other client-side framework for additional capabilities. They can be embedded into any extension type that manifests itself in the client browser (module, skin, skin object, container) and use a syntax that should be familiar to skin designers. Here’s an example of a Flickr Widget:

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

That’s it…three lines of HTML markup to embed a Flickr slideshow like the image below instantly into a DotNetNuke page. Go ahead…try it out by adding the above markup in an HTML module (in source)…I’ll wait.

At this point you are probably wondering what the benefit of Widgets is if they are coded in Javascript and make use of pre-existing client-side libraries. After all it’s not that difficult to embed a simple <script> element into your skin or module and add any code that you desire directly at the appropriate location. And using my simplistic example of a Flickr slideshow, you could just as easily get the embed code for the slideshow and use it directly.

Five Reasons for using the Widget framework

Let’s address these questions by reviewing the five primary reasons for using the Widgets framework:

Clean Markup: Using Widgets enables you to keep the HTML markup for your skin or module clean and script-free. Since Widgets are embedded using the standard <object> element, you can add functionality without sacrificing readability. In fact, Widgets lend themselves to more semantic markup as the intent of the markup is usually evident from the name of the Widget and the parameter name/value pairs. Embedding script directly or referencing an external script makes your markup harder to read and maintain.

Reusability: If you have some Javascript code that needs to be used in multiple skins or modules, wrapping it into a Widget makes it easy for you to re-use the code while taking advantage of DotNetNuke’s packaging and versioning capabilities. Sure, you could store a script file in a central location and reference it, but Widgets afford you greater control in using, deploying and maintaining the code. Furthermore, by implementing the code as a Widget, you now have the ability to easily pass parameters without messing around with querystring parameters to script file references or in-line Javascript variable declarations. Such reusability does come at a small price in terms of time and effort required, so it’s probably not a good idea to create a Widget for a single-use script.

Testability and Maintainability: Unlike context-less Javascript files or embedded script, Widgets are stand-alone, contextual entities. Therefore they can be tested and debugged in a variety of scenarios quickly and easily with minimal effort. If you just add a <script> reference to a Javascript file in your HTML markup, you have no way of knowing if the dependencies for the script are being loaded or not. You have no idea if any variable necessary to pass parameters to the script are already on the page or not. These issues are eliminated using Widgets. When you use a Widget, you know that its dependencies will be correctly loaded and its parameters are available in the Widget’s HTML markup itself.

Performance: Browsers execute inline script and fetch scripts referenced using the <script> element synchronously while rendering a page (you could use the “defer” attribute, but browser support for this is not consistent). This puts an unnecessary wait penalty on the site visitor. Using jQuery’s document.ready() method mitigates this somewhat, but remember, the browser still has to switch context from HTML to Javascript, parse the script and then switch context back to HTML. Widgets provide a cleaner way to add client-side interactivity as they are loaded at the end of a page when the DOM is ready. Thus, the visitor will have a better user experience as HTML, CSS and images will already have been rendered. If you would like to learn more about how browsers handle script, read Timing and Synchronization in JavaScript.

Behavior Injection and Modification: It’s quite easy to add “onclick” and “onmouseover” attributes to HTML elements to add client-side interactivity. Unfortunately, this results in horrible markup that is difficult to maintain and difficult to debug. Widgets force you to use behavior injection and modification in order to attach events to DOM elements. This keeps all behavioral code in one location and makes it incredibly easy to maintain through good use of jQuery selectors. It’s also results in a cleaner separation between the markup and the script.

Hopefully this information has provided you with enough knowledge to understand when Widgets are a good idea and when they are not. Now let’s take a deeper look at the client-side page life-cycle to understand the Widget rendering process.

Widget Rendering Process

Widgets are rendered only if the Site Setting “Enable Skin Widgets” is checked. This value is checked by default, so you can be assured that Widgets will render on most DotNetNuke sites. (We should probably re-name this setting to “Enable Client-side Widgets”…when I was first coding the Widget framework, I was focused on usage scenarios involving skins and used the term “skin widgets.” The term stuck even though Widgets can be used in any DotNetNuke extension that renders code to the browser.) By enabling this setting, a single reference to a Javascript file is injected into the very end of the page:

<script type="text/javascript" src="/Resources/Shared/scripts/initWidgets.js"></script>

When the script loads, it initiates a four-step process: Framework Initialization, Widget Detection, Widget Instantiation and Widget Rendering. This process is illustrated below:

The Widget framework uses jQuery to load all required scripts in an asynchronous manner. When a script is done loading, an event is fired to carry out the next step in the rendering process. All of this happens pretty fast, and most notably, after the page is already rendered in the browser. If you view the HTML source for the page, you will see no difference in the markup from what was originally sent by the server (i.e. <object> elements). However, if you query the DOM using FireBug or a similar tool, you will see that each <object> Widget element has been replaced with a <div> or similar element with the same ID as originally given to the <object> element. This enables you to use CSS for styling the Widget using an ID selector (i.e. #MyWidget).

In this post, I provided an introduction to the DotNetNuke Widget Framework. In the next post in this series, I will introduce you to the Widgets included with DotNetNuke and provide a usage reference for each Widget.

(Click for larger image)

In an increasingly hyper-competitive world, businesses look for every possible opportunity that can give them an edge over their competition. It’s no secret — businesses that innovate survive and win, and those that don’t either die, don’t grow or become the walking dead.

But innovation isn’t easy. In fact, it is a challenge for most companies. There are many reasons for this – corporate culture, inertia, risk-aversion – but I think the biggest reason is “expertise.” The quote I have on my desktop wallpaper sums it up nicely:

“In the beginner’s mind there are many possibilities, in the expert’s mind there are few.”

– Shunryu Suzuki

I have this quote on my desktop because it’s a constant reminder that as I become more familiar with a technology or business skill, my ability to come up with innovative ideas about that technology or business area decreases. This is my totally unscientific thesis at a personal level; your experience may differ, but I suspect not by much. Since businesses are primarily just people doing stuff, the corollary is that businesses face the same issue – dearth of innovation due to expertise.

So if a business can’t look internally to its employees, where should it look for those innovative ideas that will propel it to the next level? (NO, the answer is definitely not consultants.) The best source of innovative ideas for your business is your customers and the best place to engage them for these ideas is online.

Many companies have discovered that the same concepts that work amazingly well on a personal and social level with FaceBook and MySpace, work equally well for business (albeit without any sheep being thrown about in the process). Creating an online community for your business is an effective way to engage your customers online and provide a direct channel to them, bereft of the hierarchical and departmental boundaries that stifle discussion and open dialog offline. This should not come as a surprise, after all “people want to connect with people; people want to help and be helped” (Study: Tribalization of Business). Chances are that if you follow some basic guidelines, you can very quickly and easily engage your customers and make innovation an open and collaborative process.

One company that has been successful in creating such an online customer community is ExactTarget. The company has been a long-time sponsor of the DotNetNuke project (thanks!). The “3sixty” community site it created for its customers using DotNetNuke Professional Edition is a prime example of best practices for creating online communities recommended by HiveLive, a SAAS provider of enterprise online customer communities. Since 3sixty was created, the site has become a key competitive differentiator for ExactTarget resulting in over 100 customer-suggested feature innovations into its product. You can get the straight scoop on how ExactTarget achieved this by attending the free webinar “ExactTarget: Using DotNetNuke to Build an Interactive Business Community” on Aug. 26, 2009 (download a recording of the video by following the link if you are reading this after Aug. 26).

While ExactTarget could have developed a custom ASP.NET solution for this site, it selected DotNetNuke because of its ability to easily integrate with existing web-based business applications while providing a robust platform for rapid application development. Let me stop myself right here and not get carried away discussing the merits of DotNetNuke as an excellent platform for building online communities. It is very tempting to look at creating such communities as a technology problem and delve into a discussion about features, API’s and such. But as Dion Hinchcliffe accurately points out in Twelve Best Practices for Online Customer Communities, “community is mostly not a technology problem.” Indeed, as he points out, platforms like DotNetNuke make it easy to create compelling communities. (If you are reading this on DotNetNuke.com, you are looking at the best evidence to support this claim.) Creating successful online business communities is more an exercise in adapting your business to a new form of customer engagement and creating the social architecture for such a community.

In order to succeed, here is a summation of HiveLive’s recommendations:

Best Practice #1: Build a community with clear goals in mind Start with a narrow and tightly defined scope and develop the community structure from there. This is essential for rallying members and motivating them to contribute. Be prepared to expand the scope quickly as the community evolves.

Best Practice #2: Motivate your members Online community members are power users, participants or spectators. Explore ways to keep power users engaged to ensure a steady stream of relevant and authentic content. This in turn will motivate others to play a more active role. Also, think of ways in which you can compensate participants. Compensation, does not have to be monetary – insider status, avatars, recognition, they all work.

Best Practice #3: Use Design Thinking Principles Design Thinking is a process for practical, creative resolution of problems or issues that looks for an improved future result. Using this approach can establish ground rules and foster a culture of crowd-sourced innovation in an online community.

Best Practice #4: Build a Culture of Openness Direct engagement through genuine interactions will yield significant benefits and convince more members to participate in the innovation process. Don’t try to control the conversation, listen more than you talk, and make sure the culture of openness is not just a façade. Although painful at first, such a culture is critical to the success of an online community.

Best Practice #5: Remain Dedicated to Continuous Improvement View your online community as a journey, instead of a technology initiative with a defined end-point. Committing to a posture of cultivation will yield tangible results in the form of a steady flow of innovative ideas from the community. This also builds trust and gives members a greater sense of ownership as their ideas and suggestions are realized.

Has your company created an online business community? Do share! What were the challenges you faced? What did you learn from the experience?

If you have not created an online business community yet, hopefully this post and the webinar will give you some ideas that will help guide you in the process.