1 // ==========================================================================
  2 // Project:   The M-Project - Mobile HTML5 Application Framework
  3 // Copyright: �2010 M-Way Solutions GmbH. All rights reserved.
  4 // Creator:   Sebastian
  5 // Date:      28.10.2010
  6 // License:   Dual licensed under the MIT or GPL Version 2 licenses.
  7 //            http://github.com/mwaylabs/The-M-Project/blob/master/MIT-LICENSE
  8 //            http://github.com/mwaylabs/The-M-Project/blob/master/GPL-LICENSE
  9 // ==========================================================================
 10 
 11 m_require('core/foundation/object.js');
 12 
 13 /**
 14  * @class
 15  *
 16  * The root class for every request. Makes ajax requests. Is used e.g. for querying REST web services.
 17  * First M.Request.init needs to be called, then send.
 18  *
 19  * @extends M.Object
 20  */
 21 M.Request = M.Object.extend(
 22 /** @scope M.Request.prototype */ {
 23 
 24     /**
 25      * The type of this object.
 26      *
 27      * @type String
 28      */
 29     type: 'M.Request',
 30 
 31     /**
 32      * Initializes a request. Sets the parameter of this request object with the passed values.
 33      * 
 34      * @param {Object} obj The parameter object. Includes:
 35      * * method: the http method to use, e.g. 'POST'
 36      * * url: the request url, e.g. 'twitter.com/search.json' (needs a proxy to be set because of Same-Origin-Policy)
 37      * * isAsync: defines whether request should be made async or not. defaults to YES. Should be YES.
 38      * * isJSON: defines whether to process request and response as JSON
 39      * * timout: defines timeout in milliseconds
 40      * * data: the data to be transmitted
 41      * * beforeSend: callback that is called before request is sent
 42      * * onError: callback that is called when an error occured
 43      * * onSuccess: callback that is called when request was successful
 44      */
 45     init: function(obj){
 46         this.method = obj['method'] ? obj['method'] : this.method;
 47         this.url = obj['url'] ? obj['url'] : this.url;
 48         this.isAsync = obj['isAsync'] ? obj['isAsync'] : this.isAsync;
 49         this.isJSON = obj['isJSON'] ? obj['isJSON'] : this.isJSON;
 50         this.timeout = obj['timeout'] ? obj['timeout'] : this.timeout;
 51         this.data = obj['data'] ? obj['data'] : this.data;
 52         this.beforeSend = obj['beforeSend'] ? obj['beforeSend'] : this.beforeSend;
 53         this.onError = obj['onError'] ? obj['onError'] : this.onError;
 54         this.onSuccess = obj['onSuccess'] ? obj['onSuccess'] : this.onSuccess;
 55         return this;
 56     },
 57 
 58     /**
 59      * The HTTP method to use.
 60      *
 61      * Defaults to GET.
 62      *
 63      * @type String
 64      */
 65     method: 'GET',
 66 
 67     /**
 68      * The URL this request is sent to.
 69      *
 70      * @type String
 71      */
 72     url: null,
 73 
 74     /**
 75      * Sends the request asynchronously instead of blocking the browser.
 76      * You should almost always make requests asynchronous. �You can change this
 77      * options with the async() helper option (or simply set it directly).
 78      *
 79      * Defaults to YES.
 80      *
 81      * @type Boolean
 82      */
 83     isAsync: YES,
 84 
 85 
 86     /**
 87      * Processes the request and response as JSON if possible.
 88      *
 89      * Defaults to NO.
 90      *
 91      * @type Boolean
 92      */
 93     isJSON: NO,
 94 
 95     /**
 96      * Optional timeout value of the request in milliseconds.
 97      *
 98      * @type Number
 99      */
100     timeout: null,
101 
102     /**
103      * The data body of the request.
104      *
105      * @property {String, Object} 
106      */
107     data: null,
108 
109     /**
110      * A pre-callback that is called right before the request is sent.
111      *
112      * @param {Object} request The XMLHttpRequest object.
113      */
114     beforeSend: function(request){},
115 
116     /**
117      * The callback to be called if the request failed.
118      *
119      * @param {Object} request The XMLHttpRequest object.
120      * @param {String} msg The error message.
121      */
122     onError: function(request, msg){},
123 
124     /**
125      * The callback to be called if the request succeeded.
126      * @param {String, Object} data The data returned from the server.
127      * @param {String} msg A String describing the status.
128      * @param {Object} request The XMLHttpRequest object.
129      */
130     onSuccess: function(data, msg, request){},
131 
132 
133     /**
134      * Sends an Ajax request by using jQuery's $.ajax().
135      * Needs init first!
136      */
137     send: function(){
138         $.ajax({
139             type: this.method,
140             url: this.url,
141             async: this.isAsync,
142             dataType: this.isJSON ? 'json' : 'text',
143             timeout: this.timeout,
144             data: this.data ? this.data : '',
145             context: this,
146             beforeSend: this.beforeSend,
147             success: this.onSuccess,
148             error: this.onError
149         });
150     }
151 
152 });
153 
154