lib/dojo/store/JsonRest.js

   1 /*
   2         Copyright (c) 2004-2011, The Dojo Foundation All Rights Reserved.
   3         Available via Academic Free License >= 2.1 OR the modified BSD license.
   4         see: http://dojotoolkit.org/license for details
   5 */
   6
   7
   8 if(!dojo._hasResource["dojo.store.JsonRest"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
   9 dojo._hasResource["dojo.store.JsonRest"] = true;
  10 dojo.provide("dojo.store.JsonRest");
  11 dojo.require("dojo.store.util.QueryResults");
  12
  13
  14 dojo.declare("dojo.store.JsonRest", null, {
  15         constructor: function(/*dojo.store.JsonRest*/ options){
  16                 // summary:
  17                 //              This is a basic store for RESTful communicating with a server through JSON
  18                 //              formatted data.
  19                 // options:
  20                 //              This provides any configuration information that will be mixed into the store
  21                 dojo.mixin(this, options);
  22         },
  23         // target: String
  24         //              The target base URL to use for all requests to the server. This string will be
  25         //      prepended to the id to generate the URL (relative or absolute) for requests
  26         //      sent to the server
  27         target: "",
  28         // idProperty: String
  29         //              Indicates the property to use as the identity property. The values of this
  30         //              property should be unique.
  31         idProperty: "id",
  32
  33         get: function(id, options){
  34                 //      summary:
  35                 //              Retrieves an object by its identity. This will trigger a GET request to the server using
  36                 //              the url `this.target + id`.
  37                 //      id: Number
  38                 //              The identity to use to lookup the object
  39                 //      returns: Object
  40                 //              The object in the store that matches the given id.
  41                 var headers = options || {};
  42                 headers.Accept = "application/javascript, application/json";
  43                 return dojo.xhrGet({
  44                         url:this.target + id,
  45                         handleAs: "json",
  46                         headers: headers
  47                 });
  48         },
  49         getIdentity: function(object){
  50                 // summary:
  51                 //              Returns an object's identity
  52                 // object: Object
  53                 //              The object to get the identity from
  54                 //      returns: Number
  55                 return object[this.idProperty];
  56         },
  57         put: function(object, options){
  58                 // summary:
  59                 //              Stores an object. This will trigger a PUT request to the server
  60                 //              if the object has an id, otherwise it will trigger a POST request.
  61                 // object: Object
  62                 //              The object to store.
  63                 // options: dojo.store.api.Store.PutDirectives?
  64                 //              Additional metadata for storing the data.  Includes an "id"
  65                 //              property if a specific id is to be used.
  66                 //      returns: Number
  67                 options = options || {};
  68                 var id = ("id" in options) ? options.id : this.getIdentity(object);
  69                 var hasId = typeof id != "undefined";
  70                 return dojo.xhr(hasId && !options.incremental ? "PUT" : "POST", {
  71                                 url: hasId ? this.target + id : this.target,
  72                                 postData: dojo.toJson(object),
  73                                 handleAs: "json",
  74                                 headers:{
  75                                         "Content-Type": "application/json",
  76                                         "If-Match": options.overwrite === true ? "*" : null,
  77                                         "If-None-Match": options.overwrite === false ? "*" : null
  78                                 }
  79                         });
  80         },
  81         add: function(object, options){
  82                 // summary:
  83                 //              Adds an object. This will trigger a PUT request to the server
  84                 //              if the object has an id, otherwise it will trigger a POST request.
  85                 // object: Object
  86                 //              The object to store.
  87                 // options: dojo.store.api.Store.PutDirectives?
  88                 //              Additional metadata for storing the data.  Includes an "id"
  89                 //              property if a specific id is to be used.
  90                 options = options || {};
  91                 options.overwrite = false;
  92                 return this.put(object, options);
  93         },
  94         remove: function(id){
  95                 // summary:
  96                 //              Deletes an object by its identity. This will trigger a DELETE request to the server.
  97                 // id: Number
  98                 //              The identity to use to delete the object
  99                 return dojo.xhrDelete({
 100                         url:this.target + id
 101                 });
 102         },
 103         query: function(query, options){
 104                 // summary:
 105                 //              Queries the store for objects. This will trigger a GET request to the server, with the
 106                 //              query added as a query string.
 107                 // query: Object
 108                 //              The query to use for retrieving objects from the store.
 109                 // options: dojo.store.api.Store.QueryOptions?
 110                 //              The optional arguments to apply to the resultset.
 111                 //      returns: dojo.store.api.Store.QueryResults
 112                 //              The results of the query, extended with iterative methods.
 113                 var headers = {Accept: "application/javascript, application/json"};
 114                 options = options || {};
 115
 116                 if(options.start >= 0 || options.count >= 0){
 117                         headers.Range = "items=" + (options.start || '0') + '-' +
 118                                 (("count" in options && options.count != Infinity) ?
 119                                         (options.count + (options.start || 0) - 1) : '');
 120                 }
 121                 if(dojo.isObject(query)){
 122                         query = dojo.objectToQuery(query);
 123                         query = query ? "?" + query: "";
 124                 }
 125                 if(options && options.sort){
 126                         query += (query ? "&" : "?") + "sort(";
 127                         for(var i = 0; i<options.sort.length; i++){
 128                                 var sort = options.sort[i];
 129                                 query += (i > 0 ? "," : "") + (sort.descending ? '-' : '+') + encodeURIComponent(sort.attribute);
 130                         }
 131                         query += ")";
 132                 }
 133                 var results = dojo.xhrGet({
 134                         url: this.target + (query || ""),
 135                         handleAs: "json",
 136                         headers: headers
 137                 });
 138                 results.total = results.then(function(){
 139                         var range = results.ioArgs.xhr.getResponseHeader("Content-Range");
 140                         return range && (range=range.match(/\/(.*)/)) && +range[1];
 141                 });
 142                 return dojo.store.util.QueryResults(results);
 143         }
 144 });
 145
 146 }