github/backbone
1
1
Fork 0
mirror of https://github.com/jashkenas/backbone.git synced 2026-04-30 03:00:06 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2854 from akre54/bindall-docs

Browse Source 
Clarify bindAll and events hash `this` binding in FAQ section
This commit is contained in:
Jeremy Ashkenas
2013-11-06 10:33:01 -08:00
parent bd662597ca a5e6326f46
commit 00d27824ad
1 changed files with 42 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
index.html
View File

@@ -624,7 +624,7 @@
of data-structuring (models and collections) and user interface (views
and URLs) primitives that are generally useful when building web applications with
JavaScript. In an ecosystem where overarching, decides-everything-for-you
frameworks are commonplace, and many libraries require your site to be
frameworks are commonplace, and many libraries require your site to be
reorganized to suit their look, feel, and default behavior — Backbone should
continue to be a tool that gives you the <i>freedom</i> to design the full
experience of your web application.
@@ -679,11 +679,11 @@
</li>
<li>
In 1.1, Backbone Views no longer have the <tt>options</tt> argument
attached as <tt>this.options</tt> automatically. Feel free to continue
attached as <tt>this.options</tt> automatically. Feel free to continue
attaching it if you like.
</li>
<li>
In 1.1, The <b>Collection</b> methods <tt>add</tt>, <tt>remove</tt>,
In 1.1, The <b>Collection</b> methods <tt>add</tt>, <tt>remove</tt>,
<tt>set</tt>, <tt>push</tt>, and <tt>shift</tt> now return the model
(or models) added or removed from the collection.
</li>
@@ -1015,7 +1015,7 @@ var Library = Backbone.Model.extend({
collection the model belongs to, and is used to help compute the model's
<a href="#Model-url">url</a>. The <tt>model.collection</tt> property is
normally created automatically when you first add a model to a collection.
Note that the reverse is not true, as passing this option to the constructor
Note that the reverse is not true, as passing this option to the constructor
will not automatically add the model to the collection. Useful, sometimes.
</p>
@@ -1774,7 +1774,7 @@ ships.add([
<p id="Collection-remove">
<b class="header">remove</b><code>collection.remove(models, [options])</code>
<br />
Remove a model (or an array of models) from the collection, and returns them.
Remove a model (or an array of models) from the collection, and returns them.
Fires a <tt>"remove"</tt> event, which you can use <tt>silent</tt> to suppress.
The model's index before removal is available to listeners as
<tt>options.index</tt>.
@@ -2645,9 +2645,9 @@ ui.Chapter = Backbone.View.extend({
<b class="header">template</b><code>view.template([data])</code>
<br />
While templating for a view isn't a function provided directly by Backbone,
it's often a nice convention to define a <b>template</b> function on your
it's often a nice convention to define a <b>template</b> function on your
views. In this way, when rendering your view, you have convenient access to
instance data.
instance data.
For example, using Underscore templates:
</p>
@@ -3089,13 +3089,13 @@ var model = localBackbone.Model.extend(...);
<h2 id="examples-delicious">Delicious</h2>
<p>
<a href="https://delicious.com/">Delicious</a> is a social bookmarking
platform making it easy to save, sort, and store bookmarks from across
the web. Delicious uses <a href="http://chaplinjs.org">Chaplin.js</a>,
Backbone.js and AppCache to build a full-featured MVC web app.
The use of Backbone helped the website and
<a href="http://delicious.com/tools">mobile apps</a> share a
single API service, and the reuse of the model tier made it significantly
<a href="https://delicious.com/">Delicious</a> is a social bookmarking
platform making it easy to save, sort, and store bookmarks from across
the web. Delicious uses <a href="http://chaplinjs.org">Chaplin.js</a>,
Backbone.js and AppCache to build a full-featured MVC web app.
The use of Backbone helped the website and
<a href="http://delicious.com/tools">mobile apps</a> share a
single API service, and the reuse of the model tier made it significantly
easier to share code during the recent Delicious redesign.
</p>
@@ -3941,18 +3941,30 @@ inbox.messages.fetch({reset: true});
<b class="header">Binding "this"</b>
<br />
Perhaps the single most common JavaScript "gotcha" is the fact that when
you pass a function as a callback, its value for <tt>this</tt> is lost. With
Backbone, when dealing with <a href="#Events">events</a> and callbacks,
you'll often find it useful to rely on
<a href="http://underscorejs.org/#bind">_.bind</a> and
<a href="http://underscorejs.org/#bindAll">_.bindAll</a>
from Underscore.js.
</p>
you pass a function as a callback, its value for <tt>this</tt> is lost.
When dealing with <a href="#Events">events</a> and callbacks in Backbone,
you'll often find it useful to rely on <a href="#Events-listenTo">listenTo</a>
or the optional <tt>context</tt> argument that many of Underscore
and Backbone's methods use to specify the <tt>this</tt>
that will be used when the callback is later invoked. (See
<a href="http://underscorejs.org/#each">_.each</a>,
<a href="http://underscorejs.org/#map">_.map</a>, and
<a href="#Events-on">object.on</a>, to name a few).
<a href="#View-delegateEvents">View events</a> are automatically bound to
the view's context for you.
<p>
<p>
When binding callbacks to Backbone events, you can choose to pass an optional
third argument to specify the <tt>this</tt> that will be used when the
callback is later invoked:
You may also find it helpful to use
<a href="http://underscorejs.org/#bind">_.bind</a> and
<a href="http://underscorejs.org/#bindAll">_.bindAll</a>
from Underscore.js. Be aware, however, that due to an imperfect shim in older
browsers, the bound function's <em>arity</em> (that is, its <tt>length</tt>
property) is not preserved when a native <tt>bind</tt> is not present.
This is known to cause problems with <tt>constructor</tt> and collection
<a href="#Collection-comparator"><tt>comparator</tt></a>
functions bound from within the object instance and this pattern is
highly discouraged for this reason.
</p>
<pre>
@@ -3963,6 +3975,8 @@ var MessageList = Backbone.View.extend({
messages.on("reset", this.render, this);
messages.on("add", this.addMessage, this);
messages.on("remove", this.removeMessage, this);
messsages.each(this.addMessage, this);
}
});
@@ -4006,13 +4020,13 @@ ActiveRecord::Base.include_root_in_json = false
<b class="header">1.1.0</b> &mdash; <small><i>Oct. 10, 2013</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/1.0.0...1.1.0">Diff</a> &mdash; <a href="http://htmlpreview.github.com/?https://raw.github.com/jashkenas/backbone/1.1.0/index.html">Docs</a><br />
<ul style="margin-top: 5px;">
<li>
Made the return values of Collection's <tt>set</tt>, <tt>add</tt>,
Made the return values of Collection's <tt>set</tt>, <tt>add</tt>,
<tt>remove</tt>, and <tt>reset</tt> more useful. Instead of returning
<tt>this</tt>, they now return the changed (added, removed or updated)
<tt>this</tt>, they now return the changed (added, removed or updated)
model or list of models.
</li>
<li>
Backbone Views no longer automatically attach options passed to the constructor as
Backbone Views no longer automatically attach options passed to the constructor as
<tt>this.options</tt>, but you can do it yourself if you prefer.
</li>
<li>
@@ -4028,7 +4042,7 @@ ActiveRecord::Base.include_root_in_json = false
and vivify incoming nested JSON into associated submodels.
</li>
<li>
Many tweaks, optimizations and bugfixes relating to Backbone 1.0,
Many tweaks, optimizations and bugfixes relating to Backbone 1.0,
including URL overrides, mutation of options, bulk ordering, trailing
slashes, edge-case listener leaks, nested model parsing...
</li>