Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Backbone.js 0.9.0

  • Loading branch information...
commit 5ce976bf6a6c795e295190bcc48c39e52f9afe6f 1 parent 8ce8753
@jashkenas jashkenas authored
View
2  LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2010-2011 Jeremy Ashkenas, DocumentCloud
+Copyright (c) 2010-2012 Jeremy Ashkenas, DocumentCloud
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
View
35 backbone-min.js
@@ -0,0 +1,35 @@
+// Backbone.js 0.9.0
+// (c) 2010-2012 Jeremy Ashkenas, DocumentCloud Inc.
+// Backbone may be freely distributed under the MIT license.
+// For all details and documentation:
+// http://backbonejs.org
+(function(){var i=this,r=i.Backbone,s=Array.prototype.slice,t=Array.prototype.splice,g;g=typeof exports!=="undefined"?exports:i.Backbone={};g.VERSION="0.9.0";var f=i._;!f&&typeof require!=="undefined"&&(f=require("underscore"));var h=i.jQuery||i.Zepto||i.ender;g.noConflict=function(){i.Backbone=r;return this};g.emulateHTTP=false;g.emulateJSON=false;g.Events={on:function(a,b,c){for(var d,a=a.split(/\s+/),e=this._callbacks||(this._callbacks={});d=a.shift();){d=e[d]||(e[d]={});var f=d.tail||(d.tail=
+d.next={});f.callback=b;f.context=c;d.tail=f.next={}}return this},off:function(a,b,c){var d,e,f;if(a){if(e=this._callbacks)for(a=a.split(/\s+/);d=a.shift();)if(f=e[d],delete e[d],b&&f)for(;(f=f.next)&&f.next;)if(!(f.callback===b&&(!c||f.context===c)))this.on(d,f.callback,f.context)}else delete this._callbacks;return this},trigger:function(a){var b,c,d,e;if(!(d=this._callbacks))return this;e=d.all;for((a=a.split(/\s+/)).push(null);b=a.shift();)e&&a.push({next:e.next,tail:e.tail,event:b}),(c=d[b])&&
+a.push({next:c.next,tail:c.tail});for(e=s.call(arguments,1);c=a.pop();){b=c.tail;for(d=c.event?[c.event].concat(e):e;(c=c.next)!==b;)c.callback.apply(c.context||this,d)}return this}};g.Events.bind=g.Events.on;g.Events.unbind=g.Events.off;g.Model=function(a,b){var c;a||(a={});b&&b.parse&&(a=this.parse(a));if(c=j(this,"defaults"))a=f.extend({},c,a);if(b&&b.collection)this.collection=b.collection;this.attributes={};this._escapedAttributes={};this.cid=f.uniqueId("c");this._changed={};if(!this.set(a,{silent:true}))throw Error("Can't create an invalid model");
+this._changed={};this._previousAttributes=f.clone(this.attributes);this.initialize.apply(this,arguments)};f.extend(g.Model.prototype,g.Events,{idAttribute:"id",initialize:function(){},toJSON:function(){return f.clone(this.attributes)},get:function(a){return this.attributes[a]},escape:function(a){var b;if(b=this._escapedAttributes[a])return b;b=this.attributes[a];return this._escapedAttributes[a]=f.escape(b==null?"":""+b)},has:function(a){return this.attributes[a]!=null},set:function(a,b,c){var d,
+e;f.isObject(a)||a==null?(d=a,c=b):(d={},d[a]=b);c||(c={});if(!d)return this;if(d instanceof g.Model)d=d.attributes;if(c.unset)for(e in d)d[e]=void 0;if(this.validate&&!this._performValidation(d,c))return false;if(this.idAttribute in d)this.id=d[this.idAttribute];var b=this.attributes,k=this._escapedAttributes,n=this._previousAttributes||{},u=this._changing;this._changing=true;for(e in d)if(a=d[e],f.isEqual(b[e],a)||delete k[e],c.unset?delete b[e]:b[e]=a,delete this._changed[e],!f.isEqual(n[e],a)||
+f.has(b,e)!=f.has(n,e))this._changed[e]=a;if(!u)!c.silent&&this.hasChanged()&&this.change(c),this._changing=false;return this},unset:function(a,b){(b||(b={})).unset=true;return this.set(a,null,b)},clear:function(a){(a||(a={})).unset=true;return this.set(f.clone(this.attributes),a)},fetch:function(a){var a=a?f.clone(a):{},b=this,c=a.success;a.success=function(d,e,f){if(!b.set(b.parse(d,f),a))return false;c&&c(b,d)};a.error=g.wrapError(a.error,b,a);return(this.sync||g.sync).call(this,"read",this,a)},
+save:function(a,b,c){var d;f.isObject(a)||a==null?(d=a,c=b):(d={},d[a]=b);c=c?f.clone(c):{};if(d&&!this[c.wait?"_performValidation":"set"](d,c))return false;var e=this,k=c.success;c.success=function(a,b,g){b=e.parse(a,g);c.wait&&(b=f.extend(d||{},b));if(!e.set(b,c))return false;k?k(e,a):e.trigger("sync",e,a,c)};c.error=g.wrapError(c.error,e,c);a=this.isNew()?"create":"update";return(this.sync||g.sync).call(this,a,this,c)},destroy:function(a){var a=a?f.clone(a):{},b=this,c=a.success,d=function(){b.trigger("destroy",
+b,b.collection,a)};if(this.isNew())return d();a.success=function(e){a.wait&&d();c?c(b,e):b.trigger("sync",b,e,a)};a.error=g.wrapError(a.error,b,a);var e=(this.sync||g.sync).call(this,"delete",this,a);a.wait||d();return e},url:function(){var a=j(this.collection,"url")||j(this,"urlRoot")||o();return this.isNew()?a:a+(a.charAt(a.length-1)=="/"?"":"/")+encodeURIComponent(this.id)},parse:function(a){return a},clone:function(){return new this.constructor(this.attributes)},isNew:function(){return this.id==
+null},change:function(a){for(var b in this._changed)this.trigger("change:"+b,this,this._changed[b],a);this.trigger("change",this,a);this._previousAttributes=f.clone(this.attributes);this._changed={}},hasChanged:function(a){return a?f.has(this._changed,a):!f.isEmpty(this._changed)},changedAttributes:function(a){if(!a)return this.hasChanged()?f.clone(this._changed):false;var b,c=false,d=this._previousAttributes,e;for(e in a)if(!f.isEqual(d[e],b=a[e]))(c||(c={}))[e]=b;return c},previous:function(a){return!a||
+!this._previousAttributes?null:this._previousAttributes[a]},previousAttributes:function(){return f.clone(this._previousAttributes)},_performValidation:function(a,b){var c=this.validate(f.extend({},this.attributes,a),b);return c?(b.error?b.error(this,c,b):this.trigger("error",this,c,b),false):true}});g.Collection=function(a,b){b||(b={});if(b.comparator)this.comparator=b.comparator;this._reset();this.initialize.apply(this,arguments);a&&this.reset(a,{silent:true,parse:b.parse})};f.extend(g.Collection.prototype,
+g.Events,{model:g.Model,initialize:function(){},toJSON:function(){return this.map(function(a){return a.toJSON()})},add:function(a,b){var c,d,e,g,h,i={},j={};b||(b={});a=f.isArray(a)?a.slice():[a];for(c=0,d=a.length;c<d;c++){if(!(e=a[c]=this._prepareModel(a[c],b)))throw Error("Can't add an invalid model to a collection");if(i[g=e.cid]||this._byCid[g]||(h=e.id)!=null&&(j[h]||this._byId[h]))throw Error("Can't add the same model to a collection twice");i[g]=j[h]=e}for(c=0;c<d;c++)(e=a[c]).on("all",this._onModelEvent,
+this),this._byCid[e.cid]=e,e.id!=null&&(this._byId[e.id]=e);this.length+=d;t.apply(this.models,[b.at!=null?b.at:this.models.length,0].concat(a));this.comparator&&this.sort({silent:true});if(b.silent)return this;for(c=0,d=this.models.length;c<d;c++)if(i[(e=this.models[c]).cid])b.index=c,e.trigger("add",e,this,b);return this},remove:function(a,b){var c,d,e,g;b||(b={});a=f.isArray(a)?a.slice():[a];for(c=0,d=a.length;c<d;c++)if(g=this.getByCid(a[c])||this.get(a[c])){delete this._byId[g.id];delete this._byCid[g.cid];
+e=this.indexOf(g);this.models.splice(e,1);this.length--;if(!b.silent)b.index=e,g.trigger("remove",g,this,b);this._removeReference(g)}return this},get:function(a){return a==null?null:this._byId[a.id!=null?a.id:a]},getByCid:function(a){return a&&this._byCid[a.cid||a]},at:function(a){return this.models[a]},sort:function(a){a||(a={});if(!this.comparator)throw Error("Cannot sort a set without a comparator");var b=f.bind(this.comparator,this);this.comparator.length==1?this.models=this.sortBy(b):this.models.sort(b);
+a.silent||this.trigger("reset",this,a);return this},pluck:function(a){return f.map(this.models,function(b){return b.get(a)})},reset:function(a,b){a||(a=[]);b||(b={});for(var c=0,d=this.models.length;c<d;c++)this._removeReference(this.models[c]);this._reset();this.add(a,{silent:true,parse:b.parse});b.silent||this.trigger("reset",this,b);return this},fetch:function(a){a=a?f.clone(a):{};if(a.parse===void 0)a.parse=true;var b=this,c=a.success;a.success=function(d,e,f){b[a.add?"add":"reset"](b.parse(d,
+f),a);c&&c(b,d)};a.error=g.wrapError(a.error,b,a);return(this.sync||g.sync).call(this,"read",this,a)},create:function(a,b){var c=this,b=b?f.clone(b):{},a=this._prepareModel(a,b);if(!a)return false;b.wait||c.add(a,b);var d=b.success;b.success=function(e,f){b.wait&&c.add(e,b);d?d(e,f):e.trigger("sync",a,f,b)};a.save(null,b);return a},parse:function(a){return a},chain:function(){return f(this.models).chain()},_reset:function(){this.length=0;this.models=[];this._byId={};this._byCid={}},_prepareModel:function(a,
+b){if(a instanceof g.Model){if(!a.collection)a.collection=this}else{var c;b.collection=this;a=new this.model(a,b);a.validate&&!a._performValidation(a.attributes,b)&&(a=false)}return a},_removeReference:function(a){this==a.collection&&delete a.collection;a.off("all",this._onModelEvent,this)},_onModelEvent:function(a,b,c,d){(a=="add"||a=="remove")&&c!=this||(a=="destroy"&&this.remove(b,d),b&&a==="change:"+b.idAttribute&&(delete this._byId[b.previous(b.idAttribute)],this._byId[b.id]=b),this.trigger.apply(this,
+arguments))}});f.each("forEach,each,map,reduce,reduceRight,find,detect,filter,select,reject,every,all,some,any,include,contains,invoke,max,min,sortBy,sortedIndex,toArray,size,first,initial,rest,last,without,indexOf,shuffle,lastIndexOf,isEmpty,groupBy".split(","),function(a){g.Collection.prototype[a]=function(){return f[a].apply(f,[this.models].concat(f.toArray(arguments)))}});g.Router=function(a){a||(a={});if(a.routes)this.routes=a.routes;this._bindRoutes();this.initialize.apply(this,arguments)};
+var v=/:\w+/g,w=/\*\w+/g,x=/[-[\]{}()+?.,\\^$|#\s]/g;f.extend(g.Router.prototype,g.Events,{initialize:function(){},route:function(a,b,c){g.history||(g.history=new g.History);f.isRegExp(a)||(a=this._routeToRegExp(a));c||(c=this[b]);g.history.route(a,f.bind(function(d){d=this._extractParameters(a,d);c&&c.apply(this,d);this.trigger.apply(this,["route:"+b].concat(d));g.history.trigger("route",this,b,d)},this));return this},navigate:function(a,b){g.history.navigate(a,b)},_bindRoutes:function(){if(this.routes){var a=
+[],b;for(b in this.routes)a.unshift([b,this.routes[b]]);b=0;for(var c=a.length;b<c;b++)this.route(a[b][0],a[b][1],this[a[b][1]])}},_routeToRegExp:function(a){a=a.replace(x,"\\$&").replace(v,"([^/]+)").replace(w,"(.*?)");return RegExp("^"+a+"$")},_extractParameters:function(a,b){return a.exec(b).slice(1)}});g.History=function(){this.handlers=[];f.bindAll(this,"checkUrl")};var m=/^[#\/]/,y=/msie [\w.]+/,l=false;f.extend(g.History.prototype,g.Events,{interval:50,getFragment:function(a,b){if(a==null)if(this._hasPushState||
+b){var a=window.location.pathname,c=window.location.search;c&&(a+=c)}else a=window.location.hash;a=decodeURIComponent(a.replace(m,""));a.indexOf(this.options.root)||(a=a.substr(this.options.root.length));return a},start:function(a){if(l)throw Error("Backbone.history has already been started");this.options=f.extend({},{root:"/"},this.options,a);this._wantsHashChange=this.options.hashChange!==false;this._wantsPushState=!!this.options.pushState;this._hasPushState=!(!this.options.pushState||!window.history||
+!window.history.pushState);var a=this.getFragment(),b=document.documentMode;if(b=y.exec(navigator.userAgent.toLowerCase())&&(!b||b<=7))this.iframe=h('<iframe src="javascript:0" tabindex="-1" />').hide().appendTo("body")[0].contentWindow,this.navigate(a);if(this._hasPushState)h(window).bind("popstate",this.checkUrl);else if(this._wantsHashChange&&"onhashchange"in window&&!b)h(window).bind("hashchange",this.checkUrl);else if(this._wantsHashChange)this._checkUrlInterval=setInterval(this.checkUrl,this.interval);
+this.fragment=a;l=true;a=window.location;b=a.pathname==this.options.root;if(this._wantsHashChange&&this._wantsPushState&&!this._hasPushState&&!b)return this.fragment=this.getFragment(null,true),window.location.replace(this.options.root+"#"+this.fragment),true;else if(this._wantsPushState&&this._hasPushState&&b&&a.hash)this.fragment=a.hash.replace(m,""),window.history.replaceState({},document.title,a.protocol+"//"+a.host+this.options.root+this.fragment);if(!this.options.silent)return this.loadUrl()},
+stop:function(){h(window).unbind("popstate",this.checkUrl).unbind("hashchange",this.checkUrl);clearInterval(this._checkUrlInterval);l=false},route:function(a,b){this.handlers.unshift({route:a,callback:b})},checkUrl:function(){var a=this.getFragment();a==this.fragment&&this.iframe&&(a=this.getFragment(this.iframe.location.hash));if(a==this.fragment||a==decodeURIComponent(this.fragment))return false;this.iframe&&this.navigate(a);this.loadUrl()||this.loadUrl(window.location.hash)},loadUrl:function(a){var b=
+this.fragment=this.getFragment(a);return f.any(this.handlers,function(a){if(a.route.test(b))return a.callback(b),true})},navigate:function(a,b){if(!l)return false;if(!b||b===true)b={trigger:b};var c=(a||"").replace(m,"");if(!(this.fragment==c||this.fragment==decodeURIComponent(c)))this._hasPushState?(c.indexOf(this.options.root)!=0&&(c=this.options.root+c),this.fragment=c,window.history[b.replace?"replaceState":"pushState"]({},document.title,c)):this._wantsHashChange?(this.fragment=c,this._updateHash(window.location,
+c,b.replace),this.iframe&&c!=this.getFragment(this.iframe.location.hash)&&(b.replace||this.iframe.document.open().close(),this._updateHash(this.iframe.location,c,b.replace))):window.location.assign(this.options.root+a),b.trigger&&this.loadUrl(a)},_updateHash:function(a,b,c){c?a.replace(a.toString().replace(/(javascript:|#).*$/,"")+"#"+b):a.hash=b}});g.View=function(a){this.cid=f.uniqueId("view");this._configure(a||{});this._ensureElement();this.initialize.apply(this,arguments);this.delegateEvents()};
+var z=/^(\S+)\s*(.*)$/,p="model,collection,el,id,attributes,className,tagName".split(",");f.extend(g.View.prototype,g.Events,{tagName:"div",$:function(a){return this.$el.find(a)},initialize:function(){},render:function(){return this},remove:function(){this.$el.remove();return this},make:function(a,b,c){a=document.createElement(a);b&&h(a).attr(b);c&&h(a).html(c);return a},setElement:function(a,b){this.$el=h(a);this.el=this.$el[0];b!==false&&this.delegateEvents()},delegateEvents:function(a){if(a||(a=
+j(this,"events"))){this.undelegateEvents();for(var b in a){var c=a[b];f.isFunction(c)||(c=this[a[b]]);if(!c)throw Error('Event "'+a[b]+'" does not exist');var d=b.match(z),e=d[1],d=d[2],c=f.bind(c,this);e+=".delegateEvents"+this.cid;d===""?this.$el.bind(e,c):this.$el.delegate(d,e,c)}}},undelegateEvents:function(){this.$el.unbind(".delegateEvents"+this.cid)},_configure:function(a){this.options&&(a=f.extend({},this.options,a));for(var b=0,c=p.length;b<c;b++){var d=p[b];a[d]&&(this[d]=a[d])}this.options=
+a},_ensureElement:function(){if(this.el)this.setElement(this.el,false);else{var a=j(this,"attributes")||{};if(this.id)a.id=this.id;if(this.className)a["class"]=this.className;this.setElement(this.make(this.tagName,a),false)}}});g.Model.extend=g.Collection.extend=g.Router.extend=g.View.extend=function(a,b){var c=A(this,a,b);c.extend=this.extend;return c};var B={create:"POST",update:"PUT","delete":"DELETE",read:"GET"};g.sync=function(a,b,c){var d=B[a],e={type:d,dataType:"json"};if(!c.url)e.url=j(b,
+"url")||o();if(!c.data&&b&&(a=="create"||a=="update"))e.contentType="application/json",e.data=JSON.stringify(b.toJSON());if(g.emulateJSON)e.contentType="application/x-www-form-urlencoded",e.data=e.data?{model:e.data}:{};if(g.emulateHTTP&&(d==="PUT"||d==="DELETE")){if(g.emulateJSON)e.data._method=d;e.type="POST";e.beforeSend=function(a){a.setRequestHeader("X-HTTP-Method-Override",d)}}if(e.type!=="GET"&&!g.emulateJSON)e.processData=false;return h.ajax(f.extend(e,c))};g.wrapError=function(a,b,c){return function(d,
+e){e=d===b?e:d;a?a(d,e,c):b.trigger("error",d,e,c)}};var q=function(){},A=function(a,b,c){var d;d=b&&b.hasOwnProperty("constructor")?b.constructor:function(){a.apply(this,arguments)};f.extend(d,a);q.prototype=a.prototype;d.prototype=new q;b&&f.extend(d.prototype,b);c&&f.extend(d,c);d.prototype.constructor=d;d.__super__=a.prototype;return d},j=function(a,b){return!a||!a[b]?null:f.isFunction(a[b])?a[b]():a[b]},o=function(){throw Error('A "url" property or function must be specified');}}).call(this);
View
4 backbone.js
@@ -1,4 +1,4 @@
-// Backbone.js 0.5.3
+// Backbone.js 0.9.0
// (c) 2010-2012 Jeremy Ashkenas, DocumentCloud Inc.
// Backbone may be freely distributed under the MIT license.
// For all details and documentation:
@@ -31,7 +31,7 @@
}
// Current version of the library. Keep in sync with `package.json`.
- Backbone.VERSION = '0.5.3';
+ Backbone.VERSION = '0.9.0';
// Require Underscore, if we're on the server, and it's not already present.
var _ = root._;
View
817 docs/backbone.html
432 additions, 385 deletions not shown
View
2  docs/todos.html
@@ -82,7 +82,7 @@
<span class="p">},</span></pre></div> </td> </tr> <tr id="section-37"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-37">&#182;</a> </div> <p>Add a single todo item to the list by creating a view for it, and
appending its element to the <code>&lt;ul&gt;</code>.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">addOne</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">todo</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">view</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">TodoView</span><span class="p">({</span><span class="nx">model</span><span class="o">:</span> <span class="nx">todo</span><span class="p">});</span>
- <span class="k">this</span><span class="p">.</span><span class="nx">$</span><span class="p">(</span><span class="s2">&quot;#todo-list&quot;</span><span class="p">).</span><span class="nx">append</span><span class="p">(</span><span class="nx">view</span><span class="p">.</span><span class="nx">render</span><span class="p">().</span><span class="nx">el</span><span class="p">);</span>
+ <span class="nx">$</span><span class="p">(</span><span class="s2">&quot;#todo-list&quot;</span><span class="p">).</span><span class="nx">append</span><span class="p">(</span><span class="nx">view</span><span class="p">.</span><span class="nx">render</span><span class="p">().</span><span class="nx">el</span><span class="p">);</span>
<span class="p">},</span></pre></div> </td> </tr> <tr id="section-38"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-38">&#182;</a> </div> <p>Add all items in the <strong>Todos</strong> collection at once.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">addAll</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">Todos</span><span class="p">.</span><span class="nx">each</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">addOne</span><span class="p">);</span>
<span class="p">},</span></pre></div> </td> </tr> <tr id="section-39"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-39">&#182;</a> </div> <p>If you hit return in the main input field, and there is text to save,
View
314 index.html
@@ -83,9 +83,16 @@
}
div.container ul {
list-style: circle;
- font-size: 12px;
padding-left: 15px;
+ font-size: 13px;
+ line-height: 18px;
}
+ div.container ul li {
+ margin-bottom: 10px;
+ }
+ div.container ul.small {
+ font-size: 12px;
+ }
a, a:visited {
color: #444;
}
@@ -191,19 +198,23 @@
<div id="sidebar" class="interface">
<a class="toc_title" href="#">
- Backbone.js <span class="version">(0.5.3)</span>
+ Backbone.js <span class="version">(0.9.0)</span>
</a>
- <a class="toc_title" href="#Introduction">
+ <a class="toc_title" href="#introduction">
Introduction
</a>
+
+ <a class="toc_title" href="#upgrading">
+ Upgrading
+ </a>
<a class="toc_title" href="#Events">
Events
</a>
<ul class="toc_section">
- <li>– <a href="#Events-bind">bind</a></li>
- <li>– <a href="#Events-unbind">unbind</a></li>
+ <li>– <a href="#Events-on">on</a></li>
+ <li>– <a href="#Events-off">off</a></li>
<li>– <a href="#Events-trigger">trigger</a></li>
</ul>
@@ -250,7 +261,7 @@
<li>– <a href="#Collection-constructor">constructor / initialize</a></li>
<li>– <a href="#Collection-models">models</a></li>
<li>– <a href="#Collection-toJSON">toJSON</a></li>
- <li>– <a href="#Collection-Underscore-Methods"><b>Underscore Methods (26)</b></a></li>
+ <li>– <a href="#Collection-Underscore-Methods"><b>Underscore Methods (28)</b></a></li>
<li>– <a href="#Collection-add">add</a></li>
<li>– <a href="#Collection-remove">remove</a></li>
<li>– <a href="#Collection-get">get</a></li>
@@ -301,11 +312,15 @@
<li>– <a href="#View-extend">extend</a></li>
<li>– <a href="#View-constructor">constructor / initialize</a></li>
<li>– <a href="#View-el">el</a></li>
+ <li>– <a href="#View-$el">$el</a></li>
+ <li>– <a href="#View-setElement">setElement</a></li>
+ <li>– <a href="#View-attributes">attributes</a></li>
<li>– <a href="#View-dollar">$ (jQuery or Zepto)</a></li>
<li>– <a href="#View-render">render</a></li>
<li>– <a href="#View-remove">remove</a></li>
<li>– <a href="#View-make">make</a></li>
<li>– <a href="#View-delegateEvents">delegateEvents</a></li>
+ <li>– <a href="#View-undelegateEvents">undelegateEvents</a></li>
</ul>
<a class="toc_title" href="#Utility">
@@ -421,12 +436,12 @@ <h2 id="downloads">
<table>
<tr>
- <td><a class="punch" href="backbone.js">Development Version (0.5.3)</a></td>
- <td><i>41kb, Full Source with Comments</i></td>
+ <td><a class="punch" href="backbone.js">Development Version (0.9.0)</a></td>
+ <td><i>47kb, Full source, lots of comments</i></td>
</tr>
<tr>
- <td><a class="punch" href="backbone-min.js">Production Version (0.5.3)</a></td>
- <td><i>4.6kb, Packed and Gzipped</i></td>
+ <td><a class="punch" href="backbone-min.js">Production Version (0.9.0)</a></td>
+ <td><i>5.3kb, Packed and gzipped</i></td>
</tr>
</table>
@@ -440,7 +455,7 @@ <h2 id="downloads">
<a href="http://zeptojs.com/">Zepto</a>.
</p>
- <h2 id="Introduction">Introduction</h2>
+ <h2 id="introduction">Introduction</h2>
<p>
When working on a web application that involves a lot of JavaScript, one
@@ -469,6 +484,33 @@ <h2 id="Introduction">Introduction</h2>
Many of the examples that follow are runnable. Click the <i>play</i> button
to execute them.
</p>
+
+ <h2 id="upgrading">Upgrading to 0.9</h2>
+
+ <p>
+ Backbone's <b>0.9</b> series should be considered as a release candidate
+ for an upcoming <b>1.0</b>. Some APIs have changed, and while there is a
+ <a href="#changelog">change log</a> available, and many new features to
+ take advantage of, there are a few specific changes where you'll need
+ to take care:
+ </p>
+
+ <ul>
+ <li>
+ If you've ever manually set <tt>this.el</tt> in a Backbone View to be a
+ particular DOM element, you'll want to use
+ <a href="#View-setElement">setElement</a> instead.
+ </li>
+ <li>
+ Creating and destroying models is now optimistic. Pass <tt>{wait: true}</tt>
+ if you need the previous behavior of waiting for the server to acknowledge
+ success. You can now also pass <tt>{wait: true}</tt> to <a href="#Model-save">save</a> calls.
+ </li>
+ <li>
+ If you have been writing a fair amount of <tt>$(view.el)</tt>, there's now
+ a cached reference for that jQuery object: <a href="#View-$el">$el</a>.
+ </li>
+ </ul>
<h2 id="Events">Backbone.Events</h2>
@@ -484,7 +526,7 @@ <h2 id="Events">Backbone.Events</h2>
_.extend(object, Backbone.Events);
-object.bind("alert", function(msg) {
+object.on("alert", function(msg) {
alert("Triggered " + msg);
});
@@ -496,8 +538,8 @@ <h2 id="Events">Backbone.Events</h2>
among different areas of your application: <tt>var dispatcher = _.clone(Backbone.Events)</tt>
</p>
- <p id="Events-bind">
- <b class="header">bind</b><code>object.bind(event, callback, [context])</code>
+ <p id="Events-on">
+ <b class="header">on</b><code>object.on(event, callback, [context])</code><span class="alias">Alias: bind</span>
<br />
Bind a <b>callback</b> function to an object. The callback will be invoked
whenever the <b>event</b> (specified by an arbitrary string identifier) is fired.
@@ -507,7 +549,7 @@ <h2 id="Events">Backbone.Events</h2>
<p>
To supply a <b>context</b> value for <tt>this</tt> when the callback is invoked,
- pass the optional third argument: <tt>model.bind('change', this.render, this)</tt>
+ pass the optional third argument: <tt>model.on('change', this.render, this)</tt>
</p>
<p>
@@ -518,26 +560,28 @@ <h2 id="Events">Backbone.Events</h2>
</p>
<pre>
-proxy.bind("all", function(eventName) {
+proxy.on("all", function(eventName) {
object.trigger(eventName);
});
</pre>
- <p id="Events-unbind">
- <b class="header">unbind</b><code>object.unbind([event], [callback])</code>
+ <p id="Events-off">
+ <b class="header">off</b><code>object.off([event], [callback], [context])</code><span class="alias">Alias: unbind</span>
<br />
Remove a previously-bound <b>callback</b> function from an object. If no
+ <b>context</b> is specified, all of the versions of the callback with
+ different contexts will be removed. If no
callback is specified, all callbacks for the <b>event</b> will be
removed. If no event is specified, <i>all</i> event callbacks on the object
will be removed.
</p>
<pre>
-object.unbind("change", onChange); // Removes just the onChange callback.
+object.off("change", onChange); // Removes just the onChange callback.
-object.unbind("change"); // Removes all "change" callbacks.
+object.off("change"); // Removes all "change" callbacks.
-object.unbind(); // Removes all callbacks on object.
+object.off(); // Removes all callbacks on object.
</pre>
<p id="Events-trigger">
@@ -575,7 +619,7 @@ <h2 id="Model">Backbone.Model</h2>
window.sidebar = new Sidebar;
-sidebar.bind('change:color', function(model, color) {
+sidebar.on('change:color', function(model, color) {
$('#sidebar').css({background: color});
});
@@ -674,11 +718,14 @@ <h2 id="Model">Backbone.Model</h2>
change the models state, a <tt>"change"</tt> event will be triggered, unless
<tt>{silent: true}</tt> is passed as an option. Change events for specific
attributes are also triggered, and you can bind to those as well, for example:
- <tt>change:title</tt>, and <tt>change:content</tt>.
+ <tt>change:title</tt>, and <tt>change:content</tt>. You may also pass
+ individual keys and values.
</p>
<pre>
-note.set({title: "October 12", content: "Lorem Ipsum Dolor Sit Amet..."});
+note.set({title: "March 20", content: "In his eyes she eclipses..."});
+
+book.set("title", "A Scandal in Bohemia");
</pre>
<p>
@@ -854,12 +901,20 @@ <h2 id="Model">Backbone.Model</h2>
hash (as in <a href="#Model-set">set</a>) should contain the attributes
you'd like to change &mdash; keys that aren't mentioned won't be altered &mdash; but,
a <i>complete representation</i> of the resource will be sent to the server.
+ As with <tt>set</tt>, you may pass individual keys and values instead of a hash.
If the model has a <a href="#Model-validate">validate</a>
method, and validation fails, the model will not be saved. If the model
<a href="#Model-isNew">isNew</a>, the save will be a <tt>"create"</tt>
(HTTP <tt>POST</tt>), if the model already
exists on the server, the save will be an <tt>"update"</tt> (HTTP <tt>PUT</tt>).
</p>
+
+ <p>
+ Calling <tt>save</tt> with new attributes will cause a <tt>"change"</tt>
+ event immediately, and a <tt>"sync"</tt> event after the server has acknowledged
+ the successful change. Pass <tt>{wait: true}</tt> if you'd like to wait
+ for the server before setting the new attributes on the model.
+ </p>
<p>
In the following example, notice how our overridden version
@@ -894,7 +949,7 @@ <h2 id="Model">Backbone.Model</h2>
</p>
<pre>
-book.save({author: "F.D.R."}, {error: function(){ ... }});
+book.save("author", "F.D.R.", {error: function(){ ... }});
</pre>
<p id="Model-destroy">
@@ -904,7 +959,10 @@ <h2 id="Model">Backbone.Model</h2>
request to <a href="#Sync">Backbone.sync</a>. Accepts
<tt>success</tt> and <tt>error</tt> callbacks in the options hash.
Triggers a <tt>"destroy"</tt> event on the model, which will bubble up
- through any collections that contain it.
+ through any collections that contain it, and a <tt>"sync"</tt> event, after
+ the server has successfully acknowledged the model's deletion. Pass
+ <tt>{wait: true}</tt> if you'd like to wait for the server to respond
+ before removing the model from the collection.
</p>
<pre>
@@ -941,7 +999,7 @@ <h2 id="Model">Backbone.Model</h2>
title : "Chapter One: The Beginning"
});
-one.bind("error", function(model, error) {
+one.on("error", function(model, error) {
alert(model.get("title") + " " + error);
});
@@ -989,7 +1047,8 @@ <h2 id="Model">Backbone.Model</h2>
<br />
Specify a <tt>urlRoot</tt> if you're using a model outside of a collection,
to enable the default <a href="#Model-url">url</a> function to generate
- URLs based on the model id. <tt>"/[urlRoot]/id"</tt>
+ URLs based on the model id. <tt>"/[urlRoot]/id"</tt><br />
+ Note that <tt>urlRoot</tt> may also be defined as a function.
</p>
<pre class="runnable">
@@ -1058,7 +1117,7 @@ <h2 id="Model">Backbone.Model</h2>
</p>
<pre>
-book.bind("change", function() {
+book.on("change", function() {
if (book.hasChanged("title")) {
...
}
@@ -1087,7 +1146,7 @@ <h2 id="Model">Backbone.Model</h2>
name: "Bill Smith"
});
-bill.bind("change:name", function(model, name) {
+bill.on("change:name", function(model, name) {
alert("Changed name from " + bill.previous("name") + " to " + name);
});
@@ -1117,7 +1176,7 @@ <h2 id="Collection">Backbone.Collection</h2>
triggered on the collection directly, for convenience.
This allows you to listen for changes to specific attributes in any
model in a collection, for example:
- <tt>Documents.bind("change:selected", ...)</tt>
+ <tt>Documents.on("change:selected", ...)</tt>
</p>
<p id="Collection-extend">
@@ -1187,14 +1246,14 @@ <h2 id="Collection">Backbone.Collection</h2>
</pre>
<p id="Collection-Underscore-Methods">
- <b class="header">Underscore Methods (26)</b>
+ <b class="header">Underscore Methods (28)</b>
<br />
- Backbone proxies to <b>Underscore.js</b> to provide 26 iteration functions
+ Backbone proxies to <b>Underscore.js</b> to provide 28 iteration functions
on <b>Backbone.Collection</b>. They aren't all documented here, but
you can take a look at the Underscore documentation for the full details&hellip;
</p>
- <ul>
+ <ul class="small">
<li><a href="http://documentcloud.github.com/underscore/#each">forEach (each)</a></li>
<li><a href="http://documentcloud.github.com/underscore/#map">map</a></li>
<li><a href="http://documentcloud.github.com/underscore/#reduce">reduce (foldl, inject)</a></li>
@@ -1211,9 +1270,11 @@ <h2 id="Collection">Backbone.Collection</h2>
<li><a href="http://documentcloud.github.com/underscore/#sortBy">sortBy</a></li>
<li><a href="http://documentcloud.github.com/underscore/#groupBy">groupBy</a></li>
<li><a href="http://documentcloud.github.com/underscore/#sortedIndex">sortedIndex</a></li>
+ <li><a href="http://documentcloud.github.com/underscore/#shuffle">shuffle</a></li>
<li><a href="http://documentcloud.github.com/underscore/#toArray">toArray</a></li>
<li><a href="http://documentcloud.github.com/underscore/#size">size</a></li>
<li><a href="http://documentcloud.github.com/underscore/#first">first</a></li>
+ <li><a href="http://documentcloud.github.com/underscore/#initial">initial</a></li>
<li><a href="http://documentcloud.github.com/underscore/#rest">rest</a></li>
<li><a href="http://documentcloud.github.com/underscore/#last">last</a></li>
<li><a href="http://documentcloud.github.com/underscore/#without">without</a></li>
@@ -1249,13 +1310,15 @@ <h2 id="Collection">Backbone.Collection</h2>
<a href="#Collection-model">model</a> property is defined, you may also pass
raw attributes objects, and have them be vivified as instances of the model.
Pass <tt>{at: index}</tt> to splice the model into the collection at the
- specified <tt>index</tt>.
+ specified <tt>index</tt>. Likewise, if you're a callback listening to a
+ collection's <tt>"add"</tt> event, <tt>options.index</tt> will tell you the
+ index at which the model is being added to the collection.
</p>
<pre class="runnable">
var ships = new Backbone.Collection;
-ships.bind("add", function(ship) {
+ships.on("add", function(ship) {
alert("Ahoy " + ship.get("name") + "!");
});
@@ -1270,7 +1333,9 @@ <h2 id="Collection">Backbone.Collection</h2>
<br />
Remove a model (or an array of models) from the collection. Fires a
<tt>"remove"</tt> event, which you can use <tt>silent</tt>
- to suppress.
+ to suppress. If you're a callback listening to the <tt>"remove"</tt> event,
+ the index at which the model is being removed from the collection is available
+ as <tt>options.index</tt>.
</p>
<p id="Collection-get">
@@ -1314,8 +1379,20 @@ <h2 id="Collection">Backbone.Collection</h2>
If you define a comparator, it will be used to maintain
the collection in sorted order. This means that as models are added,
they are inserted at the correct index in <tt>collection.models</tt>.
- Comparator functions take a model and return a numeric or string value
- by which the model should be ordered relative to others.
+ Comparator function can be defined as either a
+ <a href="http://underscorejs.org/#sortBy">sortBy</a>
+ (pass a function that takes a single argument),
+ or as a
+ <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
+ (pass a comparator function that expects two arguments).
+ </p>
+
+ <p>
+ "sort" comparator functions take a model and return a numeric or string
+ value by which the model should be ordered relative to others.
+ "sortBy" comparator functions take two models, and return <tt>-1</tt> if
+ the first model should come before the second, <tt>0</tt> if they are of
+ the same rank and <tt>1</tt> if the first model should come after.
</p>
<p>
@@ -1339,12 +1416,6 @@ <h2 id="Collection">Backbone.Collection</h2>
</pre>
<p class="warning">
- Brief aside: This comparator function is different than JavaScript's regular
- "sort", which must return <tt>0</tt>, <tt>1</tt>, or <tt>-1</tt>,
- and is more similar to a <tt>sortBy</tt> &mdash; a much nicer API.
- </p>
-
- <p class="warning">
Collections with comparator functions will not automatically re-sort if you
later change model attributes, so you may wish to call <tt>sort</tt> after
changing model attributes that would affect the order.
@@ -1410,7 +1481,9 @@ <h2 id="Collection">Backbone.Collection</h2>
the array of model attributes to be <a href="#Collection-add">added</a>
to the collection. The default implementation is a no-op, simply passing
through the JSON response. Override this if you need to work with a
- preexisting API, or better namespace your responses.
+ preexisting API, or better namespace your responses. Note that afterwards,
+ if your model class already has a <tt>parse</tt> function, it will be
+ run against each fetched model.
</p>
<pre>
@@ -1509,6 +1582,13 @@ <h2 id="Collection">Backbone.Collection</h2>
The <b>create</b> method can accept either an attributes hash or an
existing, unsaved model object.
</p>
+
+ <p>
+ Creating a model will cause an immediate <tt>"add"</tt> event to be
+ triggered on the collection, as well as a <tt>"sync"</tt> event, once the
+ model has been successfully created on the server. Pass <tt>{wait: true}</tt>
+ if you'd like to wait for the server before adding the new model to the collection.
+ </p>
<pre>
var Library = Backbone.Collection.extend({
@@ -1608,7 +1688,7 @@ <h2 id="Router">Backbone.Router</h2>
</pre>
<pre>
-router.bind("route:help", function(page) {
+router.on("route:help", function(page) {
...
});
</pre>
@@ -1911,12 +1991,6 @@ <h2 id="View">Backbone.View</h2>
if specified. If not, <b>el</b> is an empty <tt>div</tt>.
</p>
- <p>
- You may assign <b>el</b> directly if the view is being
- created for an element that already exists in the DOM. Use either a
- reference to a real DOM element, or a css selector string.
- </p>
-
<pre class="runnable">
var ItemView = Backbone.View.extend({
tagName: 'li'
@@ -1932,6 +2006,35 @@ <h2 id="View">Backbone.View</h2>
alert(item.el + ' ' + body.el);
</pre>
+ <p id="View-$el">
+ <b class="header">$el</b><code>view.$el</code>
+ <br />
+ A cached jQuery (or Zepto) object for the view's element. A handy
+ reference instead of re-wrapping the DOM element all the time.
+ </p>
+
+<pre>
+view.$el.show();
+
+listView.$el.append(itemView.el);
+</pre>
+
+ <p id="View-setElement">
+ <b class="header">setElement</b><code>view.setElement(element)</code>
+ <br />
+ If you'd like to apply a Backbone view to a different DOM element, use
+ <b>setElement</b>, which will also create the cached <tt>$el</tt> reference
+ and move the view's delegated events from the old element to the new one.
+ </p>
+
+ <p id="View-attributes">
+ <b class="header">attributes</b><code>view.attributes</code>
+ <br />
+ A hash of attributes that will be set as HTML DOM element attributes on the
+ view's <tt>el</tt> (id, class, data-properties, etc.), or a function that
+ returns such a hash.
+ </p>
+
<p id="View-dollar">
<b class="header">$ (jQuery or Zepto)</b><code>view.$(selector)</code>
<br />
@@ -2027,6 +2130,8 @@ <h2 id="View">Backbone.View</h2>
for DOM events within a view.
If an <b>events</b> hash is not passed directly, uses <tt>this.events</tt>
as the source. Events are written in the format <tt>{"event selector": "callback"}</tt>.
+ The callback may be either the name of a method on the view, or a direct
+ function body.
Omitting the <tt>selector</tt> causes the event to be bound to the view's
root element (<tt>this.el</tt>). By default, <tt>delegateEvents</tt> is called
within the View's constructor for you, so if you have a simple <tt>events</tt>
@@ -2085,6 +2190,13 @@ <h2 id="View">Backbone.View</h2>
});
</pre>
+ <p id="View-undelegateEvents">
+ <b class="header">undelegateEvents</b><code>undelegateEvents()</code>
+ <br />
+ Removes all of the view's delegated events. Useful if you want to disable
+ or remove a view from the DOM temporarily.
+ </p>
+
<h2 id="Utility">Utility Functions</h2>
<p>
@@ -2738,13 +2850,14 @@ <h2 id="faq">F.A.Q.</h2>
see fit.
</p>
- <ul>
+ <ul class="small">
<li><b>"add"</b> (model, collection) &mdash; when a model is added to a collection. </li>
<li><b>"remove"</b> (model, collection) &mdash; when a model is removed from a collection. </li>
<li><b>"reset"</b> (collection) &mdash; when the collection's entire contents have been replaced. </li>
<li><b>"change"</b> (model, options) &mdash; when a model's attributes have changed. </li>
<li><b>"change:[attribute]"</b> (model, value, options) &mdash; when a specific attribute has been updated. </li>
<li><b>"destroy"</b> (model, collection) &mdash; when a model is <a href="#Model-destroy">destroyed</a>. </li>
+ <li><b>"sync"</b> (model, collection) &mdash; triggers whenever a model has been successfully synced to the server. </li>
<li><b>"error"</b> (model, collection) &mdash; when a model's validation fails, or a <a href="#Model-save">save</a> call fails on the server. </li>
<li><b>"route:[name]"</b> (router) &mdash; when one of a router's routes has matched. </li>
<li><b>"all"</b> &mdash; this special event fires for <i>any</i> triggered event, passing the event name as the first argument. </li>
@@ -2788,8 +2901,8 @@ <h2 id="faq">F.A.Q.</h2>
<b>Feel free to define your own events.</b> <a href="#Events">Backbone.Events</a>
is designed so that you can mix it in to any JavaScript object or prototype.
Since you can use any string as an event, it's often handy to bind
- and trigger your own custom events: <tt>model.bind("selected:true")</tt> or
- <tt>model.bind("editing")</tt>
+ and trigger your own custom events: <tt>model.on("selected:true")</tt> or
+ <tt>model.on("editing")</tt>
</p>
<p>
@@ -2821,7 +2934,7 @@ <h2 id="faq">F.A.Q.</h2>
initialize: function() {
this.messages = new Messages;
this.messages.url = '/mailbox/' + this.id + '/messages';
- this.messages.bind("reset", this.updateCounts);
+ this.messages.on("reset", this.updateCounts);
},
...
@@ -2974,9 +3087,9 @@ <h2 id="faq">F.A.Q.</h2>
initialize: function() {
var messages = this.collection;
- messages.bind("reset", this.render, this);
- messages.bind("add", this.addMessage, this);
- messages.bind("remove", this.removeMessage, this);
+ messages.on("reset", this.render, this);
+ messages.on("add", this.addMessage, this);
+ messages.on("remove", this.removeMessage, this);
}
});
@@ -3015,6 +3128,87 @@ <h2 id="faq">F.A.Q.</h2>
</p>
<h2 id="changelog">Change Log</h2>
+
+ <b class="header">0.9.0</b> &mdash; <small><i>Jan. 30, 2012</i></small> &mdash; <a href="https://github.com/documentcloud/backbone/compare/0.5.3...0.9.0">Diff</a><br />
+ <ul style="margin-top: 5px;">
+ <li>
+ Creating and destroying models with <tt>create</tt> and <tt>destroy</tt>
+ are now optimistic by default. Pass <tt>{wait: true}</tt> as an option
+ if you'd like them to wait for a successful server response to proceed.
+ </li>
+ <li>
+ Two new properties on views: <tt>$el</tt> &mdash; a cached jQuery (or Zepto)
+ reference to the view's element, and <tt>setElement</tt>, which should
+ be used instead of manually setting a view's <tt>el</tt>. It will
+ both set <tt>view.el</tt> and <tt>view.$el</tt> correctly, as well as
+ re-delegating events on the new DOM element.
+ </li>
+ <li>
+ When you don't know the key in advance, you may now call
+ <tt>model.set(key, value)</tt> as well as <tt>save</tt>.
+ </li>
+ <li>
+ Multiple models with the same <tt>id</tt> are no longer allowed in a
+ single collection.
+ </li>
+ <li>
+ Added a <tt>"sync"</tt> event, which triggers whenever a model's state
+ has been successfully synced with the server (create, save, destroy).
+ </li>
+ <li>
+ <tt>bind</tt> and <tt>unbind</tt> have been renamed to <tt>on</tt>
+ and <tt>off</tt> for clarity, following jQuery's lead.
+ The old names are also still supported.
+ </li>
+ <li>
+ A Backbone collection's <tt>comparator</tt> function may now behave
+ either like a <a href="http://underscorejs.org/#sortBy">sortBy</a>
+ (pass a function that takes a single argument),
+ or like a <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
+ (pass a comparator function that expects two arguments). The comparator
+ function is also now bound by default to the collection &mdash; so you
+ can refer to <tt>this</tt> within it.
+ </li>
+ <li>
+ A view's <tt>events</tt> hash may now also contain direct function
+ values as well as the string names of existing view methods.
+ </li>
+ <li>
+ Added <tt>shuffle</tt> and <tt>initial</tt> to collections, proxied
+ from Underscore.
+ </li>
+ <li>
+ <tt>Model#urlRoot</tt> may now be defined as a function as well as a
+ value.
+ </li>
+ <li>
+ <tt>View#attributes</tt> may now be defined as a function as well as a
+ value.
+ </li>
+ <li>
+ Calling <tt>fetch</tt> on a collection will now cause all fetched JSON
+ to be run through the collection's model's <tt>parse</tt> function, if
+ one is defined.
+ </li>
+ <li>
+ You may now tell a router to <tt>navigate(fragment, {replace: true})</tt>,
+ which will either use <tt>history.replaceState</tt> or
+ <tt>location.hash.replace</tt>, in order to change the URL without adding
+ a history entry.
+ </li>
+ <li>
+ Within a collection's <tt>add</tt> and <tt>remove</tt> events, the index
+ of the model being added or removed is now available as <tt>options.index</tt>.
+ </li>
+ <li>
+ Added an <tt>undelegateEvents</tt> to views, allowing you to manually
+ remove all configured event delegations.
+ </li>
+ <li>
+ Although you shouldn't be writing your routes with them in any case &mdash;
+ leading slashes (<tt>/</tt>) are now stripped from routes.
+ </li>
+ </ul>
<p>
<b class="header">0.5.3</b> &mdash; <small><i>August 9, 2011</i></small><br />
View
4 package.json
@@ -6,9 +6,9 @@
"author" : "Jeremy Ashkenas <jeremy@documentcloud.org>",
"contributors" : [],
"dependencies" : {
- "underscore" : ">=1.1.2"
+ "underscore" : ">=1.3.1"
},
"lib" : ".",
"main" : "backbone.js",
- "version" : "0.5.3"
+ "version" : "0.9.0"
}
Please sign in to comment.
Something went wrong with that request. Please try again.