[Pkg-javascript-commits] [backbone] 19/211: documenting urlRoot ... making collection.url take precedence over urlRoot, if defined.

[Jonas Smedegaard]

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 81cd0cfd83c98fad787c3c1b18c31819c1b77915
Author: Jeremy Ashkenas <jashkenas at gmail.com>
Date:   Fri Dec 10 10:46:19 2010 -0500

    documenting urlRoot ... making collection.url take precedence over urlRoot, if defined.
---
 backbone.js | 11 ++++++++---
 index.html  | 34 +++++++++++++++++++++++-----------
 2 files changed, 31 insertions(+), 14 deletions(-)

diff --git a/backbone.js b/backbone.js
index 3276e07..15d888c 100644
--- a/backbone.js
+++ b/backbone.js
@@ -291,7 +291,7 @@
     // using Backbone's restful methods, override this to change the endpoint
     // that will be called.
     url : function() {
-      var base = this.urlRoot || getUrl(this.collection);
+      var base = getUrl(this.collection) || this.urlRoot || urlError();
       if (this.isNew()) return base;
       return base + (base.charAt(base.length - 1) == '/' ? '' : '/') + this.id;
     },
@@ -926,7 +926,7 @@
 
     // Default JSON-request options.
     var params = {
-      url:          getUrl(model),
+      url:          getUrl(model) || urlError(),
       type:         type,
       contentType:  'application/json',
       data:         modelJSON,
@@ -1004,10 +1004,15 @@
   // Helper function to get a URL from a Model or Collection as a property
   // or as a function.
   var getUrl = function(object) {
-    if (!(object && object.url)) throw new Error("A 'url' property or function must be specified");
+    if (!(object && object.url)) return null;
     return _.isFunction(object.url) ? object.url() : object.url;
   };
 
+  // Throw an error when a URL is needed, and none is supplied.
+  var urlError = function() {
+    throw new Error("A 'url' property or function must be specified");
+  };
+
   // Wrap an optional error callback with a fallback error event.
   var wrapError = function(onError, model, options) {
     return function(resp) {
diff --git a/index.html b/index.html
index 0d25ea7..fcaa50c 100644
--- a/index.html
+++ b/index.html
@@ -182,6 +182,7 @@
       <li>– <a href="#Model-destroy">destroy</a></li>
       <li>– <a href="#Model-validate">validate</a></li>
       <li>– <a href="#Model-url">url</a></li>
+      <li>– <a href="#Model-urlRoot">urlRoot</a></li>
       <li>– <a href="#Model-parse">parse</a></li>
       <li>– <a href="#Model-clone">clone</a></li>
       <li>– <a href="#Model-isNew">isNew</a></li>
@@ -699,13 +700,6 @@ setInterval(function() {
 }, 10000);
 </pre>
 
-    <p class="warning">
-      <b>Cautionary Note:</b> When fetching or saving a model, make sure that the model is part of
-      a collection with a <a href="#Collection-url">url</a> property specified,
-      or that the model itself has a complete <a href="#Model-url">url</a> function
-      of its own, so that the request knows where to go.
-    </p>
-
     <p id="Model-save">
       <b class="header">save</b><code>model.save(attributes, [options])</code>
       <br />
@@ -810,16 +804,34 @@ account.set({access: "unlimited"}, {
       <br />
       Returns the relative URL where the model's resource would be located on
       the server. If your models are located somewhere else, override this method
-      with the correct logic. Generates URLs of the form: <tt>"/[collection]/[id]"</tt>.
+      with the correct logic. Generates URLs of the form: <tt>"/[collection.url]/[id]"</tt>,
+      falling back to <tt>"/[urlRoot]/id"</tt> if the model is not part of a collection.
     </p>
 
     <p>
       Delegates to <a href="#Collection-url">Collection#url</a> to generate the
-      URL, so make sure that you have it defined.
+      URL, so make sure that you have it defined, or a <a href="#Model-urlRoot">urlRoot</a>
+      property, if all models of this class share a common root URL.
       A model with an id of <tt>101</tt>, stored in a
-      <a href="#Collection">Backbone.Collection</a> with a <tt>url</tt> of <tt>"/notes"</tt>,
-      would have this URL: <tt>"/notes/101"</tt>
+      <a href="#Collection">Backbone.Collection</a> with a <tt>url</tt> of <tt>"/documents/7/notes"</tt>,
+      would have this URL: <tt>"/documents/7/notes/101"</tt>
+    </p>
+    
+    <p id="Model-urlRoot">
+      <b class="header">urlRoot</b><code>model.urlRoot</code>
+      <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>
     </p>
+    
+<pre class="runnable">
+var Book = Backbone.Model.extend({urlRoot : '/books'});
+
+var solaris = new Book({id: "1083-lem-solaris"});
+
+alert(solaris.url());
+</pre>
 
     <p id="Model-parse">
       <b class="header">parse</b><code>model.parse(response)</code>

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/backbone.git