[Pkg-javascript-commits] [backbone] 07/211: Adding an FAQ section to the backbone docs.
Jonas Smedegaard
js at moszumanska.debian.org
Sat May 3 16:59:57 UTC 2014
This is an automated email from the git hooks/post-receive script.
js pushed a commit to tag 0.5.0
in repository backbone.
commit 3246463d3bbafda57e6b0bcdc3d8ac652354bab9
Author: Jeremy Ashkenas <jashkenas at gmail.com>
Date: Mon Dec 6 11:32:30 2010 -0500
Adding an FAQ section to the backbone docs.
---
index.html | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 136 insertions(+), 25 deletions(-)
diff --git a/index.html b/index.html
index 25a9462..df6000f 100644
--- a/index.html
+++ b/index.html
@@ -263,6 +263,17 @@
Examples
</a>
+ <a class="toc_title" href="#faq">
+ F.A.Q.
+ </a>
+ <ul class="toc_section">
+ <li>– <a href="#FAQ-events">Catalog of Events</a></li>
+ <li>– <a href="#FAQ-nested">Nested Models & Collections</a></li>
+ <li>– <a href="#FAQ-mvc">Traditional MVC</a></li>
+ <li>– <a href="#FAQ-this">Binding "this"</a></li>
+ <li>- <a href="#FAQ-rias">Other RIA Frameworks</a></li>
+ </ul>
+
<a class="toc_title" href="#changelog">
Change Log
</a>
@@ -355,27 +366,6 @@
</p>
<p>
- <i>How is this different than
- <a href="http://www.sproutcore.com/">SproutCore</a> or
- <a href="http://cappuccino.org/">Cappuccino</a>?
- </i>
- </p>
-
- <p>
- This question is frequently asked, and all three projects apply general
- <a href="http://en.wikipedia.org/wiki/Model–View–Controller">Model-View-Controller</a>
- principles to JavaScript applications. However, there isn't much basis
- for comparison. SproutCore and Cappuccino provide rich UI widgets, vast
- core libraries, and determine the structure of your HTML for you.
- Both frameworks measure in the hundreds of kilobytes when packed and
- gzipped, and megabytes of JavaScript, CSS, and images when loaded in the browser
- — there's a lot of room underneath for libraries of a more moderate scope.
- Backbone is a <i>4 kilobyte</i> include that provides
- just the core concepts of models, events, collections, views, controllers,
- and persistence.
- </p>
-
- <p>
Many of the examples that follow are runnable. Click the <i>play</i> button
to execute them.
</p>
@@ -550,16 +540,16 @@ new Book({
Get the current value of an attribute from the model. For example:
<tt>note.get("title")</tt>
</p>
-
+
<p id="Model-escape">
<b class="header">escape</b><code>model.escape(attribute)</code>
<br />
Similar to <a href="#Model-get">get</a>, but returns the HTML-escaped version
of a model's attribute. If you're interpolating data from the model into
- HTML, using <b>escape</b> to retrieve attributes will prevent
+ HTML, using <b>escape</b> to retrieve attributes will prevent
<a href="http://en.wikipedia.org/wiki/Cross-site_scripting">XSS</a> attacks.
</p>
-
+
<pre class="runnable">
var hacker = new Backbone.Model({
name: "<script>alert('xss')</script>"
@@ -1833,6 +1823,127 @@ var DocumentView = Backbone.View.extend({
</a>
</div>
+ <h2 id="faq">F.A.Q.</h2>
+
+ <p id="FAQ-events">
+ <b class="header">Catalog of Events</b>
+ <br />
+ Here's a list of all of the built-in events that Backbone.js can fire.
+ You're also free to trigger your own events on Models and Views as you
+ see fit.
+ </p>
+
+ <ul>
+ <li><b>"add"</b> (model, collection) — when a model is added to a collection. </li>
+ <li><b>"remove"</b> (model, collection) — when a model is removed from a collection. </li>
+ <li><b>"refresh"</b> (collection) — when the collection's entire contents have been replaced. </li>
+ <li><b>"change"</b> (model, collection) — when a model's attributes have changed. </li>
+ <li><b>"change:[attribute]"</b> (model, collection) — when a specific attribute has been updated. </li>
+ <li><b>"error"</b> (model, collection) — 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> (controller) — when one of a controller's routes has matched. </li>
+ <li><b>"all"</b> — this special event fires for <i>any</i> triggered event, passing the event name as the first argument. </li>
+ </ul>
+
+ <p id="FAQ-nested">
+ <b class="header">Nested Models & Collections</b>
+ <br />
+ It's common to nest collections inside of models with Backbone. For example,
+ consider a <tt>Mailbox</tt> model that contains many <tt>Message</tt> models.
+ One nice pattern for handling this is have a <tt>this.messages</tt> collection
+ for each mailbox, enabling the lazy-loading of messages, when the mailbox
+ is first opened ... perhaps with <tt>MessageList</tt> views listening for
+ <tt>"add"</tt> and <tt>"remove"</tt> events.
+ </p>
+
+<pre>
+var Mailbox = Backbone.Model.extend({
+
+ initialize: function() {
+ this.messages = new Messages;
+ this.messages.url = '/mailbox/' + this.id + '/messages';
+ this.messages.bind("refresh", this.updateCounts);
+ },
+
+ ...
+
+});
+
+var Inbox = new Mailbox;
+
+// And then, when the Inbox is opened:
+
+Inbox.messages.fetch();
+</pre>
+
+ <p id="FAQ-mvc">
+ <b class="header">How does Backbone relate to "traditional" MVC?</b>
+ <br />
+ Different implementations of the
+ <a href="http://en.wikipedia.org/wiki/Model–View–Controller">Model-View-Controller</a>
+ pattern tend to disagree about the definition of a controller. If it helps any, in
+ Backbone, the <a href="#View">View</a> class can also be thought of as a
+ kind of controller, dispatching events that originate from the UI, with
+ the HTML template serving as the true view. We call it a View because it
+ represents a logical chunk of UI, responsible for the contents of a single
+ DOM element.
+ </p>
+
+ <p id="FAQ-this">
+ <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, it's 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://documentcloud.github.com/underscore/#bind">_.bind</a> and
+ <a href="http://documentcloud.github.com/underscore/#bindAll">_.bindAll</a>
+ from Underscore.js. <tt>_.bind</tt> takes a function and an object to be
+ used as <tt>this</tt>, any time the function is called in the future.
+ <tt>_.bindAll</tt> takes an object and a list of method names: each method
+ in the list will be bound to the object, so that it's <tt>this</tt> may
+ not change. For example, in a <a href="#View">View</a> that listens for
+ changes to a collection...
+ </p>
+
+<pre>
+var MessageList = Backbone.View.extend({
+
+ initialize: function() {
+ _.bindAll(this, "addMessage", "removeMessage", "render");
+
+ var messages = this.collection;
+ messages.bind("refresh", this.render);
+ messages.bind("add", this.addMessage);
+ messages.bind("remove", this.removeMessage);
+ }
+
+});
+
+// Later, in the app...
+
+Inbox.messages.add(newMessage);
+</pre>
+
+ <p id="FAQ-rias">
+ <b class="header">
+ How is Backbone different than
+ <a href="http://www.sproutcore.com/">SproutCore</a> or
+ <a href="http://cappuccino.org/">Cappuccino</a>?
+ </b>
+ <br />
+ This question is frequently asked, and all three projects apply general
+ <a href="http://en.wikipedia.org/wiki/Model–View–Controller">Model-View-Controller</a>
+ principles to JavaScript applications. However, there isn't much basis
+ for comparison. SproutCore and Cappuccino provide rich UI widgets, vast
+ core libraries, and determine the structure of your HTML for you.
+ Both frameworks measure in the hundreds of kilobytes when packed and
+ gzipped, and megabytes of JavaScript, CSS, and images when loaded in the browser
+ — there's a lot of room underneath for libraries of a more moderate scope.
+ Backbone is a <i>4 kilobyte</i> include that provides
+ just the core concepts of models, events, collections, views, controllers,
+ and persistence.
+ </p>
+
<h2 id="changelog">Change Log</h2>
<p>
@@ -1841,7 +1952,7 @@ var DocumentView = Backbone.View.extend({
jQuery, as a framework for DOM manipulation and Ajax support.
Implemented <a href="#Model-escape">Model#escape</a>, to efficiently handle
attributes intended for HTML interpolation. When trying to persist a model,
- failed requests will now trigger an <tt>"error"</tt> event. The
+ failed requests will now trigger an <tt>"error"</tt> event. The
ubiquitous <tt>options</tt> argument is now passed as the final argument
to all <tt>"change"</tt> events.
</p>
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/backbone.git
More information about the Pkg-javascript-commits
mailing list