Introduction

What

Sammy.js is a tiny JavaScript framework developed to ease the pain and provide a basic structure for developing JavaScript applications.

Sammy tries to achieve this by providing a small ‘core’ framework and an ever-growing list of plugins for specific functionality. The core includes a simple API for defining applications which are made up primarily of routes and events. By driving application development around a small and specific API, Sammy attempts to keep your code organized while still allowing a lot of breathing room to define your own style and structure.

Sammy is not a solution for every JavaScript application or problematic situation. It is a single and rather opinionated method for building applications that tries to lend itself to best practices and maintainable development. It does this without the overhead of a large base framework or a single method or system for building models or views. If you want something more fully featured I highly suggest checking out SproutCore or Cappuccino.

Why

In the modern age of super-fast browsers and user expectations about the responsiveness and perceived speed of web applications – single page AJAX applications have become the rage (GMail, etc.) Furthermore, instead of just fetching full HTML and rendering it asynchronously, fetching raw data (JSON) and rendering on the client side has not only become possible – it’s actually very common.

Sammy.js was originally built as an experiment in designing APIs in JavaScript and was heavily inspired by Sinatra.rb. As Sammy evolved it aimed to solve the common problems associated with writing this new style of application. It became clear early on that Sammy was well suited for building simple applications on top of RESTful JSON data stores (See CouchDB).

Sammy continues to be fueled by the community and real-world production applications. It’s small enough that it can stay out of your way, and soon it will integrate with the DOM/AJAX Framework of your choice.

How

Installation

Download Sammy.js and install it in your public javascripts directory.
Include it in your document AFTER jQuery. For more detailed instructions, check out the first tutorial

Basic Usage

A Sammy application is built around Routes. Routes define a link between a named state (usually in the hash or the url) and the action taken at that state (as a callback/function). Routes are defined using the common HTTP verbs within a Sammy.Application container.


      // define a new Sammy.Application bound to the #main element selector
      Sammy('#main', function() {
        
        // define a 'get' route that will be triggered at '#/path'
        this.get('#/path', function() {
          // this context is a Sammy.EventContext
          this.$element() // $('#main')
              .html('A new route!');
        });
      }).run();
      

The only thing we have to ensure once an application is defined is that that app runs after the DOM is fully loaded. You can do this by putting your JS at the end of your body (recommended) or by wrapping run in a document ready event handler.


      var app = Sammy(...);
        
      jQuery(function() {
        app.run();
      });
      

More!

Learn!

Keep informed!