![What is a view? iv
6 this.render();
7 },
8 render: function(){
9 var template = _.template( $("#search_template").html(), {} );
10 this.el.html( template );
11 },
12 events: {
13 "click input[type=button]": "doSearch"
14 },
15 doSearch: function( event ){
16 // Button clicked, you can access the element that was clicked
17 with event.currentTarget
18 alert( "Search for " + $("#search_input").val() );
19 }
20 });
21
22 var search_view = new SearchView({ el: $("#search_container") });
23 </script>
24
25 <script type="text/template" id="search_template">
26 <label>Search</label>
27 <input type="text" id="search_input" />
28 <input type="button" id="search_button" value="Search" />
29 </script>
Tips and Tricks
Using template variables
1 <div id="search_container"></div>
2
3 <script type="text/javascript">
4 SearchView = Backbone.View.extend({
5 initialize: function(){
6 this.render();
7 },
8 render: function(){
9 //Pass variables in using Underscore.js Template
10 var variables = { search_label: "My Search" };
11 // Compile the template using underscore
12 var template = _.template( $("#search_template").html(), variab
13 les );
14 // Load the compiled HTML into the Backbone "el"
15 this.el.html( template );
16 },
17 events: {
18 "click input[type=button]": "doSearch"
19 },](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-10-320.jpg)
![What is a model? vii
Getting attributes
Using the model.get() method we can access model properties at anytime.
1 Person = Backbone.Model.extend({
2 initialize: function(){
3 alert("Welcome to this world");
4 }
5 });
6
7 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']})
8 ;
9
10 var age = person.get("age"); // 67
11 var name = person.get("name"); // "Thomas"
12 var children = person.get("children"); // ['Ryan']
Setting model defaults
Sometimes you will want your model to contain default values. This can easily be accomplished by setting
a property name ‘defaults’ in your model declaration.
1 Person = Backbone.Model.extend({
2 defaults: {
3 name: 'Fetus',
4 age: 0,
5 children: []
6 },
7 initialize: function(){
8 alert("Welcome to this world");
9 }
10 });
11
12 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']})
13 ;
14
15 var age = person.get("age"); // 67
16 var name = person.get("name"); // "Thomas"
17 var children = person.get("children"); // ['Ryan']
Manipulating model attributes
Models can contain as many custom methods as you like to manipulate attributes. By default all methods
are public.
1 Person = Backbone.Model.extend({
2 defaults: {](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-13-320.jpg)
![What is a model? viii
3 name: 'Fetus',
4 age: 0,
5 children: []
6 },
7 initialize: function(){
8 alert("Welcome to this world");
9 },
10 adopt: function( newChildsName ){
11 var children_array = this.get("children");
12 children_array.push( newChildsName );
13 this.set({ children: children_array });
14 }
15 });
16
17 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']})
18 ;
19 person.adopt('John Resig');
20 var children = person.get("children"); // ['Ryan', 'John Resig']
So we can implement methods to get/set and perform other calculations using attributes from our model
at any time.
Listening for changes to the model
Now onto one of the more useful parts of using a library such as backbone. All attributes of a model can
have listeners bound to them to detect changes to their values. In our initialize function we are going
to bind a function call everytime we change the value of our attribute. In this case if the name of our
“person” changes we will alert their new name.
1 Person = Backbone.Model.extend({
2 defaults: {
3 name: 'Fetus',
4 age: 0,
5 children: []
6 },
7 initialize: function(){
8 alert("Welcome to this world");
9 this.bind("change:name", function(){
10 var name = this.get("name"); // 'Stewie Griffin'
11 alert("Changed my name to " + name );
12 });
13 },
14 replaceNameAttr: function( name ){
15 this.set({ name: name });
16 }
17 });
18
19 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']})](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-14-320.jpg)
![What is a model? ix
20 ;
21 person.replaceNameAttr('Stewie Griffin'); // This triggers a change and
22 will alert()
So we can bind the a change listener to individual attributes or if we like simply ‘this.bind(“change”,
function(){});’ to listen for changes to all attributes of the model.
Fetching, Saving and Destroying
Models actually have to be a part of a collection for requests to the server to work by default. This tutorial
is more of a focus on individual models. Check back soon for a tutorial on collection implementation.
Tips and Tricks
Get all the current attributes
1 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']})
2 ;
3 var attributes = person.toJSON(); // { name: "Thomas", age: 67, childre
4 n: ['Ryan']}
5 /* This simply returns a copy of the current attributes. */
6 delete attributes;
7 var attributes = person.attributes;
8 /* The line above gives a direct reference to the attributes and you sh
9 ould be careful when playing with it. Best practise would suggest that yo
10 u use .set() to edit attributes of a model to take advantage of backbone li
11 steners. */
Validate data before you set or save it
1 Person = Backbone.Model.extend({
2 // If you return a string from the validate function,
3 // Backbone will throw an error
4 validate: function( attributes ){
5 if( attributes.age < 0 && attributes.name != "Dr Manhatten" ){
6 return "You can't be negative years old";
7 }
8 },
9 initialize: function(){
10 alert("Welcome to this world");
11 this.bind("error", function(model, error){
12 // We have received an error, log it, alert it or forget it
13 :)
14 alert( error );
15 });
16 }
17 });](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-15-320.jpg)
![What is a collection? xii
12 model: Song
13 });
14
15 var song1 = new Song({ name: "How Bizarre", artist: "OMC" });
16 var song2 = new Song({ name: "Sexual Healing", artist: "Marvin Gaye" })
17 ;
18 var song3 = new Song({ name: "Talk It Over In Bed", artist: "OMC" });
19
20 var myAlbum = new Album([ song1, song2, song3]);
21 console.log( myAlbum.models ); // [song1, song2, song3]](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-18-320.jpg)
21
22 [Activate another route](#/route/action)
23
24 _Notice the change in the url_
Please note: Prior to Backbone 0.5 (released 1. July 2011) a Router was called a Controller. To avoid
confusion, the Backbone developers changed the name to Router. Hence, if you find yourself using an
older version of Backbone you should write Backbone.Controller.extend({ ** });
Dynamic Routing
Most conventional frameworks allow you to define routes that contain a mix of static and dynamic route
parameters. For example you might want to retrieve a post with a variable id with a friendly URL string.
²⁰http://backbonetutorials.com/what-is-a-view
xiii](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-19-320.jpg)
25
26 [Post 130](#/posts/130)
27
28 _Notice the change in the url_
Dynamic Routing Cont. “:params” and “*splats”
Backbone uses two styles of variables when implementing routes. First there are “:params” which match
any URL components between slashes. Then there are “_splats” which match any number of URL
components. Note that due to the nature of a “_splat” it will always be the last variable in your URL
as it will match any and all components.
Any “*splats” or “:params” in route definitions are passed as arguments (in respective order) to the
associated function. A route defined as “/:route/:action” will pass 2 variables (“route” and “action”) to
the callback function. (If this is confusing please post a comment and I will try articulate it better)
Here are some examples of using “:params” and “*splats”
1 routes: {
2
3 "/posts/:id": "getPost",
4 // <a href="http://example.com/#/posts/121">Example</a>](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-20-320.jpg)
![Organizing your application using Modules (require.js) xix
What does the bootstrap look like?
Our bootstrap file will be responsible for configuring Require.js and loading initially important depen-
dencies.
In the below example we configure Require.js to create shortcut alias to commonly used scripts such as
jQuery, Underscore and Backbone.
Due to the nature of these libraries implementations we actually have to load them in order because they
each depend on each other existing in the global namespace(which is bad but is all we have to work with).
Hopefully if the AMD specification takes off these libraries will add code to allow themselves to be loaded
asynchronously. Due to this inconvience the bootstrap is not as intuitive as it could be, I hope to solve
this problem in the near future.
We also request a module called “app”, this will contain the entireity of our application logic.
Note: Modules are loaded relativly to the boot strap and always append with “.js”. So the module “app”
will load “app.js” which is in the same directory as the bootstrap.
1 // Filename: main.js
2
3 // Require.js allows us to configure shortcut alias
4 // There usage will become more apparent futher along in the tutorial.
5 require.config({
6 paths: {
7 jQuery: 'libs/jquery/jquery',
8 Underscore: 'libs/underscore/underscore',
9 Backbone: 'libs/backbone/backbone'
10 }
11
12 });
13
14 require([
15
16 // Load our app module and pass it to our definition function
17 'app',
18
19 // Some plugins have to be loaded in order due to there non AMD complianc
20 e
21 // Because these scripts are not "modules" they do not pass any values to
22 the definition function below
23 'order!libs/jquery/jquery-min',
24 'order!libs/underscore/underscore-min',
25 'order!libs/backbone/backbone-min'
26 ], function(App){
27 // The "app" dependency is passed in as "App"
28 // Again, the other dependencies passed in are not "AMD" therefore don't
29 pass a parameter to this function
30 App.initialize();
31 });](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-25-320.jpg)
![Organizing your application using Modules (require.js) xx
How should we lay out external scripts?
Any modules we develop for our application using AMD/Require.js will be asynchronously loaded.
We have a heavy dependency on jQuery, Underscore and Backbone, unfortunatly this libraries are loaded
synchronously and also depend on each other existing in the global namespace.
Below I propose a solution(until these libraries allow themselves to be loaded asynchronously) to allow
these libraries to be loaded properly(synchronously) and also removing themselves from global scope.
1 // Filename: libs/jquery/jquery.js
2
3 define([
4 // Load the original jQuery source file
5 'order!libs/jquery/jquery-min'
6 ], function(){
7 // Tell Require.js that this module returns a reference to jQuery
8 return $;
9 });
10
11
12 // Filename: libs/underscore/underscore
13 // As above lets load the original underscore source code
14 define(['order!libs/underscore/underscore-min'], function(){
15 // Tell Require.js that this module returns a reference to Underscore
16 return _;
17 });
18
19
20 // Filename: libs/backbone/backbone
21 // Finally lets load the original backbone source code
22 define(['order!libs/backbone/backbone-min'], function(){
23 // Now that all the orignal source codes have ran and accessed each other
24 // We can call noConflict() to remove them from the global name space
25 // Require.js will keep a reference to them so we can use them in our mod
26 ules
27 _.noConflict();
28 $.noConflict();
29 return Backbone.noConflict();
30 });
A boiler plate module
So before we start developing our application, let’s quickly look over boiler plate code that will be reused
quite often.
For convience sake I generally keep a “boilerplate.js” in my application root so I can copy it when I need
to.](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-26-320.jpg)
![Organizing your application using Modules (require.js) xxi
1 //Filename: boilerplate.js
2
3 define([
4 // These are path alias that we configured in our bootstrap
5 'jQuery', // lib/jquery/jquery
6 'Underscore', // lib/underscore/underscore
7 'Backbone' // lib/backbone/backbone
8 ], function($, _, Backbone){
9 // Above we have passed in jQuery, Underscore and Backbone
10 // They will not be accesible in the global scope
11 return {};
12 // What we return here will be used by other modules
13 });
The first argument of the define function is our dependency array, we can pass in any modules we like in
the future.
App.js Building our applications main module
Our applications main module should always remain quite light weight. This tutorial covers only setting
up a Backbone Router and initializing it in our main module.
The router will then load the correct dependencies depending on the current URL.
1 // Filename: app.js
2 define([
3 'jQuery',
4 'Underscore',
5 'Backbone',
6 'router', // Request router.js
7 ], function($, _, Backbone, Router){
8 var initialize = function(){
9 // Pass in our Router module and call it's initialize function
10 Router.initialize();
11 }
12
13 return {
14 initialize: initialize
15 };
16 });
17
18
19 // Filename: router.js
20 define([
21 'jQuery',
22 'Underscore',
23 'Backbone',
24 'views/projects/list',](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-27-320.jpg)
![Organizing your application using Modules (require.js) xxii
25 'views/users/list'
26 ], function($, _, Backbone, Session, projectListView, userListView){
27 var AppRouter = Backbone.Router.extend({
28 routes: {
29 // Define some URL routes
30 '/projects': 'showProjects',
31 '/users': 'showUsers',
32
33 // Default
34 '*actions": "defaultAction'
35 },
36 showProjects: function(){
37 // Call render on the module we loaded in via the dependency array
38 // 'views/projects/list'
39 projectListView.render();
40 },
41 // As above, call render on our loaded module
42 // 'views/users/list'
43 showUsers: function(){
44 userListView.render();
45 },
46 defaultAction: function(actions){
47 // We have no matching route, lets just log what the URL was
48 console.log('No route:', actions);
49 }
50 });
51
52 var initialize = function(){
53 var app_router = new AppRouter;
54 Backbone.history.start();
55 };
56 return {
57 initialize: initialize
58 };
59 });
Modularizing a Backbone View
Backbone views most usually always interact with the DOM, using our new modular system we can load
in Javascript templates using Require.js text! plugin.
1 // Filename: views/project/list
2 define([
3 'jQuery',
4 'Underscore',
5 'Backbone',
6 // Using the Require.js text! plugin, we are loaded raw text
7 // which will be used as our views primary template](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-28-320.jpg)
![Organizing your application using Modules (require.js) xxiii
8 'text!templates/project/list.html'
9 ], function($, _, Backbone, projectListTemplate){
10 var projectListView = Backbone.View.extend({
11 el: $('#container'),
12 render: function(){
13 // Using Underscore we can compile our template with data
14 var data = {};
15 var compiledTemplate = _.template( projectListTemplate, data );
16 // Append our compiled template to this Views "el"
17 this.el.append( compiledTemplate );
18 }
19 });
20 // Our module now returns an instantiated view
21 // Sometimes you might return an un-instantiated view e.g. return project
22 ListView
23 return new projectListView;
24 });
Javascript templating allows us to seperate the design from the application logic placing all our html in
the templates folder.
Modularizing a Collection, Model and View
Now we put it altogether by chaining up a Model, Collection and View which is a typical scenairo when
building a Backbone.js application.
First off we will define our model
1 // Filename: models/project
2 define([
3 'Underscore',
4 'Backbone'
5 ], function(_, Backbone){
6 var projectModel = Backbone.Model.extend({
7 defaults: {
8 name: "Harry Potter"
9 }
10 });
11 // You usually don't return a model instantiated
12 return projectModel;
13 });
Now we have a model, our collection module can depend on it. We will set the “model” attribute of our
collection to the loaded module. Backbone.js offers great benefits when doing this.
Collection.model: Override this property to specify the model class that the collection
contains. If defined, you can pass raw attributes objects (and arrays) to add, create, and
reset, and the attributes will be converted into a model of the proper type.](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-29-320.jpg)
![Organizing your application using Modules (require.js) xxiv
1 // Filename: collections/projects
2 define([
3 'Underscore',
4 'Backbone',
5 // Pull in the Model module from above
6 'models/project'
7 ], function(_, Backbone, projectModel){
8 var projectCollection = Backbone.Collection.extend({
9 model: projectModel
10 });
11 // You don't usually return a collection instantiated
12 return new projectCollection;
13 });
Now we can simply depend on our collection in our view and pass it to our Javascript template.
1 // Filename: views/projects/list
2 define([
3 'jQuery',
4 'Underscore',
5 'Backbone',
6 // Pull in the Collection module from above
7 'collections/projects',
8 'text!templates/projects/list
9 ], function(_, Backbone, projectsCollection, projectsListTemplate){
10 var projectListView = Backbone.View.extend({
11 el: $("#container"),
12 initialize: function(){
13 this.collection = new projectsCollection;
14 this.collection.add({ name: "Ginger Kid"});
15 // Compile the template using Underscores micro-templating
16 var compiledTemplate = _.template( projectsListTemplate, { projects:
17 this.collection.models } );
18 this.el.html(compiledTemplate);
19 }
20 });
21 // Returning instantiated views can be quite useful for having "state"
22 return new projectListView;
23 });
Conclusion
Looking forward to feedback so I can turn this post and example into quality references on building
modular Javascript applications.
Get in touch with me on twitter, comments or github!](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-30-320.jpg)
![Lightweight Infinite Scrolling using Twitter
API
Getting started
In this example we are going to build a widget that pulls in tweets and when the user scrolls to the bottom
of the widget Backbone.js will resync with the server to bring down the next page of results.
Example Demo³⁶
Example Source³⁷
Note: This tutorial will use AMD³⁸ for modularity.
The Twitter Collection
Twitter offers a jsonp API for browsing tweets. The first thing to note is that we have to append
‘&callback?’ to allow cross domain ajax calls which is a feature of jsonp³⁹.
Using the ‘q’ and ‘page’ query parameters we can find the results we are after. In the collection definition
below we have set some defaults which can be overridden at any point.
Twitter’s search API actually returns a whole bunch of meta information alongside the results. Though
this is a problem for Backbone.js because a Collection expects to be populated with an array of objects.
So in our collection definition we can override the Backbone.js default parse function to instead choose
the correct property to populate the collection.
1 // collections/twitter.js
2 define([
3 'jquery',
4 'underscore',
5 'backbone'
6 ], function($, _, Backbone){
7 var Tweets = Backbone.Collection.extend({
8 url: function () {
9 return 'http://search.twitter.com/search.json?q=' + this.query + '&pa
10 ge=' + this.page + '&callback=?'
11 },
12 // Because twitter doesn't return an array of models by default we need
13 // to point Backbone.js at the correct property
14 parse: function(resp, xhr) {
15 return resp.results;
16 },
17 page: 1,
18 query: 'backbone.js tutorials'
³⁶http://backbonetutorials.com/examples/infinite-scroll/
³⁷https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/infinite-scroll
³⁸http://backbonetutorials.com/organizing-backbone-using-modules
³⁹http://en.wikipedia.org/wiki/JSONP
xxvi](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-32-320.jpg)
![Lightweight Infinite Scrolling using Twitter API xxvii
19 });
20
21 return Tweets;
22 });
Note: Feel free to attach the meta information returned by Twitter to the collection itself e.g.
1 parse: function(resp, xhr) {
2 this.completed_in = resp.completed_in
3 return resp.results;
4 },
Setting up the View
The first thing to do is load our Twitter collection and template into the widget module. We should attach
our collection to our view in our initialize function. loadResults will be responsible for calling fetch
on our Twitter collection. On success we will append the latest results to our widget using our template.
Our Backbone.js events will listen for scroll on the current el of the view which is ‘.twitter-widget’.
If the current scrollTop is at the bottom then we simply increment the Twitter collections current page
property and call loadResults again.
1 // views/twitter/widget.js
2 define([
3 'jquery',
4 'underscore',
5 'backbone',
6 'vm',
7 'collections/twitter',
8 'text!templates/twitter/list.html'
9 ], function($, _, Backbone, Vm, TwitterCollection, TwitterListTemplate){
10 var TwitterWidget = Backbone.View.extend({
11 el: '.twitter-widget',
12 initialize: function () {
13 // isLoading is a useful flag to make sure we don't send off more tha
14 n
15 // one request at a time
16 this.isLoading = false;
17 this.twitterCollection = new TwitterCollection();
18 },
19 render: function () {
20 this.loadResults();
21 },
22 loadResults: function () {
23 var that = this;
24 // we are starting a new load of results so set isLoading to true
25 this.isLoading = true;
26 // fetch is Backbone.js native function for calling and parsing the c
27 ollection url](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-33-320.jpg)
![Simple example - Node.js, Restify, MongoDb and Mongoose xxxiii
This wraps up the server side of things, if you follow the example⁴⁹ then you should see something like
http://backbonetutorials.nodejitsu.com/messages⁵⁰
Note: Again you must remember to change the Model⁵¹ and Collection⁵² definitions to match your server
address.
Setting up the client(Backbone.js)
I’ve actually used the latest copy of http://backboneboilerplate.com⁵³ to set up the example page.
The important files you will want to check out are;
• views/dashboard/page.js
• views/guestbook/form.js
• views/guestbook/list.js
• models/message.js
• collections/messages.js
• templates/guestbook/
Saving a message
First of all we want to setup a template⁵⁴ for showing our form that creates new messages.
1 <textarea class="message"></textarea>
2 <button class="post-message">Post Message</button>
This template gets inserted into the DOM by views/guestbook/form.js, this Backbone view also handles
the interaction of the form and the posting of the new data.
Let us create a Backbone Model that has the correct url for our restFul interface.
1 define([
2 'underscore',
3 'backbone'
4 ], function(_, Backbone) {
5 var Message = Backbone.Model.extend({
6 url: 'http://localhost:8080/messages'
7 });
8 return Message;
9 });
⁴⁹https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/server.js
⁵⁰http://backbonetutorials.nodejitsu.com/messages
⁵¹https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/js/models/message.js
⁵²https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/js/collections/messages.
js
⁵³http://backboneboilerplate.com
⁵⁴https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/templates/guestbook/
form.html](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-39-320.jpg)
![Simple example - Node.js, Restify, MongoDb and Mongoose xxxiv
We can see how we require our pre-defined model for messages and also our form template.
1 define([
2 'jquery',
3 'underscore',
4 'backbone',
5 'models/message',
6 'text!templates/guestbook/form.html'
7 ], function($, _, Backbone, MessageModel, guestbookFormTemplate){
8 var GuestbookForm = Backbone.View.extend({
9 el: '.guestbook-form-container',
10 render: function () {
11 $(this.el).html(guestbookFormTemplate);
12
13 },
14 events: {
15 'click .post-message': 'postMessage'
16 },
17 postMessage: function() {
18 var that = this;
19
20 var message = new MessageModel();
21 message.save({ message: $('.message').val()}, {
22 success: function () {
23 that.trigger('postMessage');
24 }
25 });
26 }
27 });
28 return GuestbookForm;
29 });
Note: trigger is from Backbone Events, I binded a listener to this view in views/dashboard/page.js so
that when a new message is submitted, the list is re-rendered. We are setting the date of post on the server
so there is no need to pass it up now.
Retrieving a list of messages
We setup a route on our server to generate a list of all available messages at GET /messages. So we need
to define a collection with the appropriate url to fetch this data down.
1 define([
2 'jquery',
3 'underscore',
4 'backbone',
5 'models/message'
6 ], function($, _, Backbone, MessageModel){
7 var Messages = Backbone.Collection.extend({](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-40-320.jpg)
![Simple example - Node.js, Restify, MongoDb and Mongoose xxxv
8 model: MessageModel, // Generally best practise to bring down a Model/S
9 chema for your collection
10 url: 'http://localhost:8080/messages'
11 });
12
13 return Messages;
14 });
Now that we have a collection to use we can setup our views/list.js to require the collection and trigger
a fetch. Once the fetch is complete we want to render our returned data to a template and insert it into
the DOM.
1 define([
2 'jquery',
3 'underscore',
4 'backbone',
5 'collections/messages',
6 'text!templates/guestbook/list.html'
7 ], function($, _, Backbone, MessagesCollection, guestbookListTemplate){
8 var GuestbookList = Backbone.View.extend({
9 el: '.guestbook-list-container',
10 render: function () {
11 var that = this;
12 var messages = new MessagesCollection();
13 messages.fetch({
14 success: function(messages) {
15 $(that.el).html(_.template(guestbookListTemplate, {messages: mess
16 ages.models, _:_}));
17 }
18 });
19 }
20 });
21 return GuestbookList;
22 });
The template file should iterate over messages.models which is an array and print out a HTML fragment
for each model.
1 <% _.each(messages, function(message) { %>
2
3 <p><%= message.get('message') %></p>
4 <em><%= message.get('date') %></em>
5
6 <% }); %>
This actually sums up everything you need to know to implement this simple example.](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-41-320.jpg)
![Cross-domain Backbone.js with sessions using CORS xxxviii
Getting started
To easily understand this tutorial you should jump straight into the example code base.
Host the codebase on a simple http server such that the domain is localhost with port 80 hidden.
Example Codebase⁶²
Example Demo⁶³
This tutorial focuses on building a flexible Session model to control session state in your application.
Checking session state at first load
Before starting any routes, we should really know if the user is authed or not. This will allow us to load
the appropiate views. We will simply wrap our Backbone.history.start in a callback that executes after
Session.getAuth has checked the server. We will jump into our Session model next.
1 define([
2 'jquery',
3 'underscore',
4 'backbone',
5 'vm',
6 'events',
7 'models/session',
8 'text!templates/layout.html'
9 ], function($, _, Backbone, Vm, Events, Session, layoutTemplate){
10 var AppView = Backbone.View.extend({
11 el: '.container',
12 initialize: function () {
13 $.ajaxPrefilter( function( options, originalOptions, jqXHR ) {
14 // Your server goes below
15 //options.url = 'http://localhost:8000' + options.url;
16 options.url = 'http://cross-domain.nodejitsu.com' + options.url;
17 });
18
19 },
20 render: function () {
21 var that = this;
22 $(this.el).html(layoutTemplate);
23 // This is the entry point to your app, therefore
24 // when the user refreshes the page we should
25 // really know if they're authed. We will give it
26 // A call back when we know what the auth status is
27 Session.getAuth(function () {
28 Backbone.history.start();
29 })
30 }
⁶²https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/cross-domain
⁶³http://backbonetutorials.com/examples/cross-domain/](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-44-320.jpg)
![Cross-domain Backbone.js with sessions using CORS xxxix
31 });
32 return AppView;
33 });
Note: We have used jQuery ajaxPrefilter to hook into all AJAX requests before they are executed. This
is where we specify what server we want the application to hit.
An example Session model
This is a very light weight Session model which handles most situations. Read through the code and
comments below. The model simply has a login, logout and check function. Again we have hooked
into jQuery ajaxPrefilter to allow for csrf tokens and also telling jQuery to send cookies with the
withCredentials property. The model relies heavily on it’s auth property. Throughout your application,
each view can simply bind to change:auth on the Session model and react accordingly. Because we return
this AMD module instantiated using the new keyword, then it will keep state throughout the page. (This
may not be best practise but it’s highly convenient)
1 // views/app.js
2 define([
3 'underscore',
4 'backbone'
5 ], function(_, Backbone) {
6 var SessionModel = Backbone.Model.extend({
7
8 urlRoot: '/session',
9 initialize: function () {
10 var that = this;
11 // Hook into jquery
12 // Use withCredentials to send the server cookies
13 // The server must allow this through response headers
14 $.ajaxPrefilter( function( options, originalOptions, jqXHR ) {
15 options.xhrFields = {
16 withCredentials: true
17 };
18 // If we have a csrf token send it through with the next request
19 if(typeof that.get('_csrf') !== 'undefined') {
20 jqXHR.setRequestHeader('X-CSRF-Token', that.get('_csrf'));
21 }
22 });
23 },
24 login: function(creds) {
25 // Do a POST to /session and send the serialized form creds
26 this.save(creds, {
27 success: function () {}
28 });
29 },
30 logout: function() {
31 // Do a DELETE to /session and clear the clientside data](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-45-320.jpg)
![Cross-domain Backbone.js with sessions using CORS xl
32 var that = this;
33 this.destroy({
34 success: function (model, resp) {
35 model.clear()
36 model.id = null;
37 // Set auth to false to trigger a change:auth event
38 // The server also returns a new csrf token so that
39 // the user can relogin without refreshing the page
40 that.set({auth: false, _csrf: resp._csrf});
41
42 }
43 });
44 },
45 getAuth: function(callback) {
46 // getAuth is wrapped around our router
47 // before we start any routers let us see if the user is valid
48 this.fetch({
49 success: callback
50 });
51 }
52 });
53 return new SessionModel();
54
55 });
Note: This session model is missing one useful feature. If a user looses auth when navigating your
application then the application should set {auth: false} on this model. To do this, in the ajaxPrefilter
edit outgoing success functions to check if the server response was {auth: false} and then call the original
success() function.
Hooking up views to listen to changes in auth
Now that we have a Session model, let’s hook up our login/logout view to listen to changes in auth.
When creating the view we use on to bind a listener to the auth attribute of our model. Everytime is
changes we will re-render the view which will conditionally load a template depending on the value of
Session.get('auth').
1 // models/session.js
2 define([
3 'jquery',
4 'underscore',
5 'backbone',
6 'models/session',
7 'text!templates/example/login.html',
8 'text!templates/example/logout.html'
9 ], function($, _, Backbone, Session, exampleLoginTemplate, exampleLogoutTem
10 plate){
11 var ExamplePage = Backbone.View.extend({](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-46-320.jpg)
![Cross-domain Backbone.js with sessions using CORS xli
12 el: '.page',
13 initialize: function () {
14 var that = this;
15 // Bind to the Session auth attribute so we
16 // make our view act recordingly when auth changes
17 Session.on('change:auth', function (session) {
18 that.render();
19 });
20 },
21 render: function () {
22 // Simply choose which template to choose depending on
23 // our Session models auth attribute
24 if(Session.get('auth')){
25 this.$el.html(_.template(exampleLogoutTemplate, {username: Session.
26 get('username')}));
27 } else {
28 this.$el.html(exampleLoginTemplate);
29 }
30 },
31 events: {
32 'submit form.login': 'login', // On form submission
33 'click .logout': 'logout'
34 },
35 login: function (ev) {
36 // Disable the button
37 $('[type=submit]', ev.currentTarget).val('Logging in').attr('disabled
38 ', 'disabled');
39 // Serialize the form into an object using a jQuery plgin
40 var creds = $(ev.currentTarget).serializeObject();
41 Session.login(creds);
42 return false;
43 },
44 logout: function (ev) {
45 // Disable the button
46 $(ev.currentTarget).text('Logging out').attr('disabled', 'disabled');
47 Session.logout();
48 }
49 });
50 return ExamplePage;
51 });
Note: .serializeObject is not a native jQuery function and I have included it in [app.js](https://github.com/thomasdav
pages/examples/cross-domain/js/views/app.js) in the demo folder. creds can be an object of any
variation of inputs, regardless it will be converted to JSON and posted to the server like any normal
Backbone model.
Here are the templates we are using for our login view
1 <!-- templates/example/login.html -->
2 <form class="login">](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-47-320.jpg)
![Cross-domain Backbone.js with sessions using CORS xliii
Example node server
This server below implements everything we talked about above. It should be relativly easy to see how
would translate into other frameworks and languages. app.configure runs the specified libraries against
every request. We have told the server that on each request it should check the csrf token and check if
the origin domain is white-listed. If so we edit each request to contain the appropiate headers.
This server has 3 end points, that are pseduo-restful;
• POST /session - Login - Sets the session username and returns a csrf token for the user to use
• DELETE /session - Logout - Destroys the session and regenerates a new csrf token if the user wants
to re-login
• GET /session - Checks Auth - Simply returns if auth is true or false, if true then also returns some
session details
var express = require(‘express’);
var connect = require(‘connect’); // Custom csrf library var csrf = require(‘./csrf’);
var app = express.createServer();
var allowCrossDomain = function(req, res, next) { // Added other domains you want the server to
give access to // WARNING - Be careful with what origins you give access to var allowedHost = [
‘http://backbonetutorials.com’, ‘http://localhost’ ];
1 if(allowedHost.indexOf(req.headers.origin) !== -1) {
2 res.header('Access-Control-Allow-Credentials', true);
3 res.header('Access-Control-Allow-Origin', req.headers.origin)
4 res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS')
5 ;
6 res.header('Access-Control-Allow-Headers', 'X-CSRF-Token, X-Requested-Wit
7 h, Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date,
8 X-Api-Version');
9 next();
10 } else {
11 res.send({auth: false});
12 }
}
app.configure(function() { app.use(express.cookieParser()); app.use(express.session({ secret: ‘thomas-
davislovessalmon’ })); app.use(express.bodyParser()); app.use(allowCrossDomain); app.use(csrf.check);
});
app.get(‘/session’, function(req, res){ // This checks the current users auth // It runs before Backbones
router is started // we should return a csrf token for Backbone to use if(typeof req.session.username
!== ‘undefined’){ res.send({auth: true, id: req.session.id, username: req.session.username, _csrf:
req.session._csrf}); } else { res.send({auth: false, _csrf: req.session._csrf}); } });
app.post(‘/session’, function(req, res){
// Login // Here you would pull down your user credentials and match them up // to the request
req.session.username = req.body.username; res.send({auth: true, id: req.session.id, username:
req.session.username}); });](https://image.slidesharecdn.com/backbonetutorials-121022012215-phpapp02/85/Backbonetutorials-49-320.jpg)
Backbonetutorials
- 1. Backbone Tutorials Beginner, Intermediate and Advanced Thomas Davis
- 2. Backbone Tutorials Beginner, Intermediate and Advanced ©2012 Thomas Davis This version was published on 2012-06-25 This is a Leanpub book, for sale at: http://leanpub.com/backbonetutorials Leanpub helps authors to self-publish in-progress ebooks. We call this idea Lean Publishing. To learn more about Lean Publishing, go to: http://leanpub.com/manifesto To learn more about Leanpub, go to: http://leanpub.com
- 3. Tweet This Book! Please help Thomas Davis by spreading the word about this book on Twitter! The suggested hashtag for this book is #backbonetutorials. Find out what other people are saying about the book by clicking on this link to search for this hashtag on Twitter: https://twitter.com/search/#backbonetutorials
- 4. Contents Why do you need Backbone.js? i So how does Backbone.js help? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Relevant Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i What is a view? ii The “el” property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii Loading a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii Listening for events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv Relevant Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v What is a model? vi Setting attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Getting attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Setting model defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Manipulating model attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Listening for changes to the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Fetching, Saving and Destroying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x What is a collection? xi Building a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi What is a router? xiii Dynamic Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Dynamic Routing Cont. “:params” and “*splats” . . . . . . . . . . . . . . . . . . . . . . . . . . xiv Relevant Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv i
- 5. CONTENTS ii Organizing your application using Modules (require.js) xvi What is AMD? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi Why Require.js? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Example File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Bootstrapping your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii What does the bootstrap look like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix How should we lay out external scripts? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx A boiler plate module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx App.js Building our applications main module . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Modularizing a Backbone View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii Modularizing a Collection, Model and View . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv Relevant Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv Lightweight Infinite Scrolling using Twitter API xxvi Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi The Twitter Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi Setting up the View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii The widget template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii Simple example - Node.js, Restify, MongoDb and Mongoose xxx Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx The technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx Restify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx MongoDb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx Mongoose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx Building the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi Restify configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi MongoDb/Mongoose configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi Mongoose Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi Setting up the routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii Setting up the client(Backbone.js) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
- 6. CONTENTS iii Saving a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii Retrieving a list of messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiv Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvi Relevant Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvi Cross-domain Backbone.js with sessions using CORS xxxvii Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvii Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxviii Checking session state at first load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxviii An example Session model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxix Hooking up views to listen to changes in auth . . . . . . . . . . . . . . . . . . . . . . . . . . . xl Building a compatible server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlii Example node server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xliii Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xliv Relevant Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xliv
- 7. Why do you need Backbone.js? Building single-page web apps or complicated user interfaces will get extremely difficult by simply using jQuery¹ or MooTools². The problem is standard JavaScript libraries are great at what they do - and without realizing it you can build an entire application without any formal structure. You will with ease turn your application into a nested pile of jQuery callbacks, all tied to concrete DOM elements. I shouldn’t need to explain why building something without any structure is a bad idea. Of course you can always invent your own way of implement your own way of structuring your application but you miss out on the benefits of the open source community. So how does Backbone.js help? a. Backbone is an incredibly small library for the amount of functionality and structure it gives you. One can not easily summarize the benefits you will reap from using it. If you read through some of the beginner tutorials the benefits will soon become self evident and due to Backbone.js light nature you can incrementally include it in any current or future projects. Relevant Links • Backbone.js official website”³ • great hackernews discussion /w post from author⁴ Contributors • FND⁵ ¹http://jquery.com ²http://mootools.net ³http://documentcloud.github.com/backbone/ ⁴http://news.ycombinator.com/item?id=2119704 ⁵https://github.com/FND i
- 8. What is a view? Backbone views are used to reflect what your applications’ data models look like. They are also used to listen to events and react accordingly. This tutorial will not be addressing how to bind models and collections to views but will focus on view functionality and how to use views with a JavaScript templating library, specifically Underscore.js’s _.template⁶. We will be using jQuery 1.5⁷ as our DOM manipulator. It’s possible to use other libraries such as MooTools⁸ or Sizzle⁹, but official Backbone.js documentation endorses jQuery. Backbone.View events may not work with other libraries other than jQuery. For the purposes of this demonstration, we will be implementing a search box. A live example¹⁰ can be found on jsFiddle. 1 SearchView = Backbone.View.extend({ 2 initialize: function(){ 3 alert("Alerts suck."); 4 } 5 }); 6 7 // The initialize function is always called when instantiating a Backbo 8 ne View. 9 // Consider it the constructor of the class. 10 var search_view = new SearchView; The “el” property The “el” property references the DOM object created in the browser. Every Backbone.js view has an “el” property, and if it not defined, Backbone.js will construct its own, which is an empty div element. Let us set our view’s “el” property to div#search_container, effectively making Backbone.View the owner of the DOM element. 1 <div id="search_container"></div> 2 3 <script type="text/javascript"> 4 SearchView = Backbone.View.extend({ 5 initialize: function(){ 6 alert("Alerts suck."); 7 } 8 }); 9 10 var search_view = new SearchView({ el: $("#search_container") }); 11 </script> Note: Keep in mind that this binds the container element. Any events we trigger must be in this element. ⁶http://documentcloud.github.com/underscore/#template ⁷http://jquery.com/ ⁸http://mootools.net/ ⁹http://sizzlejs.com/ ¹⁰http://jsfiddle.net/thomas/C9wew/6 ii
- 9. What is a view? iii Loading a template Backbone.js is dependent on Underscore.js, which includes its own micro-templating solution. Refer to Underscore.js’s documentation¹¹ for more information. Let us implement a “render()” function and call it when the view is initialized. The “render()” function will load our template into the view’s “el” property using jQuery. 1 <div id="search_container"></div> 2 3 <script type="text/javascript"> 4 SearchView = Backbone.View.extend({ 5 initialize: function(){ 6 this.render(); 7 }, 8 render: function(){ 9 // Compile the template using underscore 10 var template = _.template( $("#search_template").html(), {} ); 11 // Load the compiled HTML into the Backbone "el" 12 this.el.html( template ); 13 } 14 }); 15 16 var search_view = new SearchView({ el: $("#search_container") }); 17 </script> 18 19 <script type="text/template" id="search_template"> 20 <label>Search</label> 21 <input type="text" id="search_input" /> 22 <input type="button" id="search_button" value="Search" /> 23 </script> Tip: Place all your templates in a file and serve them from a CDN. This ensures your users will always have your application cached. Listening for events To attach a listener to our view, we use the “events” attribute of Backbone.View. Remember that event listeners can only be attached to child elements of the “el” property. Let us attach a “click” listener to our button. 1 <div id="search_container"></div> 2 3 <script type="text/javascript"> 4 SearchView = Backbone.View.extend({ 5 initialize: function(){ ¹¹http://documentcloud.github.com/underscore/
- 10. What is a view? iv 6 this.render(); 7 }, 8 render: function(){ 9 var template = _.template( $("#search_template").html(), {} ); 10 this.el.html( template ); 11 }, 12 events: { 13 "click input[type=button]": "doSearch" 14 }, 15 doSearch: function( event ){ 16 // Button clicked, you can access the element that was clicked 17 with event.currentTarget 18 alert( "Search for " + $("#search_input").val() ); 19 } 20 }); 21 22 var search_view = new SearchView({ el: $("#search_container") }); 23 </script> 24 25 <script type="text/template" id="search_template"> 26 <label>Search</label> 27 <input type="text" id="search_input" /> 28 <input type="button" id="search_button" value="Search" /> 29 </script> Tips and Tricks Using template variables 1 <div id="search_container"></div> 2 3 <script type="text/javascript"> 4 SearchView = Backbone.View.extend({ 5 initialize: function(){ 6 this.render(); 7 }, 8 render: function(){ 9 //Pass variables in using Underscore.js Template 10 var variables = { search_label: "My Search" }; 11 // Compile the template using underscore 12 var template = _.template( $("#search_template").html(), variab 13 les ); 14 // Load the compiled HTML into the Backbone "el" 15 this.el.html( template ); 16 }, 17 events: { 18 "click input[type=button]": "doSearch" 19 },
- 11. What is a view? v 20 doSearch: function( event ){ 21 // Button clicked, you can access the element that was clicked 22 with event.currentTarget 23 alert( "Search for " + $("#search_input").val() ); 24 } 25 }); 26 27 var search_view = new SearchView({ el: $("#search_container") }); 28 </script> 29 30 <script type="text/template" id="search_template"> 31 <!-- Access template variables with <%= %> --> 32 <label><%= search_label %></label> 33 <input type="text" id="search_input" /> 34 <input type="button" id="search_button" value="Search" /> 35 </script> Relevant Links • This example implemented with google API¹² • This examples exact code on jsfiddle.net¹³ • Another semi-complete example on jsFiddle¹⁴ Contributors • Michael Macias¹⁵ • Alex Lande¹⁶ ¹²http://thomasdavis.github.com/2011/02/05/backbone-views-and-templates.html ¹³http://jsfiddle.net/thomas/C9wew/4/ ¹⁴http://jsfiddle.net/thomas/dKK9Y/6/ ¹⁵https://github.com/zaeleus ¹⁶https://github.com/lawnday
- 12. What is a model? Across the internet the definition of MVC¹⁷ is so diluted that it’s hard to tell what exactly your model should be doing. The authors of backbone.js have quite a clear definition of what they believe the model represents in backbone.js. Models are the heart of any JavaScript application, containing the interactive data as well as a large part of the logic surrounding it: conversions, validations, computed properties, and access control. So for the purpose of the tutorial let’s create a model. 1 Person = Backbone.Model.extend({ 2 initialize: function(){ 3 alert("Welcome to this world"); 4 } 5 }); 6 7 var person = new Person; So initialize() is triggered whenever you create a new instance of a model( models, collections and views work the same way ). You don’t have to include it in your model declaration but you will find yourself using it more often than not. Setting attributes Now we want to pass some parameters when we create an instance of our model. 1 Person = Backbone.Model.extend({ 2 initialize: function(){ 3 alert("Welcome to this world"); 4 } 5 }); 6 7 var person = new Person({ name: "Thomas", age: 67}); 8 delete person; 9 // or we can set afterwards, these operations are equivelent 10 var person = new Person(); 11 person.set({ name: "Thomas", age: 67}); So passing a javascript object to our constructor is the same as calling model.set(). Now that these models have attributes set we need to be able to retrieve them. ¹⁷http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller vi
- 13. What is a model? vii Getting attributes Using the model.get() method we can access model properties at anytime. 1 Person = Backbone.Model.extend({ 2 initialize: function(){ 3 alert("Welcome to this world"); 4 } 5 }); 6 7 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']}) 8 ; 9 10 var age = person.get("age"); // 67 11 var name = person.get("name"); // "Thomas" 12 var children = person.get("children"); // ['Ryan'] Setting model defaults Sometimes you will want your model to contain default values. This can easily be accomplished by setting a property name ‘defaults’ in your model declaration. 1 Person = Backbone.Model.extend({ 2 defaults: { 3 name: 'Fetus', 4 age: 0, 5 children: [] 6 }, 7 initialize: function(){ 8 alert("Welcome to this world"); 9 } 10 }); 11 12 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']}) 13 ; 14 15 var age = person.get("age"); // 67 16 var name = person.get("name"); // "Thomas" 17 var children = person.get("children"); // ['Ryan'] Manipulating model attributes Models can contain as many custom methods as you like to manipulate attributes. By default all methods are public. 1 Person = Backbone.Model.extend({ 2 defaults: {
- 14. What is a model? viii 3 name: 'Fetus', 4 age: 0, 5 children: [] 6 }, 7 initialize: function(){ 8 alert("Welcome to this world"); 9 }, 10 adopt: function( newChildsName ){ 11 var children_array = this.get("children"); 12 children_array.push( newChildsName ); 13 this.set({ children: children_array }); 14 } 15 }); 16 17 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']}) 18 ; 19 person.adopt('John Resig'); 20 var children = person.get("children"); // ['Ryan', 'John Resig'] So we can implement methods to get/set and perform other calculations using attributes from our model at any time. Listening for changes to the model Now onto one of the more useful parts of using a library such as backbone. All attributes of a model can have listeners bound to them to detect changes to their values. In our initialize function we are going to bind a function call everytime we change the value of our attribute. In this case if the name of our “person” changes we will alert their new name. 1 Person = Backbone.Model.extend({ 2 defaults: { 3 name: 'Fetus', 4 age: 0, 5 children: [] 6 }, 7 initialize: function(){ 8 alert("Welcome to this world"); 9 this.bind("change:name", function(){ 10 var name = this.get("name"); // 'Stewie Griffin' 11 alert("Changed my name to " + name ); 12 }); 13 }, 14 replaceNameAttr: function( name ){ 15 this.set({ name: name }); 16 } 17 }); 18 19 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']})
- 15. What is a model? ix 20 ; 21 person.replaceNameAttr('Stewie Griffin'); // This triggers a change and 22 will alert() So we can bind the a change listener to individual attributes or if we like simply ‘this.bind(“change”, function(){});’ to listen for changes to all attributes of the model. Fetching, Saving and Destroying Models actually have to be a part of a collection for requests to the server to work by default. This tutorial is more of a focus on individual models. Check back soon for a tutorial on collection implementation. Tips and Tricks Get all the current attributes 1 var person = new Person({ name: "Thomas", age: 67, children: ['Ryan']}) 2 ; 3 var attributes = person.toJSON(); // { name: "Thomas", age: 67, childre 4 n: ['Ryan']} 5 /* This simply returns a copy of the current attributes. */ 6 delete attributes; 7 var attributes = person.attributes; 8 /* The line above gives a direct reference to the attributes and you sh 9 ould be careful when playing with it. Best practise would suggest that yo 10 u use .set() to edit attributes of a model to take advantage of backbone li 11 steners. */ Validate data before you set or save it 1 Person = Backbone.Model.extend({ 2 // If you return a string from the validate function, 3 // Backbone will throw an error 4 validate: function( attributes ){ 5 if( attributes.age < 0 && attributes.name != "Dr Manhatten" ){ 6 return "You can't be negative years old"; 7 } 8 }, 9 initialize: function(){ 10 alert("Welcome to this world"); 11 this.bind("error", function(model, error){ 12 // We have received an error, log it, alert it or forget it 13 :) 14 alert( error ); 15 }); 16 } 17 });
- 16. What is a model? x 18 19 var person = new Person; 20 person.set({ name: "Mary Poppins", age: -1 }); 21 // Will trigger an alert outputting the error 22 delete person; 23 24 var person = new Person; 25 person.set({ name: "Dr Manhatten", age: -1 }); 26 // God have mercy on our souls Contributors • Utkarsh Kukreti¹⁸ ¹⁸https://github.com/utkarshkukreti
- 17. What is a collection? Backbone collections are simply an ordered set of models¹⁹. Such that it can be used in situations such as; • Model: Student, Collection: ClassStudents • Model: Todo Item, Collection: Todo List • Model: Animals, Collection: Zoo Typically your collection will only use one type of model but models themselves are not limited to a type of collection; • Model: Student, Collection: Gym Class • Model: Student, Collection: Art Class • Model: Student, Collection: English Class Here is a generic Model/Collection example. 1 var Song = Backbone.Model.extend({ 2 initialize: function(){ 3 console.log("Music is the answer"); 4 } 5 }); 6 7 var Album = Backbone.Collection.extend({ 8 model: Song 9 }); Building a collection Now we are going to populate a creation with some useful data. 1 var Song = Backbone.Model.extend({ 2 defaults: { 3 name: "Not specified", 4 artist: "Not specified" 5 }, 6 initialize: function(){ 7 console.log("Music is the answer"); 8 } 9 }); 10 11 var Album = Backbone.Collection.extend({ ¹⁹http://backbonetutorials.com/what-is-a-model xi
- 18. What is a collection? xii 12 model: Song 13 }); 14 15 var song1 = new Song({ name: "How Bizarre", artist: "OMC" }); 16 var song2 = new Song({ name: "Sexual Healing", artist: "Marvin Gaye" }) 17 ; 18 var song3 = new Song({ name: "Talk It Over In Bed", artist: "OMC" }); 19 20 var myAlbum = new Album([ song1, song2, song3]); 21 console.log( myAlbum.models ); // [song1, song2, song3]
- 19. What is a router? Backbone routers are used for routing your applications URL’s when using hash tags(#). In the traditional MVC sense they don’t neccesarily fit the semantics and if you have read “What is a view?²⁰” it will elaborate on this point. Though a Backbone “router” is still very useful for any application/feature that needs URL routing/history capabilities. Defined routers should always contain at least one route and a function to map the particular route to. In the example below we are going to define a route that is always called. Also note that routes intepret anything after “#” tag in the url. All links in your application should target “#/action” or “#action”. (Appending a forward slash after the hashtag looks a bit nicer e.g. http://example.com/#/user/help) 1 <script> 2 var AppRouter = Backbone.Router.extend({ 3 routes: { 4 "*actions": "defaultRoute" // matches http://example.com/#anyth 5 ing-here 6 }, 7 defaultRoute: function( actions ){ 8 // The variable passed in matches the variable in the route def 9 inition "actions" 10 alert( actions ); 11 } 12 }); 13 // Initiate the router 14 var app_router = new AppRouter; 15 // Start Backbone history a neccesary step for bookmarkable URL's 16 Backbone.history.start(); 17 18 </script> 19 20 [Activate route](#action) 21 22 [Activate another route](#/route/action) 23 24 _Notice the change in the url_ Please note: Prior to Backbone 0.5 (released 1. July 2011) a Router was called a Controller. To avoid confusion, the Backbone developers changed the name to Router. Hence, if you find yourself using an older version of Backbone you should write Backbone.Controller.extend({ ** }); Dynamic Routing Most conventional frameworks allow you to define routes that contain a mix of static and dynamic route parameters. For example you might want to retrieve a post with a variable id with a friendly URL string. ²⁰http://backbonetutorials.com/what-is-a-view xiii
- 20. What is a router? xiv Such that your URL would look like “http://example.com/#/posts/12”. Once this route was activated you would want to access the id given in the URL string. This example is implemented below. 1 <script> 2 var AppRouter = Backbone.Router.extend({ 3 routes: { 4 "/posts/:id": "getPost", 5 "*actions": "defaultRoute" // Backbone will try match the route 6 above first 7 }, 8 getPost: function( id ) { 9 // Note the variable in the route definition being passed in he 10 re 11 alert( "Get post number " + id ); 12 }, 13 defaultRoute: function( actions ){ 14 alert( actions ); 15 } 16 }); 17 // Instantiate the router 18 var app_router = new AppRouter; 19 // Start Backbone history a neccesary step for bookmarkable URL's 20 Backbone.history.start(); 21 22 </script> 23 24 [Post 120](#/posts/120) 25 26 [Post 130](#/posts/130) 27 28 _Notice the change in the url_ Dynamic Routing Cont. “:params” and “*splats” Backbone uses two styles of variables when implementing routes. First there are “:params” which match any URL components between slashes. Then there are “_splats” which match any number of URL components. Note that due to the nature of a “_splat” it will always be the last variable in your URL as it will match any and all components. Any “*splats” or “:params” in route definitions are passed as arguments (in respective order) to the associated function. A route defined as “/:route/:action” will pass 2 variables (“route” and “action”) to the callback function. (If this is confusing please post a comment and I will try articulate it better) Here are some examples of using “:params” and “*splats” 1 routes: { 2 3 "/posts/:id": "getPost", 4 // <a href="http://example.com/#/posts/121">Example</a>
- 21. What is a router? xv 5 6 "/download/*path": "downloadFile", 7 // <a href="http://example.com/#/download/user/images/hey.gif"> 8 Download</a> 9 10 "/:route/:action": "loadView", 11 // <a href="http://example.com/#/dashboard/graph">Load Route/Ac 12 tion View</a> 13 14 }, 15 16 getPost: function( id ){ 17 alert(id); // 121 18 }, 19 downloadFile: function( path ){ 20 alert(path); // user/images/hey.gif 21 }, 22 loadView: function( route, action ){ 23 alert(route + "_" + action); // dashboard_graph 24 } Routes are quite powerful and in an ideal world your application should never contain too many. If you need to implement hash tags with SEO in mind, do a google search for “google seo hashbangs”. Remember to do a pull request for any errors you come across. Relevant Links • Backbone.js official router documentation²¹ • Using routes and understanding the hash tag²² Contributors • Herman Schistad²³ - (Backbone 0.5 rename from Controller to Router) • Paul Irish²⁴ ²¹http://documentcloud.github.com/backbone/#Router ²²http://thomasdavis.github.com/2011/02/07/making-a-restful-ajax-app.html ²³http://schistad.info ²⁴http://paulirish.com
- 22. Organizing your application using Modules (require.js) Unfortunately Backbone.js does not tell you how to organize your code, leaving many developers in the dark regarding how to load scripts and lay out their development enviroments. This was quite a different decision to other Javascript MVC frameworks who were more in favor of setting a development philosophy. Hopefully this tutorial will allow you to build a much more robust project with great separation of concerns between design and code. This tutorial will get you started on combining Backbone.js with AMD²⁵ (Asynchronous Module Definitions). What is AMD? Asynchronous Module Definitions²⁶ designed to load modular code asynchronously in the browser and server. It is actually a fork of the Common.js specification. Many script loaders have built their implementations around AMD, seeing it as the future of modular Javascript development. This tutorial will use Require.js²⁷ to implement a modular and organized Backbone.js. I highly recommend using AMD for application development Quick Overview • Modular • Scalable • Compiles well(see r.js²⁸ ) • Market Adoption( Dojo 1.6 converted fully to AMD²⁹ ) Why Require.js? a. Require.js has a great community and it is growing rapidly. James Burke³⁰ the author is married to Require.js and responds to user feedback always. A leading expert in script loading, he is also a contributer to the AMD specification. Follow @jrburke³¹ ²⁵https://github.com/amdjs/amdjs-api/wiki/AMD ²⁶https://github.com/amdjs/amdjs-api/wiki/AMD ²⁷http://requirejs.org ²⁸http://requirejs.org/docs/optimization.html ²⁹http://dojotoolkit.org/reference-guide/releasenotes/1.6.html ³⁰http://tagneto.blogspot.com/ ³¹https://twitter.com/jrburke xvi
- 23. Organizing your application using Modules (require.js) xvii Getting started To easily understand this tutorial you should jump straight into the example code base. Example Codebase³² Example Demo³³ The tutorial is only loosely coupled with the example and you will find the example to be more comprehensive. If you would like to see how a particuliar use case would be implemented please visit the Github page and create an issue.(Example Request: How to do nested views). The example isn’t super fleshed out but should give you a vague idea. Example File Structure There are many different ways to lay out your files and I believe it is actually dependent on the size and type of the project. In the example below views and templates are mirroed in file structure. Collections and Models aren’t categorized into folders kind of like an ORM. 1 /* File Structure 2 ├── imgs 3 ├── css 4 │ └── style.css 5 ├── templates 6 │ ├── projects 7 │ │ ├── list.html 8 │ │ └── edit.html 9 │ └── users 10 │ ├── list.html 11 │ └── edit.html 12 ├── js 13 │ ├── libs 14 │ │ ├── jquery 15 │ │ │ ├── jquery.min.js 16 │ │ │ └── jquery.js // jQuery Library Wrapper 17 │ │ ├── backbone 18 │ │ │ ├── backbone.min.js 19 │ │ │ └── backbone.js // Backbone Library Wrapper 20 │ │ └── underscore 21 │ │ │ ├── underscore.min.js 22 │ │ │ └── underscore.js // Underscore Library Wrapper 23 │ ├── models 24 │ │ ├── users.js 25 │ │ └── projects.js 26 │ ├── collections ³²https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/modular-backbone ³³http://backbonetutorials.com/examples/modular-backbone
- 24. Organizing your application using Modules (require.js) xviii 27 │ │ ├── users.js 28 │ │ └── projects.js 29 │ ├── views 30 │ │ ├── projects 31 │ │ │ ├── list.js 32 │ │ │ └── edit.js 33 │ │ └── users 34 │ │ ├── list.js 35 │ │ └── edit.js 36 │ ├── router.js 37 │ ├── app.js 38 │ ├── main.js // Bootstrap 39 │ ├── order.js //Require.js plugin 40 │ └── text.js //Require.js plugin 41 └── index.html 42 43 */ To continue you must really understand what we are aiming towards as described in the introduction. Bootstrapping your application Using Require.js we define a single entry point on our index page. We should setup any useful containers that might be used by our Backbone views. Note: The data-main attribute on our single script tag tells Require.js to load the script located at “js/main.js”. It automatically appends the “.js” 1 <!doctype html> 2 <html lang="en"> 3 <head> 4 <title>Jackie Chan</title> 5 <!-- Load the script "js/main.js" as our entry point --> 6 <script data-main="js/main" src="js/libs/require/require.js"></script> 7 </head> 8 <body> 9 10 <div id="container"> 11 <div id="menu"></div> 12 <div id="content"></div> 13 </div> 14 15 </body> 16 </html> You should most always end up with quite a light weight index file. You can serve this off your server and then the rest of your site off a CDN ensuring that everything that can be cached, will be.
- 25. Organizing your application using Modules (require.js) xix What does the bootstrap look like? Our bootstrap file will be responsible for configuring Require.js and loading initially important depen- dencies. In the below example we configure Require.js to create shortcut alias to commonly used scripts such as jQuery, Underscore and Backbone. Due to the nature of these libraries implementations we actually have to load them in order because they each depend on each other existing in the global namespace(which is bad but is all we have to work with). Hopefully if the AMD specification takes off these libraries will add code to allow themselves to be loaded asynchronously. Due to this inconvience the bootstrap is not as intuitive as it could be, I hope to solve this problem in the near future. We also request a module called “app”, this will contain the entireity of our application logic. Note: Modules are loaded relativly to the boot strap and always append with “.js”. So the module “app” will load “app.js” which is in the same directory as the bootstrap. 1 // Filename: main.js 2 3 // Require.js allows us to configure shortcut alias 4 // There usage will become more apparent futher along in the tutorial. 5 require.config({ 6 paths: { 7 jQuery: 'libs/jquery/jquery', 8 Underscore: 'libs/underscore/underscore', 9 Backbone: 'libs/backbone/backbone' 10 } 11 12 }); 13 14 require([ 15 16 // Load our app module and pass it to our definition function 17 'app', 18 19 // Some plugins have to be loaded in order due to there non AMD complianc 20 e 21 // Because these scripts are not "modules" they do not pass any values to 22 the definition function below 23 'order!libs/jquery/jquery-min', 24 'order!libs/underscore/underscore-min', 25 'order!libs/backbone/backbone-min' 26 ], function(App){ 27 // The "app" dependency is passed in as "App" 28 // Again, the other dependencies passed in are not "AMD" therefore don't 29 pass a parameter to this function 30 App.initialize(); 31 });
- 26. Organizing your application using Modules (require.js) xx How should we lay out external scripts? Any modules we develop for our application using AMD/Require.js will be asynchronously loaded. We have a heavy dependency on jQuery, Underscore and Backbone, unfortunatly this libraries are loaded synchronously and also depend on each other existing in the global namespace. Below I propose a solution(until these libraries allow themselves to be loaded asynchronously) to allow these libraries to be loaded properly(synchronously) and also removing themselves from global scope. 1 // Filename: libs/jquery/jquery.js 2 3 define([ 4 // Load the original jQuery source file 5 'order!libs/jquery/jquery-min' 6 ], function(){ 7 // Tell Require.js that this module returns a reference to jQuery 8 return $; 9 }); 10 11 12 // Filename: libs/underscore/underscore 13 // As above lets load the original underscore source code 14 define(['order!libs/underscore/underscore-min'], function(){ 15 // Tell Require.js that this module returns a reference to Underscore 16 return _; 17 }); 18 19 20 // Filename: libs/backbone/backbone 21 // Finally lets load the original backbone source code 22 define(['order!libs/backbone/backbone-min'], function(){ 23 // Now that all the orignal source codes have ran and accessed each other 24 // We can call noConflict() to remove them from the global name space 25 // Require.js will keep a reference to them so we can use them in our mod 26 ules 27 _.noConflict(); 28 $.noConflict(); 29 return Backbone.noConflict(); 30 }); A boiler plate module So before we start developing our application, let’s quickly look over boiler plate code that will be reused quite often. For convience sake I generally keep a “boilerplate.js” in my application root so I can copy it when I need to.
- 27. Organizing your application using Modules (require.js) xxi 1 //Filename: boilerplate.js 2 3 define([ 4 // These are path alias that we configured in our bootstrap 5 'jQuery', // lib/jquery/jquery 6 'Underscore', // lib/underscore/underscore 7 'Backbone' // lib/backbone/backbone 8 ], function($, _, Backbone){ 9 // Above we have passed in jQuery, Underscore and Backbone 10 // They will not be accesible in the global scope 11 return {}; 12 // What we return here will be used by other modules 13 }); The first argument of the define function is our dependency array, we can pass in any modules we like in the future. App.js Building our applications main module Our applications main module should always remain quite light weight. This tutorial covers only setting up a Backbone Router and initializing it in our main module. The router will then load the correct dependencies depending on the current URL. 1 // Filename: app.js 2 define([ 3 'jQuery', 4 'Underscore', 5 'Backbone', 6 'router', // Request router.js 7 ], function($, _, Backbone, Router){ 8 var initialize = function(){ 9 // Pass in our Router module and call it's initialize function 10 Router.initialize(); 11 } 12 13 return { 14 initialize: initialize 15 }; 16 }); 17 18 19 // Filename: router.js 20 define([ 21 'jQuery', 22 'Underscore', 23 'Backbone', 24 'views/projects/list',
- 28. Organizing your application using Modules (require.js) xxii 25 'views/users/list' 26 ], function($, _, Backbone, Session, projectListView, userListView){ 27 var AppRouter = Backbone.Router.extend({ 28 routes: { 29 // Define some URL routes 30 '/projects': 'showProjects', 31 '/users': 'showUsers', 32 33 // Default 34 '*actions": "defaultAction' 35 }, 36 showProjects: function(){ 37 // Call render on the module we loaded in via the dependency array 38 // 'views/projects/list' 39 projectListView.render(); 40 }, 41 // As above, call render on our loaded module 42 // 'views/users/list' 43 showUsers: function(){ 44 userListView.render(); 45 }, 46 defaultAction: function(actions){ 47 // We have no matching route, lets just log what the URL was 48 console.log('No route:', actions); 49 } 50 }); 51 52 var initialize = function(){ 53 var app_router = new AppRouter; 54 Backbone.history.start(); 55 }; 56 return { 57 initialize: initialize 58 }; 59 }); Modularizing a Backbone View Backbone views most usually always interact with the DOM, using our new modular system we can load in Javascript templates using Require.js text! plugin. 1 // Filename: views/project/list 2 define([ 3 'jQuery', 4 'Underscore', 5 'Backbone', 6 // Using the Require.js text! plugin, we are loaded raw text 7 // which will be used as our views primary template
- 29. Organizing your application using Modules (require.js) xxiii 8 'text!templates/project/list.html' 9 ], function($, _, Backbone, projectListTemplate){ 10 var projectListView = Backbone.View.extend({ 11 el: $('#container'), 12 render: function(){ 13 // Using Underscore we can compile our template with data 14 var data = {}; 15 var compiledTemplate = _.template( projectListTemplate, data ); 16 // Append our compiled template to this Views "el" 17 this.el.append( compiledTemplate ); 18 } 19 }); 20 // Our module now returns an instantiated view 21 // Sometimes you might return an un-instantiated view e.g. return project 22 ListView 23 return new projectListView; 24 }); Javascript templating allows us to seperate the design from the application logic placing all our html in the templates folder. Modularizing a Collection, Model and View Now we put it altogether by chaining up a Model, Collection and View which is a typical scenairo when building a Backbone.js application. First off we will define our model 1 // Filename: models/project 2 define([ 3 'Underscore', 4 'Backbone' 5 ], function(_, Backbone){ 6 var projectModel = Backbone.Model.extend({ 7 defaults: { 8 name: "Harry Potter" 9 } 10 }); 11 // You usually don't return a model instantiated 12 return projectModel; 13 }); Now we have a model, our collection module can depend on it. We will set the “model” attribute of our collection to the loaded module. Backbone.js offers great benefits when doing this. Collection.model: Override this property to specify the model class that the collection contains. If defined, you can pass raw attributes objects (and arrays) to add, create, and reset, and the attributes will be converted into a model of the proper type.
- 30. Organizing your application using Modules (require.js) xxiv 1 // Filename: collections/projects 2 define([ 3 'Underscore', 4 'Backbone', 5 // Pull in the Model module from above 6 'models/project' 7 ], function(_, Backbone, projectModel){ 8 var projectCollection = Backbone.Collection.extend({ 9 model: projectModel 10 }); 11 // You don't usually return a collection instantiated 12 return new projectCollection; 13 }); Now we can simply depend on our collection in our view and pass it to our Javascript template. 1 // Filename: views/projects/list 2 define([ 3 'jQuery', 4 'Underscore', 5 'Backbone', 6 // Pull in the Collection module from above 7 'collections/projects', 8 'text!templates/projects/list 9 ], function(_, Backbone, projectsCollection, projectsListTemplate){ 10 var projectListView = Backbone.View.extend({ 11 el: $("#container"), 12 initialize: function(){ 13 this.collection = new projectsCollection; 14 this.collection.add({ name: "Ginger Kid"}); 15 // Compile the template using Underscores micro-templating 16 var compiledTemplate = _.template( projectsListTemplate, { projects: 17 this.collection.models } ); 18 this.el.html(compiledTemplate); 19 } 20 }); 21 // Returning instantiated views can be quite useful for having "state" 22 return new projectListView; 23 }); Conclusion Looking forward to feedback so I can turn this post and example into quality references on building modular Javascript applications. Get in touch with me on twitter, comments or github!
- 31. Organizing your application using Modules (require.js) xxv Relevant Links • Organizing Your Backbone.js Application With Modules³⁴ Contributors • Jakub Kozisek³⁵ (created modular-backbone-updated containing updated libs with AMD support) ³⁴http://weblog.bocoup.com/organizing-your-backbone-js-application-with-modules ³⁵https://github.com/dzejkej
- 32. Lightweight Infinite Scrolling using Twitter API Getting started In this example we are going to build a widget that pulls in tweets and when the user scrolls to the bottom of the widget Backbone.js will resync with the server to bring down the next page of results. Example Demo³⁶ Example Source³⁷ Note: This tutorial will use AMD³⁸ for modularity. The Twitter Collection Twitter offers a jsonp API for browsing tweets. The first thing to note is that we have to append ‘&callback?’ to allow cross domain ajax calls which is a feature of jsonp³⁹. Using the ‘q’ and ‘page’ query parameters we can find the results we are after. In the collection definition below we have set some defaults which can be overridden at any point. Twitter’s search API actually returns a whole bunch of meta information alongside the results. Though this is a problem for Backbone.js because a Collection expects to be populated with an array of objects. So in our collection definition we can override the Backbone.js default parse function to instead choose the correct property to populate the collection. 1 // collections/twitter.js 2 define([ 3 'jquery', 4 'underscore', 5 'backbone' 6 ], function($, _, Backbone){ 7 var Tweets = Backbone.Collection.extend({ 8 url: function () { 9 return 'http://search.twitter.com/search.json?q=' + this.query + '&pa 10 ge=' + this.page + '&callback=?' 11 }, 12 // Because twitter doesn't return an array of models by default we need 13 // to point Backbone.js at the correct property 14 parse: function(resp, xhr) { 15 return resp.results; 16 }, 17 page: 1, 18 query: 'backbone.js tutorials' ³⁶http://backbonetutorials.com/examples/infinite-scroll/ ³⁷https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/infinite-scroll ³⁸http://backbonetutorials.com/organizing-backbone-using-modules ³⁹http://en.wikipedia.org/wiki/JSONP xxvi
- 33. Lightweight Infinite Scrolling using Twitter API xxvii 19 }); 20 21 return Tweets; 22 }); Note: Feel free to attach the meta information returned by Twitter to the collection itself e.g. 1 parse: function(resp, xhr) { 2 this.completed_in = resp.completed_in 3 return resp.results; 4 }, Setting up the View The first thing to do is load our Twitter collection and template into the widget module. We should attach our collection to our view in our initialize function. loadResults will be responsible for calling fetch on our Twitter collection. On success we will append the latest results to our widget using our template. Our Backbone.js events will listen for scroll on the current el of the view which is ‘.twitter-widget’. If the current scrollTop is at the bottom then we simply increment the Twitter collections current page property and call loadResults again. 1 // views/twitter/widget.js 2 define([ 3 'jquery', 4 'underscore', 5 'backbone', 6 'vm', 7 'collections/twitter', 8 'text!templates/twitter/list.html' 9 ], function($, _, Backbone, Vm, TwitterCollection, TwitterListTemplate){ 10 var TwitterWidget = Backbone.View.extend({ 11 el: '.twitter-widget', 12 initialize: function () { 13 // isLoading is a useful flag to make sure we don't send off more tha 14 n 15 // one request at a time 16 this.isLoading = false; 17 this.twitterCollection = new TwitterCollection(); 18 }, 19 render: function () { 20 this.loadResults(); 21 }, 22 loadResults: function () { 23 var that = this; 24 // we are starting a new load of results so set isLoading to true 25 this.isLoading = true; 26 // fetch is Backbone.js native function for calling and parsing the c 27 ollection url
- 34. Lightweight Infinite Scrolling using Twitter API xxviii 28 this.twitterCollection.fetch({ 29 success: function (tweets) { 30 // Once the results are returned lets populate our template 31 $(that.el).append(_.template(TwitterListTemplate, {tweets: tweets 32 .models, _:_})); 33 // Now we have finished loading set isLoading back to false 34 that.isLoading = false; 35 } 36 }); 37 }, 38 // This will simply listen for scroll events on the current el 39 events: { 40 'scroll': 'checkScroll' 41 }, 42 checkScroll: function () { 43 var triggerPoint = 100; // 100px from the bottom 44 if( !this.isLoading && this.el.scrollTop + this.el.clientHeight + t 45 riggerPoint > this.el.scrollHeight ) { 46 this.twitterCollection.page += 1; // Load next page 47 this.loadResults(); 48 } 49 } 50 }); 51 return TwitterWidget; 52 }); Note: triggerPoint will allow you to set an offset where the user has to scroll to before loading the next page The widget template Our view above passes into our underscore template the variable tweets which we can simply iterate over with using underscore’s each method. 1 <!-- templates/twitter/list.html --> 2 <ul class="tweets"> 3 <% _.each(tweets, function (tweet) { %> 4 5 <li><%= tweet.get('text') %></li> 6 7 <% }); %> 8 </ul> Conclusion This is a very light weight but robust infinite scroll example. There are caveats to using infinite scroll in UI/UX so make sure to use it only when applicable.
- 35. Lightweight Infinite Scrolling using Twitter API xxix Example Demo⁴⁰ Example Source⁴¹ ⁴⁰http://backbonetutorials.com/examples/infinite-scroll/ ⁴¹https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/infinite-scroll
- 36. Simple example - Node.js, Restify, MongoDb and Mongoose Before I start, the Backbone.js parts of this tutorial will be using techniques described in “Organizing your application using Modules⁴² to construct a simple guestbook. Getting started To easily understand this tutorial you should jump straight into the example code base. Example Codebase⁴³ Example Demo⁴⁴ This tutorial will assist you in saving data(Backbone.js Models) to MongoDb and retrieving a list(Backbone.js Collections) of them back. The technologies This stack is great for rapid prototyping and highly intuitive. Personal note: I love using Javascript as my only language for the entire application(FrontEnd/BackEnd/API/Database). Restify is still in early development but is essentially just an extension of Express. So for anyone needing more stability you can easily just substitute Express in. Node.js “Node.js is a platform built on Chrome’s JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices.” Restify “Restify is a node.js module built specifically to enable you to build correct REST web services. It borrows heavily from express (intentionally) as that is more or less the de facto API for writing web applications on top of node.js.” MongoDb “MongoDB (from “humongous”) is a scalable, high-performance, open source NoSQL database.” Mongoose “Mongoose is a MongoDB object modeling tool designed to work in an asynchronous environment.” ⁴²http://backbonetutorials.com/organizing-backbone-using-modules/ ⁴³https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/nodejs-mongodb-mongoose-restify ⁴⁴http://backbonetutorials.com/examples/nodejs-mongodb-mongoose-restify/ xxx
- 37. Simple example - Node.js, Restify, MongoDb and Mongoose xxxi Building the server In the example repository there is a server.js example which can be executed by running node server.js. If you use this example in your own applications make sure to update the Backbone.js Model⁴⁵ and Collection⁴⁶ definitions to match your server address. Restify configuration The first thing to do is require the Restify module. Restify will be in control of handling our restFul end points and returning the appropriate JSON. 1 var restify = require('restify'); 2 var server = restify.createServer(); 3 server.use(restify.bodyParser()); Note: bodyParser() takes care of turning your request data into a Javascript object on the server automatically. MongoDb/Mongoose configuration We simply want to require the MongoDb module and pass it a MongoDb authentication URI e.g. mongodb://username:server@mongoserver:10059/somecollection The code below presupposes you have another file in the same directory called config.js. Your config should never be public as it contains your credentials. So for this repository I have added config.js to my .gitignore but added in a sample config⁴⁷. 1 var mongoose = require('mongoose/'); 2 var config = require('./config'); 3 db = mongoose.connect(config.creds.mongoose_auth), 4 Schema = mongoose.Schema; Mongoose Schema Mongoose introduces a concept of model/schema⁴⁸ enforcing types which allow for easier input validation etc 1 // Create a schema for our data 2 var MessageSchema = new Schema({ 3 message: String, 4 date: Date ⁴⁵https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/js/models/message.js ⁴⁶https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/js/collections/messages. js ⁴⁷https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/config-sample.js ⁴⁸http://mongoosejs.com/docs/model-definition.html
- 38. Simple example - Node.js, Restify, MongoDb and Mongoose xxxii 5 }); 6 // Use the schema to register a model with MongoDb 7 mongoose.model('Message', MessageSchema); 8 var Message = mongoose.model('Message'); Note: Message can now be used for all things CRUD related. Setting up the routes Just like in Backbone, Restify allows you to configure different routes and their associated callbacks. In the code below we want to define two routes. One for saving new messages and one for retrieving all messages. After we have created our function definitions, we then attach them to either GET/- POST/PUT/DELETE on a particular restful endpoint e.g. GET /messages 1 // This function is responsible for returning all entries for the Message m 2 odel 3 function getMessages(req, res, next) { 4 // Resitify currently has a bug which doesn't allow you to set default he 5 aders 6 // This headers comply with CORS and allow us to server our response to a 7 ny origin 8 res.header("Access-Control-Allow-Origin", "*"); 9 res.header("Access-Control-Allow-Headers", "X-Requested-With"); 10 // .find() without any arguments, will return all results 11 // the `-1` in .sort() means descending order 12 Message.find().sort('date', -1).execFind(function (arr,data) { 13 res.send(data); 14 }); 15 } 16 17 18 19 function postMessage(req, res, next) { 20 res.header("Access-Control-Allow-Origin", "*"); 21 res.header("Access-Control-Allow-Headers", "X-Requested-With"); 22 // Create a new message model, fill it up and save it to Mongodb 23 var message = new Message(); 24 message.message = req.params.message; 25 message.date = new Date() 26 message.save(function () { 27 res.send(req.body); 28 }); 29 } 30 31 // Set up our routes and start the server 32 server.get('/messages', getMessages); 33 server.post('/messages', postMessage);
- 39. Simple example - Node.js, Restify, MongoDb and Mongoose xxxiii This wraps up the server side of things, if you follow the example⁴⁹ then you should see something like http://backbonetutorials.nodejitsu.com/messages⁵⁰ Note: Again you must remember to change the Model⁵¹ and Collection⁵² definitions to match your server address. Setting up the client(Backbone.js) I’ve actually used the latest copy of http://backboneboilerplate.com⁵³ to set up the example page. The important files you will want to check out are; • views/dashboard/page.js • views/guestbook/form.js • views/guestbook/list.js • models/message.js • collections/messages.js • templates/guestbook/ Saving a message First of all we want to setup a template⁵⁴ for showing our form that creates new messages. 1 <textarea class="message"></textarea> 2 <button class="post-message">Post Message</button> This template gets inserted into the DOM by views/guestbook/form.js, this Backbone view also handles the interaction of the form and the posting of the new data. Let us create a Backbone Model that has the correct url for our restFul interface. 1 define([ 2 'underscore', 3 'backbone' 4 ], function(_, Backbone) { 5 var Message = Backbone.Model.extend({ 6 url: 'http://localhost:8080/messages' 7 }); 8 return Message; 9 }); ⁴⁹https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/server.js ⁵⁰http://backbonetutorials.nodejitsu.com/messages ⁵¹https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/js/models/message.js ⁵²https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/js/collections/messages. js ⁵³http://backboneboilerplate.com ⁵⁴https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/nodejs-mongodb-mongoose-restify/templates/guestbook/ form.html
- 40. Simple example - Node.js, Restify, MongoDb and Mongoose xxxiv We can see how we require our pre-defined model for messages and also our form template. 1 define([ 2 'jquery', 3 'underscore', 4 'backbone', 5 'models/message', 6 'text!templates/guestbook/form.html' 7 ], function($, _, Backbone, MessageModel, guestbookFormTemplate){ 8 var GuestbookForm = Backbone.View.extend({ 9 el: '.guestbook-form-container', 10 render: function () { 11 $(this.el).html(guestbookFormTemplate); 12 13 }, 14 events: { 15 'click .post-message': 'postMessage' 16 }, 17 postMessage: function() { 18 var that = this; 19 20 var message = new MessageModel(); 21 message.save({ message: $('.message').val()}, { 22 success: function () { 23 that.trigger('postMessage'); 24 } 25 }); 26 } 27 }); 28 return GuestbookForm; 29 }); Note: trigger is from Backbone Events, I binded a listener to this view in views/dashboard/page.js so that when a new message is submitted, the list is re-rendered. We are setting the date of post on the server so there is no need to pass it up now. Retrieving a list of messages We setup a route on our server to generate a list of all available messages at GET /messages. So we need to define a collection with the appropriate url to fetch this data down. 1 define([ 2 'jquery', 3 'underscore', 4 'backbone', 5 'models/message' 6 ], function($, _, Backbone, MessageModel){ 7 var Messages = Backbone.Collection.extend({
- 41. Simple example - Node.js, Restify, MongoDb and Mongoose xxxv 8 model: MessageModel, // Generally best practise to bring down a Model/S 9 chema for your collection 10 url: 'http://localhost:8080/messages' 11 }); 12 13 return Messages; 14 }); Now that we have a collection to use we can setup our views/list.js to require the collection and trigger a fetch. Once the fetch is complete we want to render our returned data to a template and insert it into the DOM. 1 define([ 2 'jquery', 3 'underscore', 4 'backbone', 5 'collections/messages', 6 'text!templates/guestbook/list.html' 7 ], function($, _, Backbone, MessagesCollection, guestbookListTemplate){ 8 var GuestbookList = Backbone.View.extend({ 9 el: '.guestbook-list-container', 10 render: function () { 11 var that = this; 12 var messages = new MessagesCollection(); 13 messages.fetch({ 14 success: function(messages) { 15 $(that.el).html(_.template(guestbookListTemplate, {messages: mess 16 ages.models, _:_})); 17 } 18 }); 19 } 20 }); 21 return GuestbookList; 22 }); The template file should iterate over messages.models which is an array and print out a HTML fragment for each model. 1 <% _.each(messages, function(message) { %> 2 3 <p><%= message.get('message') %></p> 4 <em><%= message.get('date') %></em> 5 6 <% }); %> This actually sums up everything you need to know to implement this simple example.
- 42. Simple example - Node.js, Restify, MongoDb and Mongoose xxxvi Conclusion Example Codebase⁵⁵ Example Demo⁵⁶ In this example you should really be using relative url’s in your collections/models and instead setting a baseUrl in a config file or by placing your index.html file on the restful server. This example is hosted on github therefore we had to include the absolute url to the server which is hosted on nodejitsu.com On a personal note, I have of recent used the Joyent, Nodejitsu, MongoDbHq stack after they have now partnered up and I have nothing but good things to say. Highly recommend you check it out! As always I hope I made this tutorial easy to follow! Get in touch with me on twitter, comments or github! Relevant Links Organizing Your Backbone.js Application With Modules⁵⁷ ⁵⁵https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/nodejs-mongodb-mongoose-restify ⁵⁶http://backbonetutorials.com/examples/nodejs-mongodb-mongoose-restify/ ⁵⁷http://weblog.bocoup.com/organizing-your-backbone-js-application-with-modules
- 43. Cross-domain Backbone.js with sessions using CORS This tutorial is a proof of concept and needs to be checked for security flawss This tutorial will teach you how to completely separate the server and client allowing for developers to work with freedom in their respective areas. On a personal note, I consider this development practise highly desirable and encourage others to think of the possible benefits but the security still needs to be prooved. Cross-Origin Resource Sharing (CORS) is a specification that enables a truly open access across domain-boundaries. - enable-cors.org⁵⁸ Some benefits include • The client and back end exist independently regardless of where they are each hosted and built • Due to the separation of concerns, testing now becomes easier and more controlled. • Develop only one API on the server, your front-end could be outsourced or built by a inhouse team. • As a front-end developer you can host the client anywhere • This separation enforces that the API be built robustly, documented, collaborativly and versioned. Cons of this tutorial • This tutorial doesn’t explain how to perform this with cross browser support. CORS headers aren’t supported by Opera and Ie 6/7. Though it is do-able using easyXDM⁵⁹ • Security is somewhat addressed but maybe a more thorough security expert can chime in. Security • Don’t allow GET request to change data, only retrieve • Whitelist your allowed domains (see server.js⁶⁰ • Protect again JSON padding⁶¹ ⁵⁸http://enable-cors.org/ ⁵⁹http://easyxdm.net/wp/ ⁶⁰https://github.com/thomasdavis/backbonetutorials/blob/gh-pages/examples/cross-domain/server.js ⁶¹http://blog.opensecurityresearch.com/2012/02/json-csrf-with-parameter-padding.html xxxvii
- 44. Cross-domain Backbone.js with sessions using CORS xxxviii Getting started To easily understand this tutorial you should jump straight into the example code base. Host the codebase on a simple http server such that the domain is localhost with port 80 hidden. Example Codebase⁶² Example Demo⁶³ This tutorial focuses on building a flexible Session model to control session state in your application. Checking session state at first load Before starting any routes, we should really know if the user is authed or not. This will allow us to load the appropiate views. We will simply wrap our Backbone.history.start in a callback that executes after Session.getAuth has checked the server. We will jump into our Session model next. 1 define([ 2 'jquery', 3 'underscore', 4 'backbone', 5 'vm', 6 'events', 7 'models/session', 8 'text!templates/layout.html' 9 ], function($, _, Backbone, Vm, Events, Session, layoutTemplate){ 10 var AppView = Backbone.View.extend({ 11 el: '.container', 12 initialize: function () { 13 $.ajaxPrefilter( function( options, originalOptions, jqXHR ) { 14 // Your server goes below 15 //options.url = 'http://localhost:8000' + options.url; 16 options.url = 'http://cross-domain.nodejitsu.com' + options.url; 17 }); 18 19 }, 20 render: function () { 21 var that = this; 22 $(this.el).html(layoutTemplate); 23 // This is the entry point to your app, therefore 24 // when the user refreshes the page we should 25 // really know if they're authed. We will give it 26 // A call back when we know what the auth status is 27 Session.getAuth(function () { 28 Backbone.history.start(); 29 }) 30 } ⁶²https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/cross-domain ⁶³http://backbonetutorials.com/examples/cross-domain/
- 45. Cross-domain Backbone.js with sessions using CORS xxxix 31 }); 32 return AppView; 33 }); Note: We have used jQuery ajaxPrefilter to hook into all AJAX requests before they are executed. This is where we specify what server we want the application to hit. An example Session model This is a very light weight Session model which handles most situations. Read through the code and comments below. The model simply has a login, logout and check function. Again we have hooked into jQuery ajaxPrefilter to allow for csrf tokens and also telling jQuery to send cookies with the withCredentials property. The model relies heavily on it’s auth property. Throughout your application, each view can simply bind to change:auth on the Session model and react accordingly. Because we return this AMD module instantiated using the new keyword, then it will keep state throughout the page. (This may not be best practise but it’s highly convenient) 1 // views/app.js 2 define([ 3 'underscore', 4 'backbone' 5 ], function(_, Backbone) { 6 var SessionModel = Backbone.Model.extend({ 7 8 urlRoot: '/session', 9 initialize: function () { 10 var that = this; 11 // Hook into jquery 12 // Use withCredentials to send the server cookies 13 // The server must allow this through response headers 14 $.ajaxPrefilter( function( options, originalOptions, jqXHR ) { 15 options.xhrFields = { 16 withCredentials: true 17 }; 18 // If we have a csrf token send it through with the next request 19 if(typeof that.get('_csrf') !== 'undefined') { 20 jqXHR.setRequestHeader('X-CSRF-Token', that.get('_csrf')); 21 } 22 }); 23 }, 24 login: function(creds) { 25 // Do a POST to /session and send the serialized form creds 26 this.save(creds, { 27 success: function () {} 28 }); 29 }, 30 logout: function() { 31 // Do a DELETE to /session and clear the clientside data
- 46. Cross-domain Backbone.js with sessions using CORS xl 32 var that = this; 33 this.destroy({ 34 success: function (model, resp) { 35 model.clear() 36 model.id = null; 37 // Set auth to false to trigger a change:auth event 38 // The server also returns a new csrf token so that 39 // the user can relogin without refreshing the page 40 that.set({auth: false, _csrf: resp._csrf}); 41 42 } 43 }); 44 }, 45 getAuth: function(callback) { 46 // getAuth is wrapped around our router 47 // before we start any routers let us see if the user is valid 48 this.fetch({ 49 success: callback 50 }); 51 } 52 }); 53 return new SessionModel(); 54 55 }); Note: This session model is missing one useful feature. If a user looses auth when navigating your application then the application should set {auth: false} on this model. To do this, in the ajaxPrefilter edit outgoing success functions to check if the server response was {auth: false} and then call the original success() function. Hooking up views to listen to changes in auth Now that we have a Session model, let’s hook up our login/logout view to listen to changes in auth. When creating the view we use on to bind a listener to the auth attribute of our model. Everytime is changes we will re-render the view which will conditionally load a template depending on the value of Session.get('auth'). 1 // models/session.js 2 define([ 3 'jquery', 4 'underscore', 5 'backbone', 6 'models/session', 7 'text!templates/example/login.html', 8 'text!templates/example/logout.html' 9 ], function($, _, Backbone, Session, exampleLoginTemplate, exampleLogoutTem 10 plate){ 11 var ExamplePage = Backbone.View.extend({
- 47. Cross-domain Backbone.js with sessions using CORS xli 12 el: '.page', 13 initialize: function () { 14 var that = this; 15 // Bind to the Session auth attribute so we 16 // make our view act recordingly when auth changes 17 Session.on('change:auth', function (session) { 18 that.render(); 19 }); 20 }, 21 render: function () { 22 // Simply choose which template to choose depending on 23 // our Session models auth attribute 24 if(Session.get('auth')){ 25 this.$el.html(_.template(exampleLogoutTemplate, {username: Session. 26 get('username')})); 27 } else { 28 this.$el.html(exampleLoginTemplate); 29 } 30 }, 31 events: { 32 'submit form.login': 'login', // On form submission 33 'click .logout': 'logout' 34 }, 35 login: function (ev) { 36 // Disable the button 37 $('[type=submit]', ev.currentTarget).val('Logging in').attr('disabled 38 ', 'disabled'); 39 // Serialize the form into an object using a jQuery plgin 40 var creds = $(ev.currentTarget).serializeObject(); 41 Session.login(creds); 42 return false; 43 }, 44 logout: function (ev) { 45 // Disable the button 46 $(ev.currentTarget).text('Logging out').attr('disabled', 'disabled'); 47 Session.logout(); 48 } 49 }); 50 return ExamplePage; 51 }); Note: .serializeObject is not a native jQuery function and I have included it in [app.js](https://github.com/thomasdav pages/examples/cross-domain/js/views/app.js) in the demo folder. creds can be an object of any variation of inputs, regardless it will be converted to JSON and posted to the server like any normal Backbone model. Here are the templates we are using for our login view 1 <!-- templates/example/login.html --> 2 <form class="login">
- 48. Cross-domain Backbone.js with sessions using CORS xlii 3 <label for="">Username</label> 4 <input name="username" type="text" required autofocus> 5 <input type="submit" id="submit" value="Login"> 6 </form> 7 8 <!-- templates/example/logout.html --> 9 <p>Hello, <%= username %>. Time to logout?</p> 10 <button class="logout">Logout</button> This wraps up setting up the client, there are some notable points to make sure this technique works. • You must use withCredentials supplied by jQuery - session.js • You must send your request with csrf tokens for security - session.js • You should wrap your applications entry pointer (router in this example) in a check auth function - app.js • You must point your application at the right server - app.js Building a compatible server This tutorial uses node.js, express.js and a modified csrf.js library. An example server.js file exist in the examples/cross-domain folder. When inside the folder simply type npm install -d to install the dependencies and then node server.js to start the server. Again, make sure your app.js points at the correct server. The server has to do a few things; • Allow CORS request • Implement csrf protection • Allow jQuery to send credentials • Set a whitelist of allowed domains • Configure the correct response headers To save you sometime here are some gotchas; • When sending withCredentials you must set correct response header Access-Control-Allow- Credentials: true. Also as a security policy browsers do not allow Access-Control-Allow- Origin to be set to *. So the origin of the request has to be known and trusted, so in the example below we use an of white listed domains. • jQuery ajax will trigger the browser to send these headers to enforce security origin, x- requested-with, accept so our server must allow them. • The browser might send out a pre-flight request to verify that it can talk to the server. The server must return 200 OK on these pre-flight request. Be sure to read this Mozilla documentation⁶⁴ on the above ⁶⁴http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/
- 49. Cross-domain Backbone.js with sessions using CORS xliii Example node server This server below implements everything we talked about above. It should be relativly easy to see how would translate into other frameworks and languages. app.configure runs the specified libraries against every request. We have told the server that on each request it should check the csrf token and check if the origin domain is white-listed. If so we edit each request to contain the appropiate headers. This server has 3 end points, that are pseduo-restful; • POST /session - Login - Sets the session username and returns a csrf token for the user to use • DELETE /session - Logout - Destroys the session and regenerates a new csrf token if the user wants to re-login • GET /session - Checks Auth - Simply returns if auth is true or false, if true then also returns some session details var express = require(‘express’); var connect = require(‘connect’); // Custom csrf library var csrf = require(‘./csrf’); var app = express.createServer(); var allowCrossDomain = function(req, res, next) { // Added other domains you want the server to give access to // WARNING - Be careful with what origins you give access to var allowedHost = [ ‘http://backbonetutorials.com’, ‘http://localhost’ ]; 1 if(allowedHost.indexOf(req.headers.origin) !== -1) { 2 res.header('Access-Control-Allow-Credentials', true); 3 res.header('Access-Control-Allow-Origin', req.headers.origin) 4 res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS') 5 ; 6 res.header('Access-Control-Allow-Headers', 'X-CSRF-Token, X-Requested-Wit 7 h, Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, 8 X-Api-Version'); 9 next(); 10 } else { 11 res.send({auth: false}); 12 } } app.configure(function() { app.use(express.cookieParser()); app.use(express.session({ secret: ‘thomas- davislovessalmon’ })); app.use(express.bodyParser()); app.use(allowCrossDomain); app.use(csrf.check); }); app.get(‘/session’, function(req, res){ // This checks the current users auth // It runs before Backbones router is started // we should return a csrf token for Backbone to use if(typeof req.session.username !== ‘undefined’){ res.send({auth: true, id: req.session.id, username: req.session.username, _csrf: req.session._csrf}); } else { res.send({auth: false, _csrf: req.session._csrf}); } }); app.post(‘/session’, function(req, res){ // Login // Here you would pull down your user credentials and match them up // to the request req.session.username = req.body.username; res.send({auth: true, id: req.session.id, username: req.session.username}); });
- 50. Cross-domain Backbone.js with sessions using CORS xliv app.del(‘/session/:id’, function(req, res, next){ // Logout by clearing the session req.session.regenerate(function(err){ // Generate a new csrf token so the user can login again // This is pretty hacky, connect.csrf isn’t built for rest // I will probably release a restful csrf module csrf.generate(req, res, function () { res.send({auth: false, _csrf: req.session._csrf}); }); }); }); app.listen(8000); Note: I wrote a custom csrf module for this which can be found in the example directory. It’s based of connects and uses the crypto library. I didn’t spend much time on it but other traditional csrf modules won’t work because they aren’t exactly built for this implentation technique. Conclusion This approach really hammers in the need for a well documented and designed API. A powerful API will let you do application iterations with ease. Again, it would be great for some more analysis of the security model. Enjoy using Backbone.js cross domain! I cannot get passed the spam filter on HackerNews so feel free to submit this tutorial Example Codebase⁶⁵ Example Demo⁶⁶ Relevant Links • cross-site xmlhttprequest with CORS⁶⁷ • Cross-Origin Resource Sharing⁶⁸ • Using CORS with All (Modern) Browsers⁶⁹ ⁶⁵https://github.com/thomasdavis/backbonetutorials/tree/gh-pages/examples/cross-domain ⁶⁶http://backbonetutorials.com/examples/cross-domain/ ⁶⁷http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/ ⁶⁸http://www.w3.org/TR/cors/ ⁶⁹http://www.kendoui.com/blogs/teamblog/posts/11-10-04/using_cors_with_all_modern_browsers.aspx