      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