A question came up on the mailing list recently about overriding previously defined routes after struggling thinking of how to do this with the current codebase, the answer was simple: Use helpers!

Coming from Sinatra or Rails the idea of helpers might be associated with just “view helpers” – methods added to the controller which are passed down to the view to help refactor/encapsulate common view logic. In Sammy.js helpers are really a way of refactoring common logic out of routes and into a reusable named method.

Refactorin’

In any app you’ll have startup code or code that needs to be run for every or multiple pages (routes). In Sammy this might looks like:

$.sammy(function() {

  

  this.get('#/', function() {

    if (this.params.grid) {

      this.$element().addClass('grid');

    } else {

      this.$element().removeClass('grid');

    }

    this.partial('index.html');

  });

  

  this.get('#/user', function() {

    if (this.params.grid) {

      this.$element().addClass('grid');

    } else {

      this.$element().removeClass('grid');

    }

    this.partial('user.html');

  });

  

})

A contrived example, but you can tell we’re doing almost the exactly same thing in each of the routes. A common JS convention and something you could do pretty easily here, would just be to extract the functionality out into a closure/function and call it for each route.

$.sammy(function() {

  

  var displayGrid = function($element, display) {

    if (display) {

      $element.addClass('grid');

    } else {

      $element.removeClass('grid');

    }

  };

  

  this.get('#/', function() {

    displayGrid(this.$element(), this.params.grid);

    this.partial('index.html');

  });

  

  this.get('#/user', function() {

    displayGrid(this.$element(), this.params.grid);

    this.partial('user.html');

  });

  

})

This works, it prevents global leakage by declaring it inside the app, and it gets rid of a number of lines of repetitive code. However, we’re still passing a bunch of route attributes into the closure. This is where helpers can shine.

$.sammy(function() {

  

  this.helpers({

    displayGrid: function() {

      if (this.params.grid) {

        this.$element().addClass('grid');

      } else {

        this.$element().removeClass('grid');

      }

  });

  

  this.get('#/', function() {

    this.displayGrid();

    this.partial('index.html');

  });

  

  this.get('#/user', function() {

    this.displayGrid();

    this.partial('user.html');

  });

  

});

This looks a lot cleaner to me. You might not love this but it makes some things really magical. By making displayGrid a helper it automagically has access to the context of the current route. That means that just like the route’s callback, it has access to everything in the EventContext including params, redirect, render and other helpers. This is important, because it basically allows you to extract common code from routes into helpers and then refactor those helpers even further into other helpers.

stOOPid inheritance and mixins

Helpers are actually just methods on the app’s EventContext prototype, and event though there’s no classical inheritance with super’s and all that jazz we can do some fun OOP-like magic.

In the example from the mailing list, we wanted to override an application’s existing route with a new route. Though the way routes are stored and handled makes it difficult on the app level, doing it on the helper level is EZ:

// initializing a new app

var app = $.sammy(function() {

  

  this.helpers({

    // define a helper to load the index as the default behavior

    loadIndex: function() {

      this.partial('index.html');

    }

  });

  

  this.get('#/', function() {

    this.loadIndex();

  });

});



// override the specific helper, and hence the index route

// we can also do this by calling `helpers()`

app.helper('loadIndex', function() {

  this.partial('specialindex.html');

});

use() is how Sammy includes a plugin in an app. A plugin is really just another app function, though, that get’s evaluated at the time you use() it. In fact, when you call $.sammy() you’re just creating a new instance of Sammy.Application and then calling use() on it with the app function. This is a simple way of doing “mixin” style inheritance. A plugin can do anything an app can, including and especially helpers. So with multiple apps we be all like tag team: OOP there it is

$.sammy('#hiphop', function() {

  this.helpers({

    playCatchPhrase: $.noop

    // noop there it is 

    // this is sort of like an abstract method

  });

  

  this.get('#/catchphrase', function() {

    this.playCatchPhrase();

  })

});



var atlanta = function() {

  this.helper('playCatchPhrase', function() {

    alert('whoomp there it is!');

  });

};



var la = function() {

  this.helper('playCatchPhrase', function() {

    alert('do the hump!');

  });

};



$.sammy('#hiphop').use(la);

// get '#/catchphrase' //=> 'do the hump!'

Thats still pretty simple, though combining these ideas is actually pretty powerful. Almost all of Sammy’s existing plugins are based on this simple approach. I’m hoping soon, it can get even more abstract and complex. Why not a Sammy.Auth that handles displaying/posting/and doing all the basic authentication? You could use helpers for most of the dirty work and then one could just override the defaults in their specific apps. You could even create another set of plugins that were different displays or authentication systems that override the simple base methods. Do it! ( so I dont have to )

I’m pleased to announce the next major release of Sammy.js, 0.5.0. I’ll go over what I think are the most import changes, but you can check out the HISTORY or just cut to the chase and download it.

jQuery 1.4.1

One of the big events I was waiting for in order to release this new version was the release of jQuery 1.4.1. Besides being a good leap and jump faster then previous versions, the latest jQuery added support for cross-browser bubbling of the submit event. This might not sound like a big deal, but Sammy handles post/put/delete routes by binding to forms and their submit events. In previous versions of Sammy, if a form was dynamically added to the page (i.e. by a partial or get route), you (or the app) would fire a changed event, which would tell the app to search for all newly added forms and bind to their submit events. Using the power of jQuery 1.4.1, Sammy can now just listen for submit events that will bubble up to the applications element and from their dispatch the route. In general this is a lot cleaner and will make it easier for beginners as it just works.

Chain of fools

From user requests, and to fulfill my own desires, I’ve tried make Sammy more adaptable to different styles of coding/app creation. The first thing I realized why not make Sammy app definitions chain-able? It’s a style of development that jQuery developers are already used to, and it looks pretty swanky, too. With 0.5, all the app modifying methods are now chain-able:

  



// classic style:

$.sammy(function() {

  this.use(Sammy.Mustache);

  this.use(Sammy.Session);

  

  this.before(function() {

    // …

  });

  

  this.get('#/', function() {

    // …

  });

  

  this.bind('run', function() {

    // …

  });

  

})



// New chain style:

$.sammy()

  .use(Sammy.Mustache)

  .use(Sammy.Session)

  .before(function() { 

    // .

  })

  .get('#/', function() {

    // …

  })

  .bind('run', function() {

    // …

  });

    

Sammy()

Once just a namespace, Sammy() is now a function (and its aliased to $.sammy). The Sammy() method provides access to the new Sammy.apps object and hence allows you to access the different Sammy applications you’ve added to the page without having to define additional global vars. Finding and extending is all based on @element_selector@s so those should be unique per-application. It also provides a quicker syntax for defining an app bound to an element_selector.

// Old way

// we're forced to make app a global so we can access it 

// outside of this closure

app = $.sammy(function() {

  this.element_selector = '#myapp';

  //…

})

// equivalent to

app = new Sammy.Application(function() {

  this.element_selector = '#myapp';

  //…

});



// NEW WAY

$.sammy('#myapp', function() {

  //…

});

// equivalent to Sammy('#myapp', function() {})



// No need to assign it, the app can be looked up by element selector

$.sammy('#myapp') //=> Sammy.Application

There are some cool use-cases for this, including being able to iterate over all the Sammy apps in play and extend them.

any way you want it

Sammy 0.5 adds the new any pseudo-verb which allows you to easily add a route that will match against any verb:

  

$.sammy(function() {

  

  this.any('#/', function() {

    this.log("I'm up for anything");

  });

  

  // also equivalent

  this.route('#/', function() {});

  

});

This was actually the first step of another way to define Sammy applications. The new mapRoutes() method allows you to define any number of routes as 2D Array.

$.sammy(function() {

  

  this.runIndex = function() {

    this.partial('index.template');

  };

  

  this.mapRoutes([

    // each element in the array represents the arguments sent to route()

    ['get', '#/user', function() {

      this.partial('user.template');

    }],

    // leaving out the verb assumes the verb is 'any'

    [/\/alert$/, function() {

      alert(this.params['alert']);

    }],

    // passing a string instead of a callback assigns the method with that

    // name from the application.

    ['get', '#/', 'runIndex']

  ]);

  

});

I personally like the method syntax better, but there are some cool uses for this – You could even load your routes from multiple files and add them to the application using JSON.

Filters

before filters are very useful for extracting common functionality out of your routes. However, I’ve found myself writing this pretty often:

$.sammy(function() {

  

  this.before(function() {

    // only run if the path is not the index

    if (this.path != '#/') {

      //… do something

    }

  })

  

});

Taking some hints from Rails, I’ve added options to before filters. The above example could be rewritten:

$.sammy(function() {

  

  this.before({except: '#/'}, function() {

    //… do something

  })

  

});

The filters can match against path (as a string or RegExp) and verb and you can define them in the positive (only) or negative (except). The method that does the matching is exposed as contextMatchesOptions so you can use it outside of before()

I’ve also found myself doing a lot of wrapping entire route callbacks in an asynchronous check for something (usually a login). The new around filters make this easy. around takes a single argument which is a neatly packed function that contains the full execution path of the route being accessed. This includes additional filters and the route callback itself. This also means you can entirely halt the execution by never running the passed callback.

$.sammy(function() {

  

  this.around(function(callback) {

    // `this` here is the Sammy.EventContext

    // just like before, etc

    $.get('/session', function() {

      callback();

    });

  });



})

Lots more

Theres actually a fair amount more to cover in Sammy 0.5, but I think I’ll be doing more short ‘Whats new’ posts soon. Check the HISTORY for a full rundown of changes.

Thanks

Special thanks goes out to everyone who helped with ideas, commits and testing for this release including Lena Herrmann, Jinzhu, dpree, Jeff O’Connell, Todd Willey, Tim Caswell, and Frank Prößdorf (endor).

Quick note, I decided to use github pages instead of this here blog to post the tutorials. In the end, its just easier to post lots of inline code AND it will be easier to maintain with updates as the Sammy API changes.

I hope you enjoy it! I’m always appreciative of feedback and constructive criticism, so fire away.

I’m very happy to announce the next major release of Sammy.js. I’ve been working on this for over a month and the result has been a lot more changes then I expected but over all a smaller, cleaner core code base. Here’s a quick run through of the biggest changes. See HISTORY or the Commits for a full list and more detail.

Plugins

The biggest change, that resulted in a lot of little changes is Sammy.Application#use() which allows you to package and resuse application level code into ‘Plugins’. See the documentation on plugins for more detail. This also marks the start of an official selection of plugins, with two as part of this release and more on the way.

The default template system that used $.srender internally has been extracted out into a plugin. To enable almost the exact same functionality:

// somewhere in your HTML (after sammy.js): 
// <script src="plugins/sammy.template.js" type="text/javascript"></script>
$.sammy(function() {
  // include the Sammy.Template plugin
  this.use(Sammy.Template);
  
});

Events

Sammy.Application’s bind() and trigger() methods now use jQuery’s namespacing to bind to Events. This means that Sammy.Application can now easily catch events that bubble to it like ‘click’ or ‘focus’. The big awesomeness is that the callbacks for these bind() methods are always evaluated within a Sammy.EventContext so that even events triggered from outside the app can be handled in the same way as internal events.

var app = $.sammy(function() {

    this.bind('custom-event', function() {
      // this == Sammy.EventContext
      alert('Custom Event' + this.params['wha']);
    });

  });

  // the app is by default bound to 'body'
  $('body').trigger('custom-event', {wha: 'ZUH?!'});
  //=> system alert ZUH?!
  

Cleanup

With the advent of plugins, Sammy Core is now even smaller (8.9k minified). This is also possible because I’ve removed the former ‘classical’ inheritence code in favor of prototypal inheritence, which is a big win in terms of cleanlieness and global scope leakage.

See Also

I mentioned this on twitter, but I’m working on some new tutorials and screencasts about Sammy. If you have ideas/suggestions, dont hesitate to let me know. The first one should be up next week. I’m going to try to do them bi-weekly, we’ll see how that goes

Again, I’ve tried to be as thorough with inline API docs as I could so any changes should be in the clear. Thanks again to everyone who helped with this release and has supported Sammy recently!

I’ll be honest. When I created Sammy.js, It was more of an academic exercise then a means to an end. I had ideas for how it could be useful, and had some immediate uses for it, but the initial thought was ‘recreating Sinatra’s API in JavaScript’. Little did I know – with a little introduction and the work of some clever individuals, its real value would be revealed.

We’re at the dawn of a new age on the web, or maybe or horizon, or a precipice; the metaphor doesn’t matter, the point is, things are changing. Specifically, as browsers become more and more powerful, as developers we’re given new opportunities to rethink how we architect web applications. Whether or not some of the predictions of ‘the death of the traditional desktop’ are correct – whether or not the near future desktop is just the browser – we now have the power, without proprietary technologies (flash, etc) to create truly desktop like experiences on the web. Thats nothing mind-blowing, we’ve seen it coming for a little while now.

Ok, then: let me blow your mind.

Because of the great power that modern browsers provide us as Javascript developers a new paradigm of web development is arising. Lets take a look at the current/traditional model:

Here we have a traditional stack. The ‘power’ of the application lies on the server: our development platform of choice (Rails, PHP, etc) sits on top of our database of choice (probably relational, probably SQL). This server platform renders finished HTML and maybe decorates those pages with the use of our JS library and our application specific code (Your $(hit)). In this model we’re using probably at least 3 different programming languages and almost fully on the speed and reliability of our servers for getting data to the user. There’s probably also at least 3 steps in either direction between data and the user:

• User clicks a link on a page or follows a URL
• The request is sent to the server
• App receives request passes it on to Model/ORM layer
• ORM requests the data from the Database
• Database returns the data to the ORM
• ORM returns the data in a parse-able form to the App
• App converts it into user-readable format and displays it to user

Obviously, Rails and most other languages frameworks abstract a lot of this away, so we don’t really have to think in all these steps. They’re there, though.

Welcome to the new world. HTTP Databases and JSON Storage. The simple act of making the database and the browser more powerful on either end has destroyed the need for the middle tier. In the new architecture, Our database (JSON/HTTP based: CouchDB, Cloudkit) serves data as JSON directly to the browser. On the browser side we create a much smaller/tighter ‘controller’ layer with JavaScript. This handles the directing of the user to the right place, the displaying of the data to the user, and the conversion of user interaction into state + data. This middle piece is jQuery + Sammy.js.

In my presentation at jQuery Conf this past weekend (slides available here) I demonstrated this concept in a rather meta-tastic way. The presentation tool I used was called Swinger and it was written using CouchDB, CouchApp, and Sammy.js. The application logic was contained in a single JS file that used a Sammy application to do all the routing, getting data in and out of CouchDB and displaying it in a particularly pretty way. The coolest part about this whole thing is that even beyond taking out the middle layer, this implementation removes the traditional static file serving model, too. With the power of CouchApp and _attachments, the javascript and HTML files needed to serve the application are served directly out of the database. Its like CouchDB and Sammy.js were made for each other. Think about the new steps for this architecture:

• User clicks a link on the page or follows a URL
• Data is requested via AJAX from the server
• The server proxies to the database or processes the request directly
• The data is returned to Sammy.js as JSON
• Sammy.js uses the data it needs and displays it to the user

There are a number really amazing and exciting things to note here. First, notice how the application is written in JavaScript AND the data is JavaScript. The JSON store might actually be written in another language (CouchDB is Erlang, Cloudkit is Ruby) but we don’t really ever have to touch those. Personally, I really like JavaScript. Sure, I miss some of Ruby’s syntax and niceties, but I’ll give that up pretty quickly for something that still shares some of the similar good features (closures, loose typing) and has a ubiquitous deployment environment (the browser). Second, the end result is probably similar if not better to the end user, as we eliminate the need to reload the page at every request, resulting in a better perceived speed.

One of the provisions I gave for my talk is that “I’m less concerned with speed than awesomeness”. That rings pretty true here. I don’t have an architecture like this running in production and getting hit like twitter. I can’t really speak yet to how well it ‘scales’ or how it preforms under load. I CAN tell you about how awesome it is and how easy and fun it was to develop swinger with Sammy. That’s really all I need to know right now.

I think my talk was pretty successful and besides not getting through all my slides, it seems like I got a lot of people excited about CouchDB and Sammy.js. I’m going to write a pretty in-depth recap of the talk and post it soon.

Also, It sounds like there will be a lot more jQuery and JavaScript conferences in the near future. I can’t wait.

My favorite feature from this update might be the simplest.

Rendering partials now uses a special swap() method on Sammy.Application. By default it just uses jQuery's html() method to swap out the old content of $element with the new content. The power though, is you easily override this to provide a cool transition when a new partial is rendered.

var app = $.sammy(function() {
  
  this.swap = function(content) {
    var width = $(window).width();
    this.$element()
      .wrapInner('<div class="inner"></div>')
      .children('.inner')
        .animate({queue: false, left: "-" + width}, 400)
        .remove()
        .end()
      .html(content)
      .css({left: width})
      .animate({left: '0px', width: width}, 400);
  };
  
  this.get('#/user/:name', function() {
    this.partial('name.erb', {name: this.params['name']});
  });
  
  //...
});

Now, when you go to '#/user/aq' or similar, it will use the swap method to do a nifty transition, instead of ye old html().

Theres more examples and Sammy on the way. Come join the mailing list or hang out in irc to learn or contribute.

The pull was obvious, a lot of the smartest people in the Ruby community love jQuery. I couldn’t really get it, though. Chaining is cool, but its really just a parlor trick. What hooked me was the community. Just like Ruby (and unlike Prototype for the most part) jQuery has a thriving community of bloggers, plugin authors, and mailing lists. Part of jQuery is that is inherently extensible. Sure, prototype.js has Object.addMethods() but jQuery allows for easy packaging and distribution of new functionality. I’m sure I’m not the first one to say this, but its very true.

The one thing that kind of hung me up at first was how to organize my code. In Prototype, I used Class.create() a lot to encapsulate functionality for elements and areas of the site. Even using Class.create() with name-spacing like:

var MyApp = {}

MyApp.Feature = Class.Create({
  ...
})

I was kind of lost how to do this easily and effectively with jQuery. Do I create plugins for all of this functionality? I could, but that seemed messy to add to the global jQuery name-space when really what I wanted was an Object. John Resig to the rescue. 25 lines of code and now I have my Classes beautifully encapsulated. An interesting design pattern I happened upon with this, is using Class.extend() and jquery’s $.fn.data() to associate groups an instance of a Class with an element on-screen.

For example:

var Block = Class.extend({
  
  init: function(element) {
    this.$element = $(element);  
  }
  // ... 
  // methods that can operate on an instance of block
  // and its elements.
})

$('.block').each(function() { $(this).data('block', new Block(this)) });

This is instead of:

$.fn.extend({
  block: function() {
    // a bunch of anonymous or private methods
  }
})

$('.block').block();

The benefit of the Class way, is that now you always can just fetch and operate on the instance of Block for a particular element.

$('.block:first').data('block').someBlockMethod();

I need to dive a little deeper to see if there's a way to easily plugin-ize this pattern as I seem to be using it a bunch.

There are still a few small things I miss from Prototype, but for the most part either someone has ported them, or it pretty easy to do it yourself. For example, Function#bind():

// works like Prototype's Function#bind
// in Prototype:
//     $('element').observe('click', this.clickMethod.bind(this));
// with jQuery + $.shove:
//     $('#element).click($.shove(this.clickMethod, this));
 
$.extend({
  shove: function(fn, object) {
    return function() {
      return fn.apply(object, arguments);
    }
  }
});

Here are some great resources that I’ve found have made the whole switch lovely:

• Learning jQuery
• The jQuery Documentation
• A desktop version of the jQuery docs
• Reading Mike Alsup’s code