Let’s suppose we want to represent an arithmetic operation on two numbers – such as plus, minus, multiply, etc. We could represent that operation as an enum (although to be clear – I don’t think you should):

enum ArithmeticOperation
{
  Add,
  Subtract,
  Multiply,
  Divide
}

We could then define a function to apply this operation to two numbers (highlighting will be explained later):

int ApplyOperation(ArithmeticOperation op, int x, int y)
{
  switch(op)
  {
    case ArithmeticOperation.Add: return x + y;
    case ArithmeticOperation.Subtract: return x - y;
    case ArithmeticOperation.Multiply: return x * y;
    case ArithmeticOperation.Divide: return x / y;
    default: throw new InvalidOperationException();
  }
}

That’s… sort of fine – but what happens when we want to extend it?

Adding Operators: No Compile-Time Checking

Let’s consider what happens if we want to add another operator – say exponentiation. If we add the enum value but forget to implement the switch case value, everything compiles fine. It’s only once we come to run the code, and actually hit that code path, that we discover the mistake, giving a run-time exception.

Adding Methods: Bad Code Organisation

Next, imagine what happens if we need to add more methods that switch on this enum. We might need a method returning the operator symbol, and another returning the operator precedence.

string GetOperatorSymbol(ArithmeticOperation op)
{
  switch(op)
  {
    case ArithmeticOperation.Add: return "+";
    case ArithmeticOperation.Subtract: return "-";
    case ArithmeticOperation.Multiply: return "*";
    case ArithmeticOperation.Divide: return "/";
    default: throw new InvalidOperationException();
  }
}

int GetOperatorPrecedence(ArithmeticOperation op)
{
  switch(op)
  {
    case ArithmeticOperation.Add: return 10;
    case ArithmeticOperation.Subtract: return 10;
    case ArithmeticOperation.Multiply: return 20;
    case ArithmeticOperation.Divide: return 20;
    default: throw new InvalidOperationException();
  }
}

I’ve highighted the relevant code for the “add” operator. Notice how it’s spread all over the place. Switch statements might group by operation, but they split by concept – and that’s the exact opposite of what’s usually intended with OO coding.

A Better Way

I’d suggest a better way of approaching this problem is to use an abstract class.

abstract class ArithmeticOperation
{
  abstract int ApplyOperation(int x, int y);
  abstract string GetSymbol();
  abstract int GetPrecendence();
}

class AddArithmeticOperation : ArithmeticOperation
{
  override int ApplyOperation(int x, int y)
  {
    return x + y;
  }

  override string GetSymbol()
  {
    return "+";
  }

  override int GetPrecedence()
  {
    return 10;
  }
}

// ...and so forth for the other operators.

That way, all the code for each operator sits in the same place, and adding any new methods for an operator requires all operators to be implemented before the code will even compile.

When to Use Enums

So if enums should be avoided, why do most languages include them? Personally I’d be happy without them,  but I can think of one possible reason you might want to use an enum. If you’re defining a public interface designed for consumption by other coders, you could argue that simplifying the interface at the expense of the code inside is a valid trade-off.

I’m sure most web developers know about image rollovers (using separate images for normal and “hover” states of anchors). Hopefully also the use of “CSS Sprites” is becoming better known – combining the normal and rollover images into a single physical image file to speed up load times and reduce flicker. I won’t cover those techniques here.

However, if you want the anchor or button to size to its contents, it’s more difficult to make use of these techniques. Here’s one way.

(The final result – view demo).

Start With Markup

Before diving into fancy techniques, get the markup down as you would like it, if you didn’t have to style anything.

<a href="..." class="rollover">Button Text</a>

Ideally we want the markup to be clean and not compromised by styling requirements.

Handle Degradation Gracefully

My technique is going to make use of JavaScript, so let’s handle the case where the user has it disabled for some reason. Here’s some very basic CSS to give the button a simple style:

a.rollover
{
  background-color: #00f;
  border: solid 1px #000;
  color: #fff;
  font-weight: bold;
  padding: 4px;
  text-decoration: none;
}

a.rollover:hover
{
  background-color: #008;
}

Add Styling Naively

Next, I’m going to add some rollover styling – but in a way that isn’t complete. Firstly I created a simple rollover image, but made it very wide – it needs to be at least as wide as the widest button is ever going to be:

I’m going to define my rollover styling against a class selector of “extra” – you’ll see where that comes from in a moment.

a.rollover.extra
{
  background: url(buttons.png) repeat-x left 0;
  border: none;
  height: 27px;
  padding: 23px 40px 10px 40px;
  position: relative;
}

a.rollover.extra:hover
{
  background-position: left -57px;
}

Note that we’ve had to undo some of the styles applied previously, such as border.

We’re kind of getting there, but our buttons won’t look correct on the right-hand-side.

Use JavaScript To Add Styling Markup

To fix the right-hand end-caps, we need to modify our markup. However, I really don’t want to have to do that on my pages – afterall, I might change my mind about the site styling.

Here I recommend using JavaScript to tweak at runtime the markup to what we need. I’m going to use jQuery for this:

$(function() {
  $('.rollover')
    .addClass('extra')
    .append('<div class="cap"></div>');
});

Basically, when the pad is ready, I find all elements with class “rollover”, add another class (“extra”), and append into the rollover button an empty span element which has a class of “cap”.

That class “extra” triggers the image rollovers. The “cap” span can be styled as follows:

a.rollover.extra .cap
{
  background: url(buttons.png) no-repeat right 0;
  height: 100%;
  position: absolute;
  right: 0;
  top: 0;
  width: 40px;
}

a.rollover.extra:hover .cap
{
  background-position: right -57px;
}

And voila!

If you’d like to see this technique in action, please view the demo.

Unfortunately, it seems that installing Internet Explorer 8 (IE8) sometimes has some adverse affects on other applications. Here’s how to fix this.

The problems we’ve experienced following installation of IE8 have been:

• Windows Explorer opens folders in new windows, even if you have “Open each window in the same folder” checked;
• “Open in new tab” doesn’t work in IE8;
• Can’t connect to databases using SQL Management Studio Express 2008 (”Unable to cast COM object of type ‘System.__ComObject’ to interface type ‘Microsoft.VisualStudio.OLE.Interop.IServiceProvider’. Exception from HRESULT: 0×80004002 (E_NOINTERFACE)”).

The solution is pretty simple:

1. Go to Start -> All Programs -> Accessories, right-click “Command Prompt”, and choose “Run as Administrator”.
2. OK the user access warning dialogs.
3. Enter “regsvr32 actxprxy.dll”.
4. Reboot.

Simples! No more tearing my hair out.

One common example (that we make use of heavily in EasyAs123Web.com) is using a handler to serve and generate images on-the-fly. Our user images are stored in the database, and are immutable – they never change. Hence we’d like the client browser to cache the image returned.

Example Handler

Let’s start with the shell of a generic handler, MyHandler.ashx.cs:

public class MyHandler : IHttpHandler
{
  public void ProcessRequest( HttpContext context )
  {
    ...
  }

  public bool IsReusable
  {
    get
    {
      return true;
    }
  }
}

Further code will go where I’ve marked with ellipses.

Reponse Headers

For some reason, ASP.NET automatically adds headers that stop the browser from caching the content, and you can’t just override them. Instead, you’ll need to clear them all out first:

context.Response.ClearHeaders();

Next we want to mark the content as fully cacheable, and expiring at some date in the future:

context.Response.Cache.SetValidUntilExpires( true );
context.Response.Cache.SetCacheability( HttpCacheability.Public );
context.Response.Cache.SetExpires( DateTime.Now.AddMonths( 1 ) );
context.Response.Cache.SetLastModified( DateTime.Now.AddMonths( -1 ) );

(I’ve marked the content as expiring in a month, but you could easily add a year or ten years or whatever).

If you are able to calculate some form of hash for your content (which you should be able to do pretty easily), you can add an ETag:

Guid hash = ...;

context.Response.Cache.SetETag( "\"" + hash.ToString().Replace( "-", "" ) + "\"" );

Finally, there’s one more trick which is incredibly useful for allowing browsers to avoid re-downloading the content.

Browsers may include the “If-Modified-Since” request header. If you ignore this header, no problems occur: you just send the content as usual. However, you can use it to inform the browser that your content hasn’t changed since the last time it was requested.

If your content really hasn’t changed, instead of sending a “200 OK” response with all the content, you can send back a “304 Not Modified” without any content whatsoever:

var textIfModifiedSince = context.Request.Headers["If-Modified-Since"];

if( !string.IsNullOrEmpty( textIfModifiedSince ) )
{
  context.Response.Status = "304 Not Modified";
  context.Response.End();

  return;
}

So instead of sending back a potentially large piece of content, you can send back just the tiny response headers.

You can do a similar trick with “If-None-Match” – I’ll leave that as an exercise.

Debugging

Making these changes is all very well, but can you be sure that your changes are actually having the desired effects?

There are two great tools you can use to actually view the requests sent by the browser, and the response sent from your web-app:

• For debugging with Firefox: Live HTTP Headers.
• For Internet Explorer: Fiddler 2.

If you care about the speed and bandwidth usage of your ASP.NET application, I’d say that these two are pretty much indispensable. You’ll want to test with both: different browsers make subtly different requests, and interpret the responses differently.

You might also want to use YSlow for Firebug: this has some nice graphical displays of page assets.

Example – Content Not In Cache

Request and response, some lines omitted for clarity.

GET /!!/_Serving/StaticFile/Style/Pro/Images/HomeCreate.jpg HTTP/1.1
Host: www.easyas123web.com

HTTP/1.x 200 OK
Cache-Control: public
Content-Type: image/jpeg
Expires: Mon, 01 Jun 2009 08:58:36 GMT
Last-Modified: Wed, 01 Apr 2009 08:58:36 GMT
Etag: "45403f772717d1c63c0b8774e4a124b7"
Content-Length: 20696
... 20K of content here ...

Example – Content In Cache

Request and response, some lines omitted for clarity.

GET /!!/_Serving/StaticFile/Style/Pro/Images/HomeCreate.jpg HTTP/1.1
Host: www.easyas123web.com
If-Modified-Since: Wed, 01 Apr 2009 08:58:36 GMT

HTTP/1.x 304 Not Modified
Cache-Control: public
Expires: Mon, 01 Jun 2009 09:03:51 GMT
Last-Modified: Wed, 01 Apr 2009 09:03:51 GMT
Etag: "45403f772717d1c63c0b8774e4a124b7"

Let’s start with an example graphic, Arrow.xaml:

<UserControl x:Class="WebImagesGenerator.Graphics.Arrow"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  Height="64" Width="64">
  <Canvas Width="64" Height="64">
    <Polygon Points="32,4 60,32 42,32 42,60 22,60 22,32 4,32"
      Fill="Red" Stroke="Black"
      StrokeThickness="3" StrokeLineJoin="Round" />
  </Canvas>
</UserControl>

That’s just a standard XAML file, nothing fancy there.

Rendering WPF content to an image is really easy; you use the RenderTargetBitmap class. I wanted to be able to produce a strip of images, all the same except rotated, that can be used as CSS sprites. For my actual web application, I have a quick console application that generates the images as a batch. If I ever change the XAML files, I can quickly re-generate all the auto-generated images in my project just be running my console application.

Let’s get started on the console application:

[STAThread]
static void Main( string[] args )
{
  var arrow = new Graphics.Arrow();

  SaveStrip( arrow, GenerateSeries( 0, 360, 10 )
           , "..\\..\\Testing\\arrows.png" );
}

WPF must be run in a [STAThread] context. I create an instance of my graphic, then call my SaveStrip routine. GenerateSeries simply returns an array of integers:

static int[] GenerateSeries( int start, int end, int step )
{
  var series = new List<int>();

  for( var v = start; v < end; v += step )
  {
    series.Add( v );
  }

  return series.ToArray();
}

The real magic happens in SaveStrip:

static void SaveStrip( FrameworkElement fe, int[] angles, string filename )
{
  var outer = new Canvas();

  outer.Width = fe.Width * angles.Length;
  outer.Height = fe.Height;

  outer.Children.Add( fe );

  outer.Arrange( new Rect( 0, 0, outer.Width, outer.Height ) );

  var bmp = new RenderTargetBitmap
    ( (int) fe.Width * angles.Length
    , (int) fe.Height, 96, 96, PixelFormats.Pbgra32 );

  for( var i = 0; i < angles.Length; ++i )
  {
    var transforms = new TransformGroup();

    transforms.Children.Add
      ( new RotateTransform( angles[i], fe.Width / 2, fe.Height / 2 ) );

    fe.RenderTransform = transforms;
    fe.SetValue( Canvas.LeftProperty, i * fe.Width );

    // The following line is VITAL!
    outer.Arrange( new Rect( 0, 0, outer.Width, outer.Height ) );

    bmp.Render( fe );
  }

  var encoder = new PngBitmapEncoder();

  encoder.Frames.Add( BitmapFrame.Create( bmp ) );

  using( var stream = File.Create( filename ) )
  {
    encoder.Save( stream );
  }
}

When I first tried this technique, all my output bitmaps were completely blank. After debugging for a while, I realised that all my graphics were of zero size. You MUST call Arrange() on your elements before calling Render(), otherwise they won’t have been laid out properly.

When run, this console app produces the following (reduced in size to fit):

Fantastic! To get a better idea of how such images might appear in a web-page, I’ve created a little HTML+jQuery demo to see a very quick example of the images in use:

View Demo

The problems we’ve experienced following installation of IE8 have been:

• Windows Explorer opens folders in new windows, even if you have “Open each window in the same folder” checked;
• “Open in new tab” doesn’t work in IE8;
• Can’t connect to databases using SQL Management Studio Express 2008 (“Unable to cast COM object of type ‘System.__ComObject’ to interface type ‘Microsoft.VisualStudio.OLE.Interop.IServiceProvider’. Exception from HRESULT: 0×80004002 (E_NOINTERFACE)”).

The solution is pretty simple:

1. Go to Start -> All Programs -> Accessories, right-click “Command Prompt”, and choose “Run as Administrator”.
2. OK the user access warning dialogs.
3. Enter “regsvr32 actxprxy.dll”.
4. Reboot.

Sorted! No more tearing my hair out.

Simplifying things a little, every file you serve to a browser comes with an expiration date. This can be an immediate expiration (as you’d set for dynamic pages), or sometime in the future. Generally, if the browser needs a particular file again, and it hasn’t expired, it will try to use a cached copy, and not ask your server for it again.

Let’s consider stylesheets and scripts.

• They are required on every page view;
• They don’t change often;
• But when they do change (eg a bug fix), you want your users to see the changes.

With standard content expiration, we have three choices:

• They could expire immediately – however this would mean they would be re-requested every page view;
• They could expire after a a set length of time (say a day) – this is a compromise, meaning they would only be re-requested at most every day, but bug fixes would take a day to appear;
• They could never expire – the user would have to explicitly refresh the page to get any changes.

None of these options are ideal, but there is a better way.

Content Should Expire Only When It Changes

If we had the time, we could version every file. We’d start with ‘stylesheet-1.css’, and when it changed, rename it to ‘stylesheet-2.css’, and fix up every single reference in the website to the new name. If the content expiration for these versioned files was set to ‘never’ (or a long time in the future), we would have solved the problem.

Doing that by hand would be a real pain – hence we need an automated way. An alternative to integer versioning is a hash – whenever the content changes, the hash will too – and to save the trouble of renaming files, we can easily add the hash as a query string. Of course, you’ll need to make sure that the content expiry of these hashed files is marked as ‘never’ – either via IIS, or via some form of static-file handler.

The following code shows how to automatically add these hashes. The pattern I’m going to use is a UserControl, into which we place script or stylesheet references, for example:

<%@ Register TagPrefix="co" TagName="CacheControl" Src="~/.../CacheControl.ascx" %>

<co:CacheControl runat="server">
  <link rel="Stylesheet" href="Path/To/Reset.css" />
  <link rel="Stylesheet" href="Path/To/Base.css" />
</co:CacheControl>

The output will be something like:

<link rel="Stylesheet" href="Path/To/Reset.css?hash=567164ca-96c5-6305-a697-a12be0f98499" />
<link rel="Stylesheet" href="Path/To/Base.css?hash=6a11adca-1593-a529-a574-735cb308a9a7" />

Source Code

To support this pattern of usage, we’ll need to add a couple of attributes:

[ParseChildren( false )]
[PersistChildren( true )]
public partial class CacheControl : System.Web.UI.UserControl
{
  ...
}

Now on to the main code. Basically, the UserControl needs to get the concatenated text of the controls inside itself, transform that text (adding the hashes), then replace its own content:

protected void Page_Load( object sender, EventArgs e )
{
  var content = string.Empty;

  foreach( Control control in Controls )
  {
    var literal = control as LiteralControl;
    var generic = control as HtmlGenericControl;

    if( literal != null )
    {
      content += literal.Text;
    }
    else if( generic != null )
    {
      var text = "<" + generic.TagName + " ";

      foreach( string key in generic.Attributes.Keys )
      {
        text += key + "=\"" + generic.Attributes[key] + "\" ";
      }

      text += "/>";

      content += text;
    }
    else
    {
      throw new InvalidOperationException();
    }
  }

  content = content.Trim();

  Controls.Clear();

  lock( _lock )
  {
    string output;

    if( !_mapInputToOutput.TryGetValue( content, out output ) )
    {
      output = ApplyCacheControl( Context, content );

#if !DEBUG
      _mapInputToOutput.Add( content, output );
#endif
    }

    Controls.Add( new LiteralControl
    {
      Text = output
    } );
  }
}
private static object _lock = new object();
private static Dictionary<string, string> _mapInputToOutput = new Dictionary<string, string>();

(Since the same conversions will be applied over and over, I’m storing the results. I’m also assuming that whenever the file content changes, the web server will be re-started).

The next part parses the content as XML, iterates over the sub-items, determines which attribute contains the path, and writes back the transformed filename:

private string ApplyCacheControl( HttpContext context, string input )
{
  var xdoc = XDocument.Parse( "<root>" + input + "</root>" );
  var sb = new StringBuilder();

  sb.Append( Environment.NewLine );

  foreach( var child in xdoc.Root.Elements() )
  {
    var linkAttrName = GetLinkAttribute( child );
    var sourceFile = child.Attribute( linkAttrName ).Value;

    var hash = GetFileHash( sourceFile );

    child.Attribute( linkAttrName ).Value = TransformFilename( context, sourceFile, hash );

    var childText = child.ToString();

    if( childText.StartsWith( "<script" ) && childText.EndsWith( "/>" ) )
    {
      childText = childText.Substring( 0, childText.Length - 2 ).Trim() + "></script>";
    }

    sb.Append( childText );
    sb.Append( Environment.NewLine );
  }

  return sb.ToString();
}

private static string GetLinkAttribute( XElement element )
{
  switch( element.Name.LocalName )
  {
    case "link":
      return "href";
    case "script":
      return "src";
    default:
      throw new InvalidOperationException();
  }
}

Calculating the hash of the file is pretty easy:

private Guid GetFileHash( string filename )
{
  var baseUri = Code.Site.Path.GetBaseUri( Request );

  if( filename.StartsWith( baseUri.AbsoluteUri ) )
  {
    filename = filename.Substring( baseUri.AbsoluteUri.Length );
  }

  filename = filename.Replace( '/', '\\' );

  var localPath = Path.Combine( Request.PhysicalApplicationPath, filename );
  Guid hash;

  if( !_mapFileToHash.TryGetValue( localPath, out hash ) )
  {
    var ms = new MemoryStream();

    using( var fs = new FileStream( localPath, FileMode.Open, FileAccess.Read, FileShare.Read ) )
    {
      Utility.StreamCopy( fs, ms );
    }

    var myMD5 = new System.Security.Cryptography.MD5CryptoServiceProvider();
    var hashedTextInBytes = myMD5.ComputeHash( ms.ToArray() );

    hash = new Guid( hashedTextInBytes );

#if !DEBUG
    _mapFileToHash.Add( localPath, hash );
#endif
  }

  return hash;
}
private static Dictionary<string, Guid> _mapFileToHash = new Dictionary<string, Guid>();

(Again, cached for speed).

Here’s my utility stream copy routine:

public static class Utility
{
  public static void StreamCopy( Stream from, Stream to )
  {
    if( from == to )
    {
      return;
    }

    var buffer = new byte[4096];

    from.Seek( 0, SeekOrigin.Begin );

    while( true )
    {
      var done = from.Read( buffer, 0, 4096 );

      if( done <= 0 )
      {
        return;
      }

      to.Write( buffer, 0, done );
    }
  }
}

Finally, the function to transform the filename:

private string TransformFilename( HttpContext context, string filename, Guid hash )
{
  filename += "?hash=" + hash.ToString();

  return filename;
}

You might be wondering why I passed the HttpContext all the way through to this function, only to not use it. Well in my code I do use it – I further transform the filename to pass it onto a handler for static files, that sets the expiry to ‘never’.

[Updated 01 Feb 2009 - I've added the debug conditionals to make debugging a little easier - now in debug you can change your scripts and stylesheets on the fly and the browser will get the latest version.]

What confused me originally is that HttpCookieCollection contains a Remove method. This doesn’t remove cookies from the user’s browser. It only removes the cookie entry from the local collection. What you have to do is force the user’s browser to delete the cookie itself. The way to do this is to add an expired cookie: the browser will then clean up the cookie itself.

void DeleteCookie( HttpContext context, string name )
{
  var cookie = context.Request.Cookies[name];

  if( cookie != null )
  {
    cookie.Expires = DateTime.Now.AddYears( -30 );

    context.Response.Cookies.Add( cookie );
  }
}

Note that I’m looking up the cookie in the request, but adding the expired cookie in the response.

Click here for a demo of the code in this example.

Imagine There’s No JavaScript

The first thing you need to do before writing a plug-in is to consider what pattern of HTML elements you’re trying to re-present to the user. One useful starting point is to imagine how you’d present the information if there was no such thing as JavaScript. Since I want to present an address, my semantic HTML will look something like this:

<div class="address">
  2 Bradford Close, Exmouth, EX8 5PF
</div>

That is, in the absense of JavaScript, my page will still make some sort of sense. Another way of thinking about this is that my page will gracefully degrade if the user doesn’t have JavaScript enabled (or, for instance, if Google crawls my site).

jQuery Plug-In Architecture

To create a plug-in method that jQuery can make use of, simply add it to the ‘fn’ property of jQuery:

jQuery.fn.createInlineVirtualEarthMap = function() { ... }

Remember that jQuery allows us to operate on sets of elements. When developing a plug-in, these elements are available via the ‘this’ keyword. Since we usually want to operate on all of the elements, a plug-in function usually has the form:

jQuery.fn.createInlineVirtualEarthMap = function() {
  return this.each(function() { ... });
}

(The value of the ‘each’ function call is returned to permit chaining).

Virtual Earth API

Note: I’ve used the Virtual Earth API here instead of Google Maps because of ease-of-use issues: although I think Google Maps is the better product (and easier API), Google has unfortuntely decided that to use their API you must either apply for a key (locked to one domain), or include some obfuscated characters (locked to one address). Since this code is based on that of EasyAs123Web.com, which allows users to create their own domains, I’ve been forced to use Virtual Earth.

Before using the Virtual Earth API, you must obviously include the appropriate script:

<script charset="UTF-8" type="text/javascript"
  src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2&mkt=en-gb"></script>

With that in place, you can then create a map in an element using code such as this:

var map = new VEMap('id-of-map-div');
map.LoadMap();
map.HideDashboard();
map.Find(null, 'street address', null, null, 0, 1, true, true, true, true,
  function() { map.SetZoomLevel(16); });

(I’ve picked a few appropriate values to simply select the first found address. I’m using a callback on the ‘Find’ method to set the zoom level to a hardcoded value).

Generating IDs

As you can see, the Virtual Earth API expects to be passed the ID of the control to create a map in. But what if the element doesn’t have an ID, as in my example?

There’s a useful function you can add to jQuery for cases like this:

if (!jQuery.generateId) {
  jQuery.generateId = function() {
    return arguments.callee.prefix + arguments.callee.count++;
  };
  jQuery.generateId.prefix = 'jq$';
  jQuery.generateId.count = 0;

  jQuery.fn.generateId = function() {
    return this.each(function() {
      this.id = $.generateId();
    });
  };
}

Note that the function can either be called as a ‘static’ method:

var id = $.generateId();

Or as a query method:

$('.whatever').generateId();

(And also note that it’s added to jQuery as a plug-in method, exactly as described earlier).

The Final Plug-In

So now we have everything necessary to create our plug-in:

jQuery.fn.createInlineVirtualEarthMap = function() {
  return this.each(function() {
    if (!this.id) {
      $(this).generateId();
    }

    var address = $(this).text();
    var map = new VEMap(this.id);

    map.LoadMap();
    map.HideDashboard();
    map.Find(null, address, null, null, 0, 1, true, true, true, true,
      function() { map.SetZoomLevel(16); });
  });

Of course, if you were creating a plug-in for general use, you’d probably want to allow the user to pass parameters to control the zoom level and other aspects of the map, but since the purpose of this tutorial is only to demonstrate the basics of creating jQuery plug-ins, I haven’t bothered.

Client Code

To use this plug-in, it’s a simple matter to call it from a jQuery selector:

$('.address').createInlineVirtualEarthMap();

(In the linked example I’ve applied a style to the class to assign a width and height to the map, and the above call is made in a document.ready block).

Click here for a demo of the code in this example.

I’ll start with an example. Suppose I have a HTML table, and I’d like to do two things:

1. Make it easier to scan visually by applying alternating row colors;
2. Make it easier to read by having a hot-tracking highlight bar over the rows.

CSS Styling

Before we jump into the jQuery, we need to define a couple of styles in the stylesheet:

.alt { background-color: #ddd; }
.hover { background-color: #aaf !important; }

The jQuery Script

Now that’s sorted, here’s the jQuery:

$(function() {
  $('table tbody tr:odd').addClass('alt');

  $('table tbody tr').hover(function() {
    $(this).addClass('hover');
  }, function() {
    $(this).removeClass('hover');
  });
});

If you’d like to see a working example, just visit this page, and view source.

Dollars Dollars Dollars

The most noticable aspect of a jQuery script is all the dollar signs. Just as C/C++ allow underscores in function names, JavaScript allows dollar signs in identifiers. And just as a single underscore would be a valid (albeit unusual) function name in C/C++, so a single dollar sign is a valid identifier name in JavaScript.

So the first line that begins ‘$(…’ is calling a function called ‘$’. If this bothers you, you can also call jQuery functions using the jQuery identifier. (In other words, ‘jQuery(…)’ is a synonym for ‘$(…)’).

Functions in Functions

JavaScript is a very expressive language, and unlike the C family of languages, treats functions as first-class citizens that can be treated just like any other object. The jQuery script above has the following form:

$(function() {
  ...
});

Or to put it another way, we are calling the function ‘$’, passing a single argument, which is itself an anonymous function.

In jQuery, this is shorthand for attaching an event to be fired when the DOM is ready. So to recap, the anonymous function body (marked ‘…’ above) will be called when the document is ready.

DOM Querying and Manipulation

So we’ve now established that the two statements within the anonymous function will be called once, when the document is ready. Let’s consider the first statement:

$('table tbody tr:odd').addClass('alt');

Hopefully this statement is a lot easier to understand than the last section. We call a function (‘$’, as usual), passing a string as a parameter, which returns some object, on which we call a function, passing a second string. (Strings in JavaScript may be enclosed with either single or double quotes).

jQuery functions (named ‘$’) are queries – they act on the DOM (or portion of it), and essentially return a set of matching elements. One major selling point of jQuery is that it presents a unified and more powerful version of CSS selectors – and they work cross-browser – so you don’t need to worry whether a particular selector works on Internet Explorer.

In the above statement, we want to select all ‘tr’ elements, that are children of ‘tbody’, that are children of ‘table’, and furthermore, only select those which are odd-ordered (i.e., at indexes 1,3,5, etc).

Once we’ve selected these elements, we can act on them as a whole using the various jQuery functions. In the statement above, the call to ‘addClass’ will add the named CSS class (‘alt’) to all elements returned from the query.

Basically, we wanted to write the following in our stylesheet:

table tbody tr:odd
{
  background-color: #ddd; // See stylesheet at top of page.
}

…but we couldn’t because ‘:odd’ isn’t a supported CSS selector. (Or at least, isn’t supported in many major browsers).

DOM Events

Onto the last stretch. The second statement is a multi-liner, but if we omit a few details, hopefully things will be clearer:

$('table tbody tr').hover(function() { ... }, function() { ... });

We’re querying the DOM, as before (for tr’s in tbody’s in table’s), then using the ‘hover’ function. The hover function is passed two parameters, both of which are anonymous functions.

The ‘hover’ method is one of a set of jQuery functions that allow you to attach events to the DOM. In the case of ‘hover’, the first function passed will be called when the mouse moves over the element, and the second called when the mouse moves out.

(Note that as before, these events will be attached to all elements returned by the query, even though there is only a single function call).

When calling the event handler functions, jQuery assigns the variable ‘this’ to the element to which the event applies. Wrapping the element in the ‘$’ syntax – $(this) – allows all the jQuery functions to be used on that element – in this case, addClass and removeClass.

Conclusion

This has been a longish article, and of course I’ve barely scratched the surface of what you can do with jQuery, but I’ve introduced the most important aspects. jQuery provides a browser-independent view of your document, and provides powerful methods for querying, modifying, and attaching events.