lib/dojo/store/JsonRest.js.uncompressed.js

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