returns a jQuery object of the Applications bound element.

A shortcut for binding a callback to be run after a route is executed. After callbacks have no guarunteed order.

Adds an around filter to the application. around filters are functions that take a single argument callback which is the entire route execution path wrapped up in a closure. This means you can decide whether or not to proceed with execution by not invoking callback or, more usefuly wrapping callback inside the result of an asynchronous execution.

Example

The most common use case for around() is calling a possibly async function and executing the route within the functions callback:

        var app = $.sammy(function() {

          var current_user = false;

          function checkLoggedIn(callback) {
            // /session returns a JSON representation of the logged in user
            // or an empty object
            if (!current_user) {
              $.getJSON('/session', function(json) {
                if (json.login) {
                  // show the user as logged in
                  current_user = json;
                  // execute the route path
                  callback();
                } else {
                  // show the user as not logged in
                  current_user = false;
                  // the context of aroundFilters is an EventContext
                  this.redirect('#/login');
                }
              });
            } else {
              // execute the route path
              callback();
            }
          };

          this.around(checkLoggedIn);

        });
      

Takes a single callback that is pushed on to a stack. Before any route is run, the callbacks are evaluated in order within the current Sammy.EventContext

If any of the callbacks explicitly return false, execution of any further callbacks and the route itself is halted.

You can also provide a set of options that will define when to run this before based on the route it proceeds.

Example

        var app = $.sammy(function() {

          // will run at #/route but not at #/
          this.before('#/route', function() {
            //...
          });

          // will run at #/ but not at #/route
          this.before({except: {path: '#/route'}}, function() {
            this.log('not before #/route');
          });

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

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

        });
      

See contextMatchesOptions() for a full list of supported options

Works just like jQuery.fn.bind() with a couple noteable differences.

• It binds all events to the application element
• All events are bound within the eventNamespace()
• Events are not actually bound until the application is started with run()
• callbacks are evaluated within the context of a Sammy.EventContext

See http://code.quirkey.com/sammy/docs/events.html for more info.

Will bind a single callback function to every event that is already being listened to in the app. This includes all the APP_EVENTS as well as any custom events defined with bind().

Used internally for debug logging.

clear the templateCache

Matches an object of options against an EventContext like object that contains path and verb attributes. Internally Sammy uses this for matching before() filters against specific options. You can set the object to only match certain paths or verbs, or match all paths or verbs except those that match the options.

Example

       var app = $.sammy(),
           context = {verb: 'get', path: '#/mypath'};

       // match against a path string
       app.contextMatchesOptions(context, '#/mypath'); //=> true
       app.contextMatchesOptions(context, '#/otherpath'); //=> false
       // equivilent to
       app.contextMatchesOptions(context, {only: {path:'#/mypath'}}); //=> true
       app.contextMatchesOptions(context, {only: {path:'#/otherpath'}}); //=> false
       // match against a path regexp
       app.contextMatchesOptions(context, /path/); //=> true
       app.contextMatchesOptions(context, /^path/); //=> false
       // match only a verb
       app.contextMatchesOptions(context, {only: {verb:'get'}}); //=> true
       app.contextMatchesOptions(context, {only: {verb:'post'}}); //=> false
       // match all except a verb
       app.contextMatchesOptions(context, {except: {verb:'post'}}); //=> true
       app.contextMatchesOptions(context, {except: {verb:'get'}}); //=> false
       // match all except a path
       app.contextMatchesOptions(context, {except: {path:'#/otherpath'}}); //=> true
       app.contextMatchesOptions(context, {except: {path:'#/mypath'}}); //=> false
      

The base error handler takes a string message and an Error object. If raise_errors is set to true on the app level, this will re-throw the error to the browser. Otherwise it will send the error to log(). Override this method to provide custom error handling e.g logging to a server side component or displaying some feedback to the user.

A unique event namespace defined per application. All events bound with bind() are automatically bound within this space.

Delegates to the location_proxy to get the current location. See Sammy.HashLocationProxy for more info on location proxies.

Helper extends the event context just like helpers() but does it a single method at a time. This is especially useful for dynamically named helpers

Example

       // Trivial example that adds 3 helper methods to the context dynamically
       var app = $.sammy(function(app) {

         $.each([1,2,3], function(i, num) {
           app.helper('helper' + num, function() {
             this.log("I'm helper number " + num);
           });
         });

         this.get('#/', function() {
           this.helper2(); //=> I'm helper number 2
         });
       });
      

Arguments

• name The name of the method
• method The function to be added to the prototype at name

Helpers extends the EventContext prototype specific to this app. This allows you to define app specific helper functions that can be used whenever you're inside of an event context (templates, routes, bind).

Example

      var app = $.sammy(function() {

        helpers({
          upcase: function(text) {
           return text.toString().toUpperCase();
          }
        });

        get('#/', function() { with(this) {
          // inside of this context I can use the helpers
          $('#main').html(upcase($('#main').text());
        }});

      });
      

Arguments

• extensions An object collection of functions to extend the context.

Returns true if the current application is running.

Given a verb and a String path, will return either a route object or false if a matching route can be found within the current defined set.

mapRoutes takes an array of arrays, each array being passed to route() as arguments, this allows for mass definition of routes. Another benefit is this makes it possible/easier to load routes via remote JSON.

Example

      var app = $.sammy(function() {

        this.mapRoutes([
            ['get', '#/', function() { this.log('index'); }],
            // strings in callbacks are looked up as methods on the app
            ['post', '#/create', 'addUser'],
            // No verb assumes 'any' as the verb
            [/dowhatever/, function() { this.log(this.verb, this.path)}];
          ]);
      })
      

This thows a '404 Not Found' error by invoking error(). Override this method or error() to provide custom 404 behavior (i.e redirecting to / or showing a warning)

Reruns the current route

Returns a copy of the given path with any query string after the hash removed.

route() is the main method for defining routes within an application. For great detail on routes, check out: http://code.quirkey.com/sammy/doc/routes.html

This method also has aliases for each of the different verbs (eg. get(), post(), etc.)

Arguments

• verb A String in the set of ROUTE_VERBS or 'any'. 'any' will add routes for each of the ROUTE_VERBS. If only two arguments are passed, the first argument is the path, the second is the callback and the verb is assumed to be 'any'.
• path A Regexp or a String representing the path to match to invoke this verb.
• callback A Function that is called/evaluated whent the route is run see: runRoute(). It is also possible to pass a string as the callback, which is looked up as the name of a method on the application.

Actually starts the application's lifecycle. run() should be invoked within a document.ready block to ensure the DOM exists before binding events, etc.

Example

      var app = $.sammy(function() { ... }); // your application
      $(function() { // document.ready
          app.run();
       });
      

Arguments

• start_url Optionally, a String can be passed which the App will redirect to after the events/routes have been bound.

First, invokes lookupRoute() and if a route is found, parses the possible URL params and then invokes the route's callback within a new Sammy.EventContext. If the route can not be found, it calls notFound(). If raise_errors is set to true and the error() has not been overriden, it will throw an actual JS error.

You probably will never have to call this directly.

Arguments

• verb A String for the verb.
• path A String path to lookup.
• params An Object of Params pulled from the URI or passed directly.

Returns

Either returns the value returned by the route callback or raises a 404 Not Found error.

Delegates to the location_proxy to set the current location. See Sammy.HashLocationProxy for more info on location proxies.

Arguments

• new_location A new location string (e.g. '#/')

Sets the location proxy for the current app. By default this is set to a new Sammy.HashLocationProxy on initialization. However, you can set the location_proxy inside you're app function to give your app a custom location mechanism. See Sammy.HashLocationProxy and Sammy.DataLocationProxy for examples.

setLocationProxy() takes an initialized location proxy.

Example

          // to bind to data instead of the default hash;
          var app = $.sammy(function() {
            this.setLocationProxy(new Sammy.DataLocationProxy(this));
          });
      

Swaps the content of $element() with content You can override this method to provide an alternate swap behavior for EventContext.partial().

Example

      var app = $.sammy(function() {

        // implements a 'fade out'/'fade in'
        this.swap = function(content) {
          this.$element().hide('slow').html(content).show('slow');
        }

        get('#/', function() {
          this.partial('index.html.erb') // will fade out and in
        });

      });
      

a simple global cache for templates. Uses the same semantics as Sammy.Cache and Sammy.Storage so can easily be replaced with a persistant storage that lasts beyond the current request.

//=> Sammy.Application: body

Triggers custom events defined with bind()

Arguments

• name The name of the event. Automatically prefixed with the eventNamespace()
• data An optional Object that can be passed to the bound callback.
• context An optional context/Object in which to execute the bound callback. If no context is supplied a the context is a new Sammy.EventContext

The opposite of run(), un-binds all event listeners and intervals run() Automaticaly binds a onunload event to run this when the document is closed.

use() is the entry point for including Sammy plugins. The first argument to use should be a function() that is evaluated in the context of the current application, just like the app_function argument to the Sammy.Application constructor.

Any additional arguments are passed to the app function sequentially.

For much more detail about plugins, check out: http://code.quirkey.com/sammy/doc/plugins.html

Example

        var MyPlugin = function(app, prepend) {

          this.helpers({
            myhelper: function(text) {
              alert(prepend + " " + text);
            }
          });

        };

        var app = $.sammy(function() {

          this.use(MyPlugin, 'This is my plugin');

          this.get('#/', function() {
            this.myhelper('and dont you forget it!');
            //=> Alerts: This is my plugin and dont you forget it!
          });

        });
      

If plugin is passed as a string it assumes your are trying to load Sammy."Plugin". This is the prefered way of loading core Sammy plugins as it allows for better error-messaging.

Example

        $.sammy(function() {
          this.use('Mustache'); //=> Sammy.Mustache
          this.use('Storage'); //=> Sammy.Storage
        });
      

A shortcut to the app's $element()

Look up a templating engine within the current app and context. engine can be one of the following:

• a function: should conform to function(content, data) { return interploated; }
• a template path: 'template.ejs', looks up the extension to match to the ejs() helper
• a string referering to the helper: "mustache" => mustache()

If no engine is found, use the app's default template_engine

A shortcut to app's eventNamespace()

using the template engine found with engineFor(), interpolate the data into content

Default JSON parsing uses jQuery's parseJSON(). Include Sammy.JSON plugin for the more conformant "crockford special".

create a new Sammy.RenderContext calling load() with location and options. Called without interpolation or placement, this allows for preloading/caching the templates.

Raises a possible notFound() error for the current path.

render() the the location with data and then swap() the app's $element with the rendered content.

Changes the location of the current window. If to begins with '#' it only changes the document's hash. If passed more than 1 argument redirect will join them together with forward slashes.

Example

        redirect('#/other/route');
        // equivilent to
        redirect('#', 'other', 'route');
      

Create and return a Sammy.RenderContext calling render() on it. Loads the template and interpolate the data, however does not actual place it in the DOM.

Example

        // mytemplate.mustache <div class="name"></div>
        render('mytemplate.mustache', {name: 'quirkey'});
        // sets the `content` to <div class="name">quirkey</div>
        render('mytemplate.mustache', {name: 'quirkey'})
          .appendTo('ul');
        // appends the rendered content to $('ul')
      

Create and return a Sammy.RenderContext calling renderEach() on it. Loads the template and interpolates the data for each item, however does not actual place it in the DOM.

Example

        // mytemplate.mustache <div class="name"></div>
        renderEach('mytemplate.mustache', [{name: 'quirkey'}, {name: 'endor'}])
        // sets the `content` to <div class="name">quirkey</div><div class="name">endor</div>
        renderEach('mytemplate.mustache', [{name: 'quirkey'}, {name: 'endor'}]).appendTo('ul');
        // appends the rendered content to $('ul')
      

create a new Sammy.RenderContext calling send() with an arbitrary function

A shortcut to app's swap()

//=> Sammy.EventContext: get #/ {}

Triggers events on app within the current context.

formFor creates a Sammy.Form builder object with the passed name and object and passes it as an argument to the content_callback. This is a shortcut for creating FormBuilder objects for use within templates.

Example

        // in item_form.template

        <% formFor('item', item, function(f) { %>
          <%= f.open({action: '#/items'}) %>
          <p>
            <%= f.label('name') %>
            <%= f.text('name') %>
          </p>
          <p>
            <%= f.submit() %>
          </p>
          <%= f.close() %>
        <% }); %>
      

creates a checkbox input for keypath with the value value. Multiple checkboxes can be created with different value, if value equals the current value of the key of the form builder's object the attribute checked='checked' will be added.

By default checkbox() also generates a hidden element whose value is the inverse of the value given. This is known hack to get around a common gotcha where browsers and jQuery itself does not include 'unchecked' elements in the list of submittable inputs. This ensures that a value should always be passed to Sammy and hence the server. You can disable the creation of the hidden element by setting the hidden_element attribute to false

closes the form

creates a hidden input for keypath with an optional attributes object

creates a label for keypath with the text content with an optionalattributes` object

creates the open form tag with the object attributes

creates a password input for keypath with an optional attributes object

creates a radio input for keypath with the value value. Multiple radios can be created with different value, if value equals the current value of the key of the form builder's object the attribute checked='checked' will be added.

creates a select element for keypath with the option elements specified by an array in options. If options is an array of arrays, the first element in each subarray becomes the text of the option and the second becomes the value.

Example

       var options = [
         ['Small', 's'],
         ['Medium', 'm'],
         ['Large', 'l']
       ];
       form.select('size', options);
       //=> <select name='item[size]'><option value='s'>Small</option> ...
      

creates a submit input for keypath with an optional attributes object

creates a text input for keypath with an optional attributes object

creates a textarea for keypath with an optional attributes object

Disable tracking for the current route. Put at the begining of the route's callback

send a page view to the tracker with path

Escapes output and converts empty values to empty strings

returns a two element array containing the numbers of contexts to back up the stack and the properties to dig into on the current context

for example, if the path is "../../alan/name", the result will be [2, ["alan", "name"]].

bind the proxy events to the current app.

get the current location from the hash.

set the current location to new_location

unbind the proxy events from the current app

json is a polymorphic function that translates objects aback and forth from JSON to JS. If given a string, it will parse into JS, if given a JS object it will stringify into JSON.

Example

        var app = $.sammy(function() {
          this.use(Sammy.JSON);

          this.get('#/', function() {
            this.json({user_id: 123}); //=> "{\"user_id\":\"123\"}"
            this.json("{\"user_id\":\"123\"}"); //=> [object Object]
            this.json("{\"user_id\":\"123\"}").user_id; //=> "123"
          });
        })
      

by @langalex, support for arrays of strings

Checks if the object has a value at key and that the value is not empty

convenience method to join as many arguments as you want by the first argument - useful for making paths

Returns an array of keys for this object. If attributes_only is true will not return keys that map to a function()

Shortcut to Sammy.log

Renders a simple HTML version of this Objects attributes. Does not render functions. For example. Given this Sammy.Object:

      var s = new Sammy.Object({first_name: 'Sammy', last_name: 'Davis Jr.'});
      s.toHTML() //=> '<strong>first_name</strong> Sammy<br /><strong>last_name</strong> Davis Jr.<br />'
      

Returns a copy of the object with Functions removed.

Returns a string representation of this object. if include_functions is true, it will also toString() the methods of this object. By default only prints the attributes.

Same usage as jQuery.fn.appendTo() but uses then() to ensure order

itterates over an array, applying the callback for each item item. the callback takes the same style of arguments as jQuery.each() (index, item). The return value of each callback is collected as a single string and stored as content to be used in the next iteration of the RenderContext.

uses the previous loaded content and the data object to interpolate a template. engine defines the templating/interpolation method/engine that should be used. If engine is not passed, the next_engine is used. If retain is true, the final interpolated data is appended to the previous_content instead of just replacing it.

Load a template into the context. The location can either be a string specifiying the remote path to the file, a jQuery object, or a DOM element.

No interpolation happens by default, the content is stored in content.

In the case of a path, unless the option {cache: false} is passed the data is stored in the app's templateCache().

If a jQuery or DOM object is passed the innerHTML of the node is pulled in. This is useful for nesting templates as part of the initial page load wrapped in invisible elements or <script> tags. With template paths, the template engine is looked up by the extension. For DOM/jQuery embedded templates, this isnt possible, so there are a couple of options:

• pass an {engine:} option.
• define the engine in the data-engine attribute of the passed node.
• just store the raw template data and use interpolate() manually

If a callback is passed it is executed after the template load.

Resume the queue, setting content to be used in the next operation. See wait() for an example.

render() the the location with data and then swap() the app's $element with the rendered content.

Same usage as jQuery.fn.prependTo() but uses then() to ensure order

load() a template and then interpolate() it with data.

Example

        this.get('#/', function() {
          this.render('mytemplate.template', {name: 'test'});
        });
      

loads a template, and then interpolates it for each item in the data array. If a callback is passed, it will call the callback with each item in the array after interpolation

Replaces the $(selector) using html() with the previously loaded content

defers the call of function to occur in order of the render queue. The function can accept any number of arguments as long as the last argument is a callback function. This is useful for putting arbitrary asynchronous functions into the queue. The content passed to the callback is passed as content to the next item in the queue.

=== Example

          this.send($.getJSON, '/app.json')
              .then(function(json) {
                $('#message).text(json['message']);
              });
      

executes EventContext#swap() with the content

The "core" of the RenderContext object, adds the callback to the queue. If the context is waiting (meaning an async operation is happening) then the callback will be executed in order, once the other operations are complete. If there is no currently executing operation, the callback is executed immediately.

The value returned from the callback is stored in content for the subsiquent operation. If you return false, the queue will pause, and the next callback in the queue will not be executed until next() is called. This allows for the guarunteed order of execution while working with async operations.

If then() is passed a string instead of a function, the string is looked up as a helper method on the event context.

Example

        this.get('#/', function() {
          // initialize the RenderContext
          // Even though `load()` executes async, the next `then()`
          // wont execute until the load finishes
          this.load('myfile.txt')
              .then(function(content) {
                // the first argument to then is the content of the
                // prev operation
                $('#main').html(content);
              });
        });
      

trigger the event in the order of the event context. Same semantics as Sammy.EventContext#trigger(). If data is ommitted, content is sent as {content: content}

Pause the RenderContext queue. Combined with next() allows for async operations.

Example

          this.get('#/', function() {
            this.load('mytext.json')
                .then(function(content) {
                  var context = this,
                      data    = JSON.parse(content);
                  // pause execution
                  context.wait();
                  // post to a url
                  $.post(data.url, {}, function(response) {
                    context.next(JSON.parse(response));
                  });
                })
                .then(function(data) {
                  // data is json from the previous post
                  $('#message').text(data.status);
                });
          });
      

Removes the value at key from the current store

Clears all the values for the current store.

Iterates over each key value pair passing them to the callback function

Example

        store.each(function(key, value) {
          Sammy.log('key', key, 'value', value);
        });
      

Checks for the existance of key in the current store. Returns a boolean.

Returns the value at key if set, otherwise, runs the callback and sets the value to the value returned in the callback.

Example

      var store = new Sammy.Store;
      store.exists('foo'); //=> false
      store.fetch('foo', function() {
        return 'bar!';
      }); //=> 'bar!'
      store.get('foo') //=> 'bar!'
      store.fetch('foo', function() {
        return 'baz!';
      }); //=> 'bar!
      

Filters the store by a filter function that takes a key value. Returns an array of arrays where the first element of each array is the key and the second is the value of that key.

Example

        var store = new Sammy.Store;
        store.set('one', 'two');
        store.set('two', 'three');
        store.set('1', 'two');
        var returned = store.filter(function(key, value) {
          // only return
          return value === 'two';
        });
        // returned => [['one', 'two'], ['1', 'two']];
      

Works exactly like filter except only returns the first matching key value pair instead of all of them

Returns the set value at key, parsing with JSON.parse and turning into an object if possible

Checks for the availability of the current storage type in the current browser/config.

Returns the all the keys set for the current store as an array. Internally Sammy.Store keeps this array in a 'meta_key' for easy access.

loads the response of a request to path into key.

Example

In /mytemplate.tpl:

      My Template
      

In app.js:

      var store = new Sammy.Store;
      store.load('mytemplate', '/mytemplate.tpl', function() {
        s.get('mytemplate') //=> My Template
      });
      

Sets the value of key with value. If value is an object, it is turned to and stored as a string with JSON.stringify. It also tries to conform to the KVO pattern triggering jQuery events on the element that the store is bound to.

Example

        var store = new Sammy.Store({name: 'kvo'});
        $('body').bind('set-kvo-foo', function(e, data) {
          Sammy.log(data.key + ' changed to ' + data.value);
        });
        store.set('foo', 'bar'); // logged: foo changed to bar
      

This stub can be overridden, e.g. in jquery.tmplPlus for providing rendered events

Get: Use $.template( name ) to access a cached template. Also $( selectorToScriptBlock ).template(), or $.template( null, templateString ) will return the compiled template, without adding a name reference. If templateString includes at least one HTML tag, $.template( templateString ) is equivalent to $.template( null, templateString )

Consider the first wrapped element as a template declaration, and get the compiled template or store it as a named template.

Return wrapped set of template items, obtained by rendering template against data.

Use first wrapped element as template markup. Return wrapped set of template items, obtained by rendering template against data.

Find which rendered template item the first wrapped DOM element belongs to

Return rendered template item for an element.