[Pkg-javascript-commits] [backbone] 83/101: documenting id and cid
Jonas Smedegaard
js at moszumanska.debian.org
Sat May 3 16:58:31 UTC 2014
This is an automated email from the git hooks/post-receive script.
js pushed a commit to tag 0.1.0
in repository backbone.
commit a72920d35515169254285a601df0751a41b5bbe1
Author: Jeremy Ashkenas <jashkenas at gmail.com>
Date: Tue Oct 12 23:56:26 2010 -0400
documenting id and cid
---
index.html | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 86 insertions(+), 17 deletions(-)
diff --git a/index.html b/index.html
index af96b76..5928844 100644
--- a/index.html
+++ b/index.html
@@ -150,6 +150,8 @@
<li>– <a href="#Model-get">get</a></li>
<li>– <a href="#Model-set">set</a></li>
<li>– <a href="#Model-unset">unset</a></li>
+ <li>– <a href="#Model-id">id</a></li>
+ <li>– <a href="#Model-cid">cid</a></li>
<li>– <a href="#Model-attributes">attributes</a></li>
<li>– <a href="#Model-save">save</a></li>
<li>– <a href="#Model-destroy">destroy</a></li>
@@ -224,7 +226,9 @@
<p>
<i>
Backbone is an open-source component of
- <a href="http://documentcloud.org/">DocumentCloud</a>.
+ <a href="http://documentcloud.org/">DocumentCloud</a>.<br />
+ Special thanks to <a href="http://github.com/broofa">Robert Kieffer</a>
+ for inspiring the ideas behind this library.
</i>
</p>
@@ -270,11 +274,11 @@
With Backbone, you represent your data as
<a href="#Model">Models</a>, which can be created, validated, destroyed,
and saved to the server. Whenever a UI action causes an attribute of
- a model to change, the model triggers a <i>change</i> event, and all
- the <a href="#View">Views</a> that are displaying the model's data are
- notified, causing them to re-render. You don't have to write the glue
+ a model to change, the model triggers a <i>"change"</i> event; all
+ the <a href="#View">Views</a> that reference the model's data receive the
+ event, causing them to re-render. You don't have to write the glue
code that looks into the DOM to find an element with a specific <i>id</i>,
- and update the HTML contents
+ and update the HTML manually
— when the model changes, the views simply update themselves.
</p>
@@ -292,9 +296,17 @@
for comparsion. SproutCore and Cappuccino provide rich UI widgets, vast
core libraries, and determine the structure of your HTML for you.
Loading the "Hello World" of SproutCore includes <i>2.5 megabytes</i> of JavaScript on the
- page; the "Hello World" of Cappuccino includes <i>1.7 megabytes</i> of JS and images.
- Backbone is a <i>2 kilobyte</i> include that provides just the core concepts of
- models, events (key-value binding), collections, views, and persistence.
+ page; the "Hello World" of Cappuccino includes <i>1.7 megabytes</i> of JS and images,
+ as measured with the Webkit inspector.
+ Backbone is a <i>2 kilobyte</i> include (packed, gzipped) that provides
+ just the core concepts of models, events (key-value binding), collections,
+ views, and persistence. A much closer relative to Backbone is
+ <a href="http://benpickles.github.com/js-model/">js-model</a>.
+ </p>
+
+ <p>
+ Many of the examples that follow are runnable. Click the <i>play</i> button
+ to execute them.
</p>
<h2 id="Events">Backbone.Events</h2>
@@ -307,27 +319,38 @@
</p>
<pre class="runnable">
-var obj = {};
+var object = {};
-_.extend(obj, Backbone.Events);
+_.extend(object, Backbone.Events);
-obj.bind("alert", function(msg) {
+object.bind("alert", function(msg) {
alert("Triggered " + msg);
});
-obj.trigger("alert", "an event");
+object.trigger("alert", "an event");
</pre>
<p id="Events-bind">
<b class="header">bind</b><code>object.bind(event, callback)</code>
<br />
Bind a <b>callback</b> function to an object. The callback will be invoked
- whenever the <b>event</b> (specified by a string identifier) is fired.
+ whenever the <b>event</b> (specified by an arbitrary string identifier) is fired.
If you have many events on a page, the convention is to use colons to
- namespace them: <tt>"poll:start"</tt>. Callbacks bound to the special
+ namespace them: <tt>"poll:start"</tt>.
+ </p>
+
+ <p>
+ Callbacks bound to the special
<tt>"all"</tt> event will be triggered when any event occurs, and are passed
- the name of the event as the first argument.
+ the name of the event as the first argument. For example, to proxy all events
+ from one object to another:
</p>
+
+<pre>
+object.bind("all", function(eventName) {
+ proxy.trigger(eventName);
+});
+</pre>
<p id="Events-unbind">
<b class="header">unbind</b><code>object.unbind([event], [callback])</code>
@@ -337,6 +360,14 @@ obj.trigger("alert", "an event");
removed. If no event is specified, all bound callbacks on the object
will be removed.
</p>
+
+<pre>
+object.unbind("change", onChange); // Removes just the onChange callback.
+
+object.unbind("change"); // Removes all "change" callbacks.
+
+object.unbind(); // Removes all callbacks on object.
+</pre>
<p id="Events-trigger">
<b class="header">trigger</b><code>object.trigger(event, [*args])</code>
@@ -357,8 +388,9 @@ obj.trigger("alert", "an event");
<p>
The following is a contrived example, but it demonstrates defining a model
- with a custom method, setting an attribute, and firing an event when the
- model changes. After running this code once, <tt>sidebar</tt> will be
+ with a custom method, setting an attribute, and firing an event when a
+ specific property of the model changes.
+ After running this code once, <tt>sidebar</tt> will be
available in your browser's console, so you can play around with it.
</p>
@@ -388,6 +420,23 @@ sidebar.promptColor();
and provide instance <b>properties</b>, as well as optional properties to be attached
directly to the constructor function.
</p>
+
+ <p>
+ <b>extend</b> correctly sets up the prototype chain, so subclasses created
+ with <b>extend</b> can be further extended and subclassed as far as you like.
+ </p>
+
+<pre>
+var Note = Backbone.Model.extend({
+
+ author: function() { ... },
+
+ allowedToEdit: function(account) { ... },
+
+ coordinates: function() { ... }
+
+});
+</pre>
<p id="Model-get">
<b class="header">get</b><code>model.get(attribute)</code>
@@ -421,6 +470,26 @@ note.set({title: "October 31"}, {silent: true});
Remove an attribute by deleting it from the internal attributes hash.
Fires a <tt>"change"</tt> event unless <tt>silent</tt> is passed as an option.
</p>
+
+ <p id="Model-id">
+ <b class="header">id</b><code>model.id</code>
+ <br />
+ A special property of models, the <b>id</b> is an arbitrary string
+ (integer id or UUID). If you set the <b>id</b> in the
+ attributes hash, it will be copied onto the model as a direct property.
+ Models can be retrieved by id from collections, and the id is used to generate
+ model URLs by default.
+ </p>
+
+ <p id="Model-cid">
+ <b class="header">cid</b><code>model.cid</code>
+ <br />
+ A special property of models, the <b>cid</b> or client id is a unique identifier
+ automatically assigned to all models when they're first created. Client ids
+ are handy when the model has not yet been saved to the server, and does not
+ yet have its eventual true <b>id</b>, but already needs to be visible in the UI.
+ Client ids take the form: <tt>c1, c2, c3 ...</tt>
+ </p>
<p id="Model-attributes">
<b class="header">attributes</b><code>model.attributes()</code>
--
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