Sammy.js has a lot more to offer than simply defining routes in the app. More advanced users can explore custom events and namespaces, for event-driven applications.
Sammy’s author Aaron and others provide additional functionality for your application. In this tutorial, you’ll get a summary of plugins that are available for Sammy, and then we’ll dive into a few that are important in building our single page applications.
In this post, you will build a single page application that receives JSON data, displays the data in various ways using templates, and stores the data to provide an off line experience. You will use the following plug-ins:
- Sammy.Mustache. Provides a quick way of using mustache style templates in your app.
In the later posts, you’ll learn more about:
- Sammy.Title. Allows you to easily set the document’s title for different routes.
- Sammy.Storage. An abstract adapter class that wraps the multitude of in browser data storage into a single common set of methods for storing and retrieving data
- Sammy.FormBuilder which make it easy to create HTML forms for creating and editing JavaScript objects
- Sammy.Flash which stores and send status messages to the client.
- Sammy.NestedParams overrides the default form parsing behavior to provide extended functionality for parsing Rack/Rails style form name/value pairs into JS Objects. In fact it passes the same suite of tests as Rack’s nested query parsing
Sammy Plugins
You can get Sammy Plugins within the Quirkey GitHub site.
Sammy includes a growing number of plugins that handle common extensions like caching and client-side templating.
First, here’s a subset of the templating engines that are supported:
- Sammy.Template: Extracted from Sammy’s core, this is a wrapper around John Resig’s simple templating engine and Greg Borenstein’s $.srender
- Sammy.Mustache: Wrapper around Mustache.js for rendering mustache templates.
- Sammy.Haml: Wrapper around haml-js for client-side rendering of Haml templates.
- Sammy.EJS is a thin wrapper around the EJS templating engine.
- Sammy.Handlebars provides a quick way of using Handlebars templates in your app.
- Sammy.Pure is a simple wrapper around the pure.js templating engine for use in Sammy apps.
These additional plugins live in the lib/plugins directory of the repository.
- Sammy.NestedParams: Parses form submissions that have nested param style names like Rack/Rails.
- Sammy.Storage/Sammy.Session/Sammy.Cache: Unified client-side key/value store with multiple back ends, including HTML5 Storage and Cookies
- sammy.cache.js A simple cache strategy that stores key/values in memory.
- Sammy.Flash is a plugin for storing and sending status messages to the client. It’s API and use is similar to Ruby on Rails’ `flash`.
- sammy.form.js Sammy.FormBuilder is based very closely on the Rails FormBuilder classes.
- Sammy.googleanalytics.js A simple plugin that pings Google Analytics tracker every time a route is triggered.
- Sammy.OAuth2 is a plugin for using OAuth 2.0 to authenticate users and access your application’s API. Requires Sammy.Session.
Sammy + Mustache
For this example, you will need jQuery, Sammy, and Mustache and have them in your script folder. All are available for your Visual Studio app from NuGet. I’ll use the path with Scripts for my script files.
Next, you will need to get the Sammy.Mustache plugin from the Sammy Plugins on GitHub. to your scripts folder.
Here is a sample mytemplate.ms file.
<div id="mytemplate"> <h3>{{title}}</h3> <p>Hey there, {{name}} Welcome to Mustache</p> </div>
And in my body tag, first load the libraries, which mustache.js before sammy.mustache.js. Then initialize the Sammy app.
var app = $.sammy()
Next use the mustache plugin. 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. you can change the default name of the method by passing a second argument (e.g. you could use the ms() as the method alias so that all the template files could be in the form file.ms instead of file.mustache).
this.use('Mustache', 'ms');
Then specify the route. In this case, the route is #/home and then pass in a parameter named :name.
this.get('#/hello/:name'
Next, you will pass a couple variables to the template: title and name. Note: This will not set the title on the page. You get the name parameter from the URL using this.params and then attach it to the this object that will be used by the template.
The body section looks like this:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<script src="Scripts/jquery-2.0.2.js"></script> | |
<script src="Scripts/mustache.js"></script> | |
<script src="Scripts/sammy-0.7.4.js"></script> | |
<script src="Scripts/sammy.mustache.js"></script> | |
<script> | |
var app = $.sammy(function() { | |
// include the plugin and alias mustache() to ms() | |
this.use('Mustache', 'ms'); | |
// to see this you will need to go to | |
// yourpage#/hello/AName | |
this.get('#/hello/:name', function() { | |
// set local vars | |
this.title = 'Hello!' | |
this.name = this.params.name; | |
// render the template and pass it through mustache | |
this.partial('mytemplate.ms'); | |
}); | |
}); | |
$(function() { | |
app.run() | |
}); | |
</script> |
When you run the app, go to yourpage.html#/home/YourName
NOTE: You can use Sammy’s EventContext methods partial()
or render()
to display your template. However, if you use render() you will need to apply the result to the DOM yourself. Here’s an example of using the render
method:
context.render('templates/item.template', {id: i, item: item}).appendTo(context.$element());
Summary
In this post, you’ve seen how you can combine Mustache with Sammy. In our next post, we’ll load data and display it.
Sample Code
You can view the sample code for this post in the DevDavs repository on GitHub: https://github.com/devdays/single-page-app/tree/master/Sammy