# AJAX

AJAX was the acronym for Asynchronous JavaScript And XML
In the meantime, the description of AJAX is already outdated because we can import not only XML, but also text, HTML, JSON and JavaScript
The $.ajax() method is jQuery's low-level AJAX implementation, and it's the counterpart of the fetch API in vanilla JS
$.ajax() is the most comprehensive, but also the most difficult method
Fortunately, there are also shorthand methods with fewer bells and whistles, but which are much easier to understand and use
The table below gives an overview of the most used methods with their capabilities and limitations

# AJAX methodes

jQuery AJAX methode	verb	dataType	remark
`$.ajax(url [,settings ])` (opens new window)	`GET`, `POST`, `PATCH/PUT`, `DELETE`	`json`, `xml`, `text`, `script`, `html`	perform an asynchronous HTTP (Ajax) request
`$.get(url [,data ] [,success ] [,dataType ])` (opens new window)	`GET`	`json`, `xml`, `text`, `script`, `html`	shorthand methode for `$.ajax()` with `GET` request
`$.getJSON(url [,data ] [,success ])` (opens new window)	`GET`	`json`	shorthand methode for `$.get()` with `GET` request and `JSON` as datatype
`$.post(url [,data ] [,success ] [,dataType ])` (opens new window)	`POST`	`json`, `xml`, `text`, `script`, `html`	shorthand methode for `$.ajax()` with `POST` request

$.ajax() can handle all the different HTTP verb methodes (opens new window) you can expect from a CRUD (Create, Read, Update and Delete)

verb (methode)	action	description
GET	read	get date from an API, database, ...
POST	create	post date to an API, add data to a database, ...
PATCH/PUT	update	update a record in the database, ...
DELETE	delete	delete a record from the database, ...

Every shorthand methode must have at least one parameter, the other parameters are optional
- url (required): the url that handels the get, post, patch/put or delete request
- data (optional): an object or string that is sent to the server with the request
- success (optional): a callback function that is executed if the request succeeds
- dataType (optional): the type of data expected from the server (if omitted, jQuery tries to guess the dataType)

TIP

Use jQuery's .serialize() (opens new window) methode to URL-encode all form elements for data submission. E.g.

$('form').submit(function(e) {
  e.preventDefault();
  const data = $(this).serialize();
  console.log('data', data);
});
 
        Copied!

1
2
3
4
5

# Chainable methodes

Every shorthand methode can be chained with so-called deferred objects (opens new window)
The most useful deferred objects (methodes) are:

methode	description
.done(cb [, cb]) (opens new window)	run one or more callback functions when the data is resolved
.catch(cb) (opens new window)	run a callback function when the data is rejected
.fail(cb [, cb]) (opens new window)	run one or more callback functions when the data is rejected
.then(resolveCb [, rejectCb] [, progressCb]) (opens new window)	run one or more callback functions when the data is resolved, rejected, or still in progress
.always(cb [, cb]) (opens new window)	run one or more callback functions when the data is resolved or rejected

REMARKS

As soon as you receive data from e.g. an API (resolved state), you can process this data in the default callback function of the AJAX methode or in one or more done() or then() methodes
Any errors (rejected state) can be intercepted with both catch() or fail()
.always() is a very handy methode to hide e.g. a preloader because this methode runs both after a resolved state or after a rejected state
The .then() method accepts a resolved and a rejected callback and is equivalent to using done/fail together, such that:

$.ajax().then(resolveCb, rejectCb);
// is equivalent to
$.ajax().then(resolveCb, rejectCb);
 
        Copied!

1
2
3

# Basic HTTP verbs

To demonstrate a very basic example of the different verbs, we use the https://reqres.in/ (opens new window) API
This is a fake API where the create, update and delete actions are not actually taking place, but the response 'fakes' this is really happens

# GET

Use the $.getJSON() (recommended), $.get() or $.ajax() (the hard way) methode to retrieve JSON data from an API or from a database
Open jquery/ajax/get.html and jquery/ajax/get.js
This example gets all the users on page 2 with this URL: https://reqres.in/api/users?page=2 (opens new window)
We are only interested in the key data witch contains an array of six users

<div class="border-gray row" id="users"></div>
 
        Copied!

$.getJSON() is by far the simplest and therefore the most recommended method of retrieving JSON data
Line 8: In this version, we use the default callback function to get all the users and add them to the page
Line 25: the cache() methode is only triggered when the API sends an error or when the URL is not accessible
(Change const url temporary to a non-existing URL to trigger the catch() methode)
Line 28: the .always() methode runs always

const url = 'https://reqres.in/api/users';

const pars = {
    page: 2,
};

// version 1: $.getJson() with default callback function
$.getJSON(url, pars, function (users) {
    console.log('users', users);
    let cards = '';
    // users.data[] contains 6 users
    users.data.forEach((user) => {
        cards += `
                    <div class="card">
                      <img src="${user.avatar}" class="section media">
                      <div class="section">
                        <p>${user.first_name} ${user.last_name}<br>
                        <a href="mailto:${user.email}">${user.email}</a>
                        </p>
                      </div>
                    </div>`;
    });
    $('#users').html(cards);
})
    .catch(function (error) {
        console.log(error);
    })
    .always(function () {
        // this function is always run last
    });
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

Line 2: remove the default callback function and move the logic to a separate done() methode line 3

// version 2: $.getJson() without default callback function, but with then()
$.getJSON(url, pars)
    .done(function (users) {
        console.log('users', users);
        let cards = '';
        // users.data[] contains 6 users
        users.data.forEach((user) => {
            cards += `
                    <div class="card">
                      <img src="${user.avatar}" class="section media">
                      <div class="section">
                        <p>${user.first_name} ${user.last_name}<br>
                        <a href="mailto:${user.email}">${user.email}</a>
                        </p>
                      </div>
                    </div>`;
        });
        $('#users').html(cards);
    })
    .catch(function (error) {
        console.error('API not resolved!', error);
    })
    .always(function () {
        // this function is always run last
        console.log('Request completed with success or error callback arguments');
    });
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Line 2: replace the done() methode with the then() methode
line 3: the first function inside done() is the resolve function
line 20: the second function inside done() is the reject function and (can) replace the catch() methode

// version 3: $.getJson() without default callback function, but with then()
$.getJSON(url, pars)
    .then(
        function (users) {
            console.log('users', users);
            let cards = '';
            // users.data[] contains 6 users
            users.data.forEach((user) => {
                cards += `
                    <div class="card">
                      <img src="${user.avatar}" class="section media">
                      <div class="section">
                        <p>${user.first_name} ${user.last_name}<br>
                        <a href="mailto:${user.email}">${user.email}</a>
                        </p>
                      </div>
                    </div>`;
            });
            $('#users').html(cards);
        },
        function (error) {
            console.error('API not resolved!', error);
        }
    )
    .always(function () {
        // this function is always run last
        console.log('Request completed with success or error callback arguments');
    });
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Compare version 2 of .getJSON() with this version
- $.getJSON(url, pars).done().catch().always()
  is now:
- $.get(url, pars, 'json').done().catch().always()
IMPORTANT: it is not recommended omitting the last parameter(json) of the .get() methode
jQuery tries to 'guess' the returned data type, but this often goes wrong...

// version 4: $.get()
$.get(url, pars, 'json')
    .done(function (users) {
        console.log('users', users);
        let cards = '';
        // users.data[] contains 6 users
        users.data.forEach((user) => {
            cards += `
                    <div class="card">
                      <img src="${user.avatar}" class="section media">
                      <div class="section">
                        <p>${user.first_name} ${user.last_name}<br>
                        <a href="mailto:${user.email}">${user.email}</a>
                        </p>
                      </div>
                    </div>`;
        });
        $('#users').html(cards);
    })
    .catch(function (error) {
        console.error('API not resolved!', error);
    })
    .always(function () {
        // this function is always run last
        console.log('Request completed with success or error callback arguments');
    });
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

ajax() is the most comprehensive method but also the most difficult to understand
In this example, we will only use some settings that are possible
A complete overview of possible parameters can be found in the API documentation (opens new window)

// version 5: $.ajax()
$.ajax(url, {
    url: url,
    type : 'GET',     // you may delete this line because GET is the default value
    data: pars,
    dataType: 'json',
    success(users) {
        console.log('users', users);
        let cards = '';
        // users.data[] contains 6 users
        users.data.forEach((user) => {
            cards += `
                    <div class="card">
                      <img src="${user.avatar}" class="section media">
                      <div class="section">
                        <p>${user.first_name} ${user.last_name}<br>
                        <a href="mailto:${user.email}">${user.email}</a>
                        </p>
                      </div>
                    </div>`;
        });
        $('#users').html(cards);
    },
    error(error) {
        console.error('API not resolved!', error);
    },
    complete() {
        // this function is always run last
        console.log('Request completed with success or error callback arguments');
    },
});
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# POST

Use the $.post() or the $.ajax() methode with the type: 'POST' to send new data to an API or insert something in a database
Open jquery/ajax/post.html and jquery/ajax/post.js

<div class="border-gray row" id="user"></div>
 
        Copied!

Line 2 to line 7: create an object that contains a new user
Line 11: post the new user to the API and the API sends us the newly (fake) inserted user
Line 14 to line 21: show a card of the new user on the page

// new user object
const newUser = {
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com',
    avatar: 'https://images.freecreatives.com/wp-content/uploads/2017/01/Person-Icons.jpg',
};
const url = 'https://reqres.in/api/users';

// version 1: $.post()
$.post(url, newUser, 'json')
    .then((user) => {
        console.log('user', user);
        $('#user').html(`
              <div class="card">
                <img src="${user.avatar}" class="section media">
                <div class="section">
                    <p>${user.first_name} ${user.last_name}<br>
                    <a href="mailto:${user.email}">${user.email}</a>
                    </p>
                </div>
            </div>`);
    })
    .catch(function (error) {
        console.error('error', error);
    })
    .always(function () {
        console.log('Request completed with success or error callback arguments');
    });
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

In this example, we will only use some settings that are possible

// version 2: $.ajax()
$.ajax(url, {
    url: url,
    type: 'POST',
    data: newUser,
    dataType: 'json',
    success(user) {
        console.log('user', user);
        $('#user').html(`
              <div class="card">
                <img src="${user.avatar}" class="section media">
                <div class="section">
                    <p>${user.first_name} ${user.last_name}<br>
                    <a href="mailto:${user.email}">${user.email}</a>
                    </p>
                </div>
            </div>`);
    },
    error(error) {
        console.error('error', error);
    },
    complete() {
        // this function is always run last
        console.log('Request completed with success or error callback arguments');
    },
});
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# PATCH/PUT

Use the $.ajax() methode with type: 'PATCH' or type: 'PUT' to update data through an API or update something in a database
Open jquery/ajax/patch.html and jquery/ajax/patch.js

<div class="border-gray row" id="user"></div>
 
        Copied!

// update user object
const updateUser = {
    first_name: 'Jane',
    last_name: 'Doe',
    email: 'jane.doe@example.com',
    avatar: 'https://images.freecreatives.com/wp-content/uploads/2017/01/Person-Icons.jpg',
};
const url = 'https://reqres.in/api/users/7';

$.ajax(url, {
    url: url,
    type: 'PATCH',
    data: updateUser,
    dataType: 'json',
    success(user) {
        console.log('user', user);
        $('#user').html(`
              <div class="card">
                <img src="${user.avatar}" class="section media">
                <div class="section">
                    <p>${user.first_name} ${user.last_name}<br>
                    <a href="mailto:${user.email}">${user.email}</a>
                    </p>
                </div>
            </div>`);
    },
    error(error) {
        console.error('error', error);
    },
    complete() {
        // this function is always run last
        console.log('Request completed with success or error callback arguments');
    },
});
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# DELETE

Use the $.ajax() methode with type: 'DELETE' to delete data through an API or delete something from a database
Open jquery/ajax/delete.html and jquery/ajax/delete.js

<div class="border-gray row" id="user"></div>
 
        Copied!

Notice that when we look at the DELETE example on the API (opens new window), we only gets a status code 204 (opens new window) back
The status code is available through the third parameter with the xhr.status property
Line 10 to line 12: show some feedback on the page if the status code is 204

const url = 'https://reqres.in/api/users/7';

$.ajax(url, {
    url: url,
    type: 'DELETE',
    success(response, textStatus, xhr) {
        console.log('response', response);
        console.log('xhr', xhr);
        console.log('xhr.status', xhr.status);
        if (xhr.status === 204) {
            $('#user').text('User successfully deleted');
        }
    },
    error(error) {
        console.error('error', error);
    },
    complete() {
        // this function is always run last
        console.log('Request completed with success or error callback arguments');
    },
});
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Examples

As we will not be using a backend of our own in this course, we will only discuss examples where we are retrieving data from external API's

# Fetch images

Open /jquery/ajax/images.html and /jquery/ajax/images.js
In this example we fetch all images from our own (fake) API:
https://my-json-server.typicode.com/pverhaert/itf-api/picsum (opens new window)

<div class="spinner tertiary"></div>
<div class="row" id="imgContainer"></div>
 
        Copied!

1
2

Line 3: fetch the API and
Line 5 to line 16: then() loop over every item inside the array, construct a card (opens new window) with the data and append it to the #imgContainer
Line 18: catch() check if the response has some errors
Line 21: always() hide the preloader/spinner

const url = 'https://my-json-server.typicode.com/pverhaert/itf-api/picsum';

$.getJSON(url)
    .done((images) => {
        images.forEach((image) => {
            $('#imgContainer').append(`
                    <div class="card">
                      <img src="${image.url}/600/400" class="section media" alt="Image by ${image.author}">
                      <div class="section">
                        Image &copy; <a href="https://unsplash.com/photos/${image.meta.unsplash}" target="_blank">${image.author}</a>
                        <br>
                        Category: ${image.category}
                      </div>
                    </div>
                `);
        });
    })
    .catch((error) => {
        console.error('API not resolved!', error);
    })
    .always(() => {
        $('.spinner').hide();
    });
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# Fetch movie info

Open /jquery/ajax/omdb.html and /jquery/ajax/omdb.js
In this example we fetch movie information from the OMDb API (opens new window)
The parameters we needed are:
- apikey: your API key (you must first generate a free apikey (opens new window))
- t: the movie title to search for
- y: year of release
- plot: can be full or short
The JSON we get from te server: https://www.omdbapi.com/?apikey=yourKey&t=Pulp+fiction&y=&plot=short (opens new window)
(Replace yourKey in the query string with a real API key)

line 2: replace the value for apikey with your API key
As you can see in the form, the name attribute of the form elements matches exactly the keys for the query string we have to append to the fetch URL
This makes it super easy (only three lines of code) to serialize the form (opens new window) with JavaScript
The result of this serialization is a string like this: apikey=yourKey&t=Pulp+fiction&y=&plot=short

<form>
    <input type="hidden" name="apikey" value="yourKey" />
    <div class="row responsive-label">
        <div class="col-sm-12 col-md-2"><label for="title" class="doc">Title</label></div>
        <div class="col-sm-12 col-md">
            <input type="text" placeholder="Title" id="title" name="t" value="Pulp fiction" required />
        </div>
    </div>
    <div class="row responsive-label">
        <div class="col-sm-12 col-md-2"><label for="year">Year</label></div>
        <div class="col-sm-12 col-md">
            <input type="number" placeholder="Year" id="year" name="y" />
        </div>
    </div>
    <div class="row responsive-label">
        <div class="col-sm-12 col-md-2"><label for="plot">Plot</label></div>
        <div class="col-sm-12 col-md">
            <select id="plot" name="plot">
                <option value="short">short</option>
                <option value="full">full</option>
            </select>
            <button type="submit" class="primary">Search</button>
        </div>
    </div>
</form>
<hr />
<div class="spinner tertiary"></div>
<div class="row" id="movieContainer"></div>
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Line 39: submit the form when the page is loaded
Line 54 to line 59: serialize the form and append it to the fetch URL
Result: fetchMovie('https://www.omdbapi.com/?apikey=yourKey&t=Pulp+fiction&y=&plot=short');
The rest of the code follows just the same logic as the code in the previous exercise

const omdbapi = 'https://www.omdbapi.com/';

$('form')
    .submit(function (e) {
        e.preventDefault();
        $.getJSON(omdbapi, $('form').serialize())
            .then((movie) => {
                // info if movie not found
                let info = `
                  <div class="card warning full-width">
                    <p>No info found for <b>${title.value}</b></p>
                  </div>`;
                // overwrite info if the movie is found
                if (movie.Response === 'True') {
                    const poster = movie.Poster && movie.Poster.length > 10 ? `<img src="${movie.Poster}">` : '';
                    info = `
                    <div class="row">
                      <div class="col-sm-6">${poster}</div>
                      <div class="col-sm-6">
                        <h2>${movie.Title}</h2>
                        <p><b>Genre: </b>${movie.Genre}<br>
                        <b>Released: </b>${movie.Released}<br>
                        <b>Actors: </b>${movie.Actors}<br>
                        <b>Director: </b>${movie.Director}<br></p>
                        <hr>
                        <p class="text-justify">${movie.Plot}</p>
                      </div>
                    </div>`;
                }
                document.getElementById('movieContainer').innerHTML = info;
            })
            .catch((error) => {
                console.error('API not resolved!', error);
            })
            .always(() => {
                $('.spinner').hide();
            });
    })
    .submit();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

READING TIP