While I know the masses are just frothing at the mouth to throw their money at me, I urge anyone with a few spare dollars and a few spare moments to donate to the cause instead.  Your donation will help the new St. Josephs Surgical Center, the redevelopment of their new Mental Health facility, and zombie research.

PathJS:  Doesn't work in IE7

This ended up being a bug with Internet Explorer 8 or 9 in either Compatibility Mode or Quirks Mode.  IE8+ supports the "onhashchange" event, which PathJS binds to.  Unfortunately, when in Quirks Mode or IE7 Compatibility Mode, this event never gets fired.  The problem?  It's still reported as being supported.  I've added some secondary checks for IE to ensure that the proper methods get fired when in Quirks/Compatibility Mode.

PathJS: "Root Route" doesn't get executed on Android

This was just a condition of certain pieces of code being called in the wrong order.  A simple re-arrangement fixed the problem, and now it works and is tested on Android 2.3.5.

PollJS: Minified file is not up to date

When I fixed the "overwrite" bug in late Novemeber, I neglected to update the minified version of the file.  I've updated the minified file, and it can now be pulled into your projects to fix that bug.

In addition to fixing the issues and bugs on my existing projects, I've also been working on a project that aims to make client-side javascript logging and debugging a lot more powerful.  Expect a release of Lumberjack.js sometime in the very near future.

But what if that long running job never gets executed during this particular session?  And what if you have many different operations that need this type of implementation?  You've now got your global namespace polluted with oft-unused variables.  That's where PollJS steps in.

PollJS is a convenience wrapper for the native "setTimeout", "setInterval", "clearTimeout", and "clearInterval" methods.  It wraps them with a simple definition method, and extends their functionality with additional options:

// A Basic Example
Poll.start({
    "update_users",
    interval: 1500,
    action: function(){
        alert("Updated!");
    }
});

Poll.stop("update_users");

You can read more about the project, and download the source code on the Github page.

var isValid = new Chronicle(false); // Default the value to false

isValid.set("not valid"); // Set it to a string
isValid.set(true); // Set it to true

// This will return true if the value inside this Chronicle
// has ever been true, and return false otherwise.
isValid.was(false);

If anyone wants this functionality on your site, it's as easy as including/running the following javascript anywhere before you need to use a Chronicle (as long as it's within the proper scope, of course). Chronicle works in any scope, in any situation.

function Chronicle(val){
    this.value = val;
    this.history = [];
    if(val != undefined){
        this.history.push(val);
    }
}

Chronicle.prototype.set = function(val){
    this.value = val;
    this.history.push(val);
};

Chronicle.prototype.was = function(val){
    return this.history.indexOf(val) >= 0;
};

Chronicle.prototype.toString = function(){
    return this.value.toString();
}

Of course, my example above is a bit simplified, but it proves the point none the same.  No matter how complex the code that you're currently working on may seem, it's always within the realm of understandability.  Step back for several weeks, and walk into the hellish nightmare that is The Spaghetti Abyss, and you'll spend five minutes wondering, "What the hell was this fool doing?" followed by a brief flash of recollection and embarrassment - "Gasp! I am that fool!"

And therein lies the rub.

As soon as I finished my time in school, documentation seemed much less important.  You see, up until this point, students had been documenting merely to get the marks for it.  We documented our code because our grades depended on it.  As soon as I stepped out those doors for the final time, I remember thinking I was free of that nightmare.  I was a good programmer, I could look at code and understand what was happening under the hood; I didn't need an explanation.

Fast forward a couple of months, and I'm at work, trying to solve a particularly bad problem - a problem I inadvertently produced several weeks back, in a module that had since been left to stew in the bowels of a great beast of a project so terrifying, so insidious, it was Beelzebub incarnate (in code).  I open that file, thinking "This will be an easy fix - after all, I wrote it."  Never have I been more wrong in my life.  My undocumented code put a bucket over my head and slammed it with a baseball bat.  It took me several days to fix a bug that was incredibly simple, but my lack of documentation fanned the flames until my ego was burned to the ground.  I wasn't a good programmer anymore; a good programmer wouldn't have run into this problem.

Fast forward yet again.  I need to delve deep within the source code of ActiveSupport.  I'm looking at code written by the deities of code.  These men and women know Ruby from top to bottom, inside out, and to a peasant like me, it looked like they were making use of every trick in the book to get things done.  But, if that was the case, why was it so easy for me to understand everything?  Why was I able to follow along at a nice leasurely pace, instead of having my eyes melt off my face? Oh, I see now...

This code had documentation.  This code had a dictionary beside it, and I could find out what everything was doing every step of the way.  This code was easy.

It takes a situation like the one described above to let you know how important something really is.  You can be an amazing problem solver, and a prolific programmer, but you won't ever be considered one of the best until your code can be understood by thousands of people at a glance.  Now that I've got my own projects, I make sure that I do my best to document every code change.  I try to act like one of the best, because I'd like to be one of the best.

// Define all your routes as you usually would with PathJS - Simply omit the "#"
Path.map("/home").to(function(){
    console.log("Welcome home!");
});

Path.map("/users").to(function(){
    console.log("Users, users, users.");
});

Path.map("/contact").to(function(){
    console.log("Feel free to contact me via Github.");
});

// Now override the click events for any of your links, and call
// the Path.history.pushState method to invoke the PathJS router.

// This example uses jQuery.
$("a").live("click", function(event){
    event.preventDefault();
    Path.history.pushState({}, "", $(this).attr("href"));
});

It's simple as that.  The PathJS implementation of the HTML5 History API supports the same features as regular PathJS, including:  Before-filter chaining, enter/exit methods, parameterized routes, and optional route parameters.  You can read more about it's features and limitations on the Github Page.

Because of the reasons above, I never use these built-in methods.  I much prefer a nice, clear cut separation for my scripts, and I'll handle the work myself.

application.js // Our document.ready wrapper
functions.js // Any utility functions we might want
extensions.js // any jQuery extensions we write
routes.js // All of our PathJS routes

I put all of my JavaScript in it's proper place, and it enjoys life there.  But there's one problem - one minor thing that has always bothered me about handling this myself...constructing URLs.  There has been many times where dragging an item from one location to another needs to make an AJAX call to update a "position" or a "parent_id".  Every time these calls are needed, you'll see some code like this:

$.ajax({
    url: "/books/" + book_id + "/pages/" + page_id,
    data: {
        "position":"top"
    },
    success: function(response){
        alert("Hazaa!");
    }
});

There is absolutely nothing elegant about the way that URL is being constructed.  Well, now there's a better way.

Say "Hello," to js:routes.

js:routes provides a simple rake task that will take all of your existing routes and convert them into JavaScript functions that take the appropriate parameters.

# Calling this will generate ./public/javascripts/rails_routes.js
rake js:routes

# You can name the file anything else by doing this
rake js:routes[other_file.js]

Now, you can tidy up those dirty constructed URL's.

// This...
url: "/books/" + book_id + "/pages/" + page_id

// Becomes this!
url: book_pages_path({"book_id": book_id, "id":page_id})

Everything is nice and tidy.  You can read more about it on the Github page.

This got me thinking - When I program in a particular programming language, do I also program in a particular accent? Of course I do.

There are a thousand little things we all do when programming that individually have their own names (Naming Conventions, Indentation Style, Equality Checks, etc), but when you think of them as one combined unit, they construct your individual accent.

Naming Convention

There are so many different possible naming conventions that it's nearly impossible to guarantee that a large development team will all use the same ones in the same situations:

var userName = "Mike"; // Camelcase
var UserName = "Mike" // Upper Camelcase
var strName = "Mike"; // Hungarian Notation
var user_name = "Mike"; // "Ruby" Notation
// And many, many more.

Which conventions do you use in what situations?  Do you name Modules different than Classes?  Classes different than Methods?  Methods different than variables?

Indentation Style

// Do you like to keep your braces on their own line?
function totallyBananas()
{
    alert("Bananas!");
}

// Or with method/class definitions?
function totallyBananas(){
    alert("Bananas");
}

Do your conventions differ for method definitions, class definitions, if/else statements, or other code blocks?  Do you prefer 2, 4, 6, or 8 space indents for different pieces of code?

Equality Checks

// Do you like to check that things are equal?

if(authorized == true){
    alert("Hello, Mike.");
}

// Or inequality?
if(authorized != false){
    alert("Hello, Mike.");
}

Value-First Comparison

We most often see the variable name come first when doing a comparison, but this can lead to some embarrassing mistakes...

var name = "Mike";
// We've all seen this before.
if(name == "Dave"){
    alert(name); // You should never see this!
}

// But this isn't what we meant!
if(name = "Mike"){
    alert(name); // You're going to see "Mike"!
}

Some people have taken to doing "value first" comparisons, which can avoid these mistakes.  Which way do you speak?

if("Mike" == name){
     alert(name); // You should never see this!
}

// This will throw an error.
if("Mike" = name){
    alert(name);
}

There are hundreds of other little things that make up your "programming voice".  Your documentation style, namespacing habits, source file naming conventions, and even your SCM commit messages are all little pieces of what your code sounds like.  So, is your code from the royal palace, or the Louisiana swamps?  Regardless of what your code sounds like, just make sure that your coworkers and colleagues can understand your accent.

A Brief Introduction

So what's the big guffaw all about?  Wikipedia uses Fragment Identifiers to jump around the page, don't they?  Well yeah, but that's just static content.  The big dilemma is over the loading of remote content when a new fragment identifier is loaded.  It's a nice way to load remote content, while still allowing the user to use the "Back" button properly.  Why would anyone want to do this, you might ask?  Well, let me tell you.

Some Numbers

When loading any website, there's two things you pull from the server.  The Markup (HTML), which structures the page, and your helpers (CSS and JavaScript) to pretty the beast up, and make him shine.  I took a look at 4 sites that are kind of a big deal, to see what was being loaded every time I hit their homepage:

Reddit.com
  HTML.: 37.6 KB
  CSS..: 20.2 KB
  JS...: 47.7 KB
  Total: 105.5 KB, 35.6% Content

Google.com
  HTML.: 12.2 KB
  CSS..: 0 KB (Included in HTML)
  JS...: 73.1 KB
  Total: 85.3 KB, 14.3% Content

Youtube
  HTML.: 20.9 KB
  CSS..: 1.3 KB
  JS...: 17.1 KB
  Total: 39.3 KB, 53.2% Content

Github.com
  HTML.: 7.3 KB
  CSS..: 61.5 KB
  JS...: 127.9 KB
  Total: 196.2 KB, 3.7% Content

It looks like nearly every site is loading a lot of stuff other than content, especially Github.  Every time a request hits the server, it has to handle this additional content if it's not cached.  If that's the case taking away the constant loading of the JavaScript and CSS can significantly decrease bandwidth and server load.  In addition to  not needing to fetch the external resources, you also cut down on the amount of HTML required to be loaded with every request, as the DOM structure is only loaded once, and only the content needs to be loaded with every request. In the case of Reddit.com, the majority of HTML loaded is DOM structure and static content, with only 5.9 KB of the 37.6 KB being real, interesting content.  The example below is a rudimentary way to accomplish this, with very little overhead in cost, time, or complexity.

Server Side

There are three things you need to do to make this work, and that's it.  First, make all internal links begin with the root of your site, sans the domain name.  We want things that "/look/like/this".  Next, modify all of your content and views to host the majority of your markup in a Layout of some sort.  Basically, your controller action should only return a block of content that will be placed into the body tag of the layout.  Finally, modify your controller actions to return the content sans layout when AJAX comes calling.  In rails, it would be as simple as:

class WidgetController < ApplicationController
  def index
    @widgets = Widget.all
    respond_to do |wants|
      wants.html {}
      wants.js {render :layout => false}
    end
  end
end

That's it.  Now, when AJAX hits any of your existing controller actions, they'll return the content without the layout.

Client Side

There are two things to do here.  First, you're going to intercept the click of every "a" tag on your site.  This is easy with jQuery:

$("a").live("click", function(event){
    var href = $(this).attr("href");
    if(href[0] == "/"){
        event.preventDefault();
        window.location.hash = "#!" + href;
    }
});

The code block above checks to see if the link goes to a local resource, and if so, intercepts it, stops the link from acting, and changes the Resource Identifier instead.  Now, using a library like PathJS, listen for route changes and act accordingly.  With pathJS, it's as simple as:

Path.default(function(){
    $.get(window.location.hash.replace("#!", ""), function(data){
        $("#contents").html(data);
    });
});

Path.listen();

Now, whenever a local resource link is clicked, it will be picked up and routed to the default function.  This function does an AJAX call to get new content, which is returned without the layout thanks to our controller action changes, and injects it into the DOM.  Fast and easy.  If a user hits your site with JavaScript disabled, the links will never be intercepted, and will go to your regular routes, returned with the layout intact.

But what about...

There are a few things people complain about when confronted with as simple a solution as this:

It doesn't make use of the HTML5 History API!

The example above does not, but the onus is on you as the application developer to build in support for that.  As time progresses, libraries like PathJS will be updated  to integrate with new technologies, but the HTML5 spec is ever changing, and the majority of browser market share doesn't support a lot of these new technologies.

If I have JavaScript enabled, and send my friend (who has JavaScript disabled) a "Hashbang" URI, he won't load the content!

You're right.  This is the primary drawback of an approach like this, and you'll need to figure out if that's acceptable for you.  Are you building a website, or a web application?  Will users ever share links?  What if you're developing an Admin Panel for an internal company tool, an authentication-locked wiki system, or any application that relies on JavaScript to function (image editing, data plotting, etc)?  In those cases, users won't be sharing links, and it's a moot point.  On the other end of the spectrum, you could be building a website, not an application, where users can often share links.  Well, what is your target audience?  Are they likely to have JavaScript disabled?  Is the edge-case of a broken shared link worth the benefits an approach like this provides?  These are all questions that you and your development team need to answer before making a decision.

Won't browser caching reduce server load already?

Yes and no.  In a perfect world, that would be the case.  However, there are a lot of things that can cause the server to send the additional contents on every request, such as  improperly set Headers, browsers with caching turned off/unsupported, clients that don't respect server headers, or any of a multitude of other possible scenarios.  In cases like these, a solution like "Hashbang URIs" makes sense.

Edit: In addition to the cases above, which are unlikely in the best of scenarios (as was pointed out to me by friends and strangers alike), some browsers have a very low cache limit, namely the mobile browser market.

Conclusion

No, it's not perfect.  No, it's not a solution for everyone. Yes, it has drawbacks and downsides.  So what?  It's pushing the boundaries of the browser, and treating the web as an Application Platform, rather than a dumb terminal for reading content and data entry.  The "Hashbang URI" makes your application feel like an application, instead of a website.  The drawbacks are things that need to be weighed against the benefits in your unique case, and the decision will be different for everyone.

Just because it doesn't make sense for you to use it, doesn't mean it's a stupid idea.  You are not the center of the Universe.

PathJS lets you route URL hashes to functions in javascript.  These functions can (and likely will) perform AJAX request to populate your shiny Web Application with data and DOM Structures galore.  You can find the code, tests, and eventually examples on the github page.

Now, a brief example:

$(document).ready(function(){
    Path.map("#/home").to(function(){
        document.write("Welcome Home");
    });

    Path.map("#/contact").to(function(){
        document.write("Contact Us");
    });

    Path.map("#/download").to(function(){
        document.write("Downloads coming soon");
    });

    Path.root("#/home");
    Path.listen();
});