Request / Ajax

    Framework7 comes with handy Request library to work with XHR requests (Ajax) right from the box.

    It is available as a request property of Framework7 class (Framework7.request) and same property on initialized app instance (app.request):

    // If we need it in place where we don't have access to app instance or before we init the app
    Framework7.request.get('somepage.html', function (data) {
      console.log(data);
    });
    
    
    // After we init the app we can access it as app instance property
    var app = new Framework7({ /*...*/ });
    
    app.request.get('somepage.html', function (data) {
      console.log(data);
    });

    API

    app.request(parameters)- Load data from the server

    • parameters - object - Request parameters

    Returns plain XHR object

    Framework7.request(parameters)- Load data from the server

    • parameters - object - Request parameters

    Returns plain XHR object

    Let's look at the list of available parameters

    Parameter Type Default Description
    url string Request url
    async boolean true If you need synchronous requests, set this option to false
    method string GET Request method (e.g. "POST", "GET", "PUT")
    cache boolean true If set to false, it will force requested pages not to be cached by the browser. Setting cache to false will only work correctly with HEAD and GET requests. It works by appending _nocache={timestamp} to the GET parameters
    contentType string application/x-www-form-urlencoded Content type. Also could be multipart/form-data or text/plain. For cross-domain requests, setting the content type to anything other than application/x-www-form-urlencoded, multipart/form-data, or text/plain will trigger the browser to send a preflight OPTIONS request to the server
    crossDomain boolean If you wish to force a crossDomain request (such as JSONP) on the same domain, set the value of crossDomain to true. When true additional X-Requested-With: XMLHttpRequest header will not be added to request. By default it will try to guess depending on app and request hosts
    data object
    string
    array
    Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests. See processData option to prevent this automatic processing. For POST requests could be FormData instance
    processData boolean true By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false
    dataType string text The type of data that you're expecting back from the server. Could be text or json
    headers object An object of additional header key/value pairs to send along with requests using the XMLHttpRequest transport. For example:
    xhrFields object An object of key/value pairs to set on the native XHR object
    username string A username to be used with XMLHttpRequest in response to an HTTP access authentication request
    password string A password to be used with XMLHttpRequest in response to an HTTP access authentication request
    timeout number 0 Set a timeout (in milliseconds) for the request
    Callbacks
    beforeCreate function (parameters) A pre-request callback function that can be used to modify passed parameters
    beforeOpen function (xhr, parameters) A pre-request callback function that will be called before XHR opened. Can be used to modify XHR object

    If you return false in this callback it will cancel the request

    beforeSend function (xhr) A pre-request callback function that will be called after XHR opened and before XHR send. Can be used to modify the XHR object before it is sent. Use this callback to set custom headers, etc.

    If you return false in this callback it will cancel the request

    error function (xhr, status) A function to be called if the request fails
    success function (data, status, xhr) A function to be called if the request succeeds
    complete function (xhr, status) A function to be called when the request finishes (after success and error callbacks are executed)
    statusCode object An object of numeric HTTP codes and functions to be called when the response has the corresponding code. For example, the following will alert when the response status is a 404:
    app.request({
      url: 'somepage.html',
      statusCode: {
        404: function (xhr) {
          alert('page not found');
        }
      }
    })
    

    Shorthand Methods

    Request comes with some pre configured methods for ease of use.

    Get

    app.request.get(url, data, success, error, dataType)- Load data from the server using a HTTP GET request

    • url - string - Request url
    • data - object - A plain object or string that is sent to the server with the request. Optional
    • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional
    • error - function (xhr, status) - A callback function that is executed if the request fails. Optional
    • dataType - string - The type of data that you're expecting back from the server. Could be text or json. Optional

    Returns plain XHR object

    Framework7.request.get(url, data, success, error, dataType)- Load data from the server using a HTTP GET request

    Returns plain XHR object

    For example:

    var app = new Framework7();
    
    var $$ = Dom7;
    
    app.request.get('blog-post.php', { foo:'bar', id:5 }, function (data) {
      $$('.articles').html(data);
      console.log('Load was performed');
    });

    Post

    app.request.post(url, data, success, error, dataType)- Load data from the server using a HTTP POST request

    • url - string - Request url
    • data - object - A plain object or FormData or string that is sent to the server with the request. Optional
    • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional
    • error - function (xhr, status) - A callback function that is executed if the request fails. Optional
    • dataType - string - The type of data that you're expecting back from the server. Could be text or json. Optional

    Returns plain XHR object

    Framework7.request.post(url, data, success, error, dataType)- Load data from the server using a HTTP POST request

    Returns plain XHR object

    For example:

    var app = new Framework7();
    
    var $$ = Dom7;
    
    app.request.post('auth.php', { username:'foo', password: 'bar' }, function (data) {
      $$('.login').html(data);
      console.log('Load was performed');
    });

    Json

    app.request.json(url, data, success, error)- Load JSON-encoded data from the server using a GET HTTP request

    • url - string - Request url
    • data - object - A plain object or FormData or string that is sent to the server with the request. Optional
    • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional
    • error - function (xhr, status) - A callback function that is executed if the request fails. Optional

    Method nothing returns

    Framework7.request.json(url, data, success, error)

    Method returns nothing

    For example:

    Framework7.request.json('items.json', function (data) {
      console.log(data);
    });
    
    var app = new Framework7();
    
    app.request.json('users.json', function (data) {
      console.log(data);
    });

    PostJSON

    app.request.postJSON(url, data, success, error, dataType)- Send JSON data using a HTTP POST request

    • url - string - Request url
    • data - object - A plain object
    • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional
    • error - function (xhr, status) - A callback function that is executed if the request fails. Optional
    • dataType - string - The type of data that you're expecting back from the server. Could be text or json. By default is json. Optional

    Returns plain XHR object

    Framework7.request.postJSON(url, data, success, error, dataType)- Send JSON data using a HTTP POST request

    Returns plain XHR object

    For example:

    var app = new Framework7();
    
    var $$ = Dom7;
    
    app.request.postJSON('http://api.myapp.com', { username:'foo', password: 'bar' }, function (data) {
      console.log(data);
    });

    Request Setup

    app.request.setup(parameters)- Set default values for future Ajax requests. Its use is not recommended

    • parameters - object - Default requests parameters

    Framework7.request.setup(parameters)- Set default values for future Ajax requests. Its use is not recommended

    For example:

    // After the following setup all XHR requests will have additional 'Autorization' header
    Framework7.request.setup({
      headers: {
        'Authorization': 'sometokenvalue'
      }
    })

    Original Request Parameters

    Each of request methods returns plain XHR object, which is also available in callbacks. This default XHR object is extended with the following properties:

    xhr.requestParameters Object with passed XHR request parameters
    xhr.requestUrl String with request URL