Request / Ajax

API
Shorthand Methods

get()
post()
json()
postJSON()

Request Setup
Original Request Parameters

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

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

parameters - object - Request parameters

Returns promise that will be resolved with response data and rejected in case of error.

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

parameters - object - Request parameters

Returns promise that will be resolved with response data and rejected in case of error.

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 This callback is not available with promise API
success	function (data, status, xhr)		A function to be called if the request succeeds This callback is not available with promise API
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

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

Returns promise that will be resolved with response data and rejected in case of error.

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

Returns promise that will be resolved with response data and rejected in case of error.

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');
});

/* Or with promise API */
app.request.promise.get('blog-post.php', { foo: 'bar', id:5 })
  .then(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

app.request.promise.post(url, data, dataType)- Load data from the server using a HTTP GET request

Returns promise that will be resolved with response data and rejected in case of error.

Framework7.request.promise.post(url, data, dataType)- Load data from the server using a HTTP GET request

Returns promise that will be resolved with response data and rejected in case of error.

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');
});

/* or with promise API */
app.request.promise.post('auth.php', { username:'foo', password: 'bar' })
  .then(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

app.request.promise.json(url, data)- Load data from the server using a HTTP GET request

Returns promise that will be resolved with response data and rejected in case of error.

Framework7.request.promise.json(url, data)- Load data from the server using a HTTP GET request

Returns promise that will be resolved with response data and rejected in case of error.

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);
});

/* or with promise API */
app.request.promise.json('users.json')
  .then(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

app.request.promise.postJSON(url, data, dataType)- Load data from the server using a HTTP GET request

Returns promise that will be resolved with response data and rejected in case of error.

Framework7.request.promise.postJSON(url, data, dataType)- Load data from the server using a HTTP GET request

Returns promise that will be resolved with response data and rejected in case of error.

For example:

var app = new Framework7();

var $$ = Dom7;

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

/* or with promise API */
app.request.promise.postJSON('http://api.myapp.com', { username:'foo', password: 'bar' })
  .then(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