Skip to content

Commit

Permalink
documenting id and cid
Browse files Browse the repository at this point in the history
  • Loading branch information
@jashkenas
jashkenas committed Oct 13, 2010
1 parent 1fb2843 commit a72920d
Showing 1 changed file with 86 additions and 17 deletions.
103 changes: 86 additions & 17 deletions index.html
View file
Expand Up @@ -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>
Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -270,11 +274,11 @@ <h2 id="Introduction">Introduction</h2>
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
&mdash; when the model changes, the views simply update themselves.
</p>

Expand All @@ -292,9 +296,17 @@ <h2 id="Introduction">Introduction</h2>
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>
Expand All @@ -307,27 +319,38 @@ <h2 id="Events">Backbone.Events</h2>
</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>
Expand All @@ -337,6 +360,14 @@ <h2 id="Events">Backbone.Events</h2>
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>
Expand All @@ -357,8 +388,9 @@ <h2 id="Model">Backbone.Model</h2>

<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>

Expand Down Expand Up @@ -388,6 +420,23 @@ <h2 id="Model">Backbone.Model</h2>
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>
Expand Down Expand Up @@ -421,6 +470,26 @@ <h2 id="Model">Backbone.Model</h2>
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>
Expand Down

0 comments on commit a72920d

Please sign in to comment.