TechBubble » Software

Subway Map Visualization jQuery Plugin

nik — Fri, 08 Oct 2010 20:15:11 +0000

I have always been fascinated by the visual clarity of the London Underground map. Given the number of cities that have adopted this mapping approach for their own subway systems, clearly this is a popular opinion. At a conference some years back, I saw a poster for the Yahoo! Developer Services. They had taken the concept of a subway map and applied it to create a YDN Metro Map. Once again, I was in awe of the visual clarity of this map in helping one understand the various Yahoo! services and how they inter-related with each other. I thought it would be awesome if there were a pseudo-programmatic way in which to render such maps to convey real-world ecosystems. A few examples I can think of:

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

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.

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:

Accordion
Autocomplete

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:

Accordion
Autocomplete

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.

Accordion
Autocomplete

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:

Accordion
Autocomplete

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.”



Accordion


Autocomplete

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.)

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.



Accordion
X

X
 
X

X
  



X

X




Tabs




 
 
X

X
X
X

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 (
will not work since the only markup supported for a label is the element).

Labels are added as absolutely positioned 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.



Accordion
Auto\ncomplete

Slider
 
Date\npicker

Dialog
  



Button

Progress\nbar




Tabs




 
 
Selectable

Resizeable
Droppable
Draggable

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-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)

The Seven Sins of DotNetNuke Module Developers

nik — Sat, 30 Jan 2010 00:29:14 +0000

In an average week, I communicate on the phone, by email, through webinars and in person, with some 100 DotNetNuke business customers, prospects and partners. A majority of them use DotNetNuke in some mission-critical way. I enjoy these conversations and get many insights on their real-world experience with DotNetNuke. I have noticed that there are some common things that end-users find problematic with Core and/or third-party extensions they use with DotNetNuke. It occurred to me that it would be good to share this information since not all extension builders may be aware of the issues that sometimes arise due to the way a particular extension is built. In order to make the information easy to digest (and because lists are cool), I am going to present these observations using a “Seven Sins…” theme.

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

Inline Style Attributes

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:

). 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.

Unfiltered User Input

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.

Hard-coded Text

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.

UpdatePanel

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.

Non-Semantic Markup

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.

Custom Settings

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.

No script tokens

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.

Module Print Widget for DotNetNuke

nik — Wed, 30 Dec 2009 01:50:09 +0000

If you are like me and want your websites to have a clean, unblemished look, then most likely you have either turned off the Print functionality in your DotNetNuke module settings or just use containers that don’t display the icon. While this does make the site look cleaner, it also takes away the functionality. I gave this some thought and concluded that a Widget would be a great way to provide the functionality for printing the content of modules on a page. I envisioned a selector that the user would click on that would allow them to print the content for a single module. A skin designer could embed the Widget directly into the skin, or a site administrator could selectively add it to pages using an HTML module.

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):

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

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>

DotNetNuke Widgets Guide (Part 1 of 4)

nik — Sat, 26 Dec 2009 05:00:43 +0000

Starting with Release 5.x, the DotNetNuke platform has included a Javascript-based Widgets framework for dynamically injecting client-side interactivity into skins and modules. Like most Open Source developers, I thoroughly enjoyed coding the Widget framework but neglected to document it properly. In this four-part series I hope to correct this shortcoming. In Part 1, I will introduce some fundamental concepts of the DotNetNuke Widget Framework. In Part 2, I will provide a reference for existing widgets that are included with DotNetNuke. In Part 3, I will step through the process of developing a Widget. Finally, in Part 4 I will create a working Widget that you can download and use to increase your understanding of the framework and to build your own Widgets.

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