Documentation

Plugins

Since version 0.3.0 Sammy has had the ability to bundle resuable application code and helpers and use them on a per-application basis. Plugins keep the Sammy core code base small, while allowing the inclusion of desired features and extensions.

Basics

A Sammy plugin is really just a Sammy app definition that isn’t evaluated until needed. Since a Sammy app definition is really just a function() we can pass this definition around wherever we want.


      var MyPlugin = function(app) {
        
        this.helpers({
          alert: function(message) {
            this.log("ALERT! " + message);
          }
        });
        
      };
      

This is the simplest type of plugin. It defines a helper method alert() which, once included, can be used within routes and event bindings. Including this code into a Sammy app is as easy as creating it:


      var app = $.sammy(function() {
        this.use(MyPlugin);
        
        this.get('#/', function() {
          this.alert("I'm home"); //=> logs: ALERT! I'm home
        });
        
      });
      

The key method for plugins is use(). use takes the plugin function you defined and evaluates it within the context of the current application. In this case it calls helpers() and defines our alert() method.

Plugins are not limited to helpers. You can define routes, event bindings, even replace/extend core methods.

There’s one extra nicety to use. You can pass extra arguments when using a plugin that get passed to the plugin function.


      var MyAdvancedPlugin = function(app, prefix, suffix) {
        
        this.helpers({
          alert: function(message) {
            this.log(prefix, message, suffix);
          }
        });
        
      };
      
      var app = $.sammy(function() {
        this.use(MyAdvancedPlugin, 'BEFORE!', 'AFTER!');
        
        this.get('#/', function() {
          this.alert("I'm home"); //=> logs: BEFORE! I'm home AFTER!
        });
        
      });
      

Here we defined a slightly more advanced plugin. Notice that the plugin function takes two extra arguments, prefix and suffix. These two are evaluated with the function scope and allow us to change the behavior of the code we’re including. At include time, we pass a ‘BEFORE!’, ‘AFTER!’ to configure the plugin.

Code Re-use

One of the best use-cases for Sammy plugins is refactoring common code out of multiple applications.


      var app1 = Sammy('#div1', function() {
        
        this.get('#/', function() {
          this.record = this.app.db['#div_1'];
          this.app.swap(this.record.toHTML());
        });
        
        // ... app specific code ...
        
        this.bind('run', function() {
          this.db = loadDB();
        });
      });
      
      var app2 = Sammy('#div_2', function() {
        
        this.get('#/', function() {
          this.record = this.app.db['#div_2'];
          this.app.swap(this.record.toHTML());
        });
        
        // ... app specific code ...
        
        this.bind('run', function() {
          this.db = loadDB();
        });
      });
      

Obviously, this is a pretty extreme example, but it lends itself well to refactoring. Let’s factor the common code out into a plugin.


      var dbLoadAndDisplay = function(app) {
        
        this.get('#/', function() {
          this.record = this.app.db[this.app.element_selector];
          this.app.swap(this.record.toHTML());
        });
      
        this.bind('run', function() {
          this.db = loadDB();
        });
      };
      
      var app1 = Sammy('#div_1', function() {
        this.use(dbLoadAndDisplay);
      
        // ... app specific code ...
      
      });
      
      var app2 = Sammy('#div_2', function() {
        this.use(dbLoadAndDisplay);
      
        // ... app specific code ...
      
      });
      

Public Plugin Repository

On top of refactoring your own code, Sammy includes a growing number of plugins that handle common extensions like caching and client-side templating. These live in the lib/plugins directory of the repository.

If you have a plugin that you’d like to be included in the public repository here are some guidelines:

When in doubt ask in irc or on the mailing list.