Web development #7: Dynamic page updates with AJAX

So in theory you should now have all the tools to create the most awesome websites. However, I don’t think any tutorial on web development is complete without doing some AJAX. No idea what I’m talking about? Read my previous posts.

  1. Web development #1: Internet and the World Wide Web
  2. Web development #2: Our first website using HTML
  3. Web development #3: Styling our page with CSS 3
  4. Web development #4: PHP in the back
  5. Web development #5: User input with HTML Forms
  6. Web development #6: Getting interactive with JavaScript
  7. Web development #7: Dynamic page updates with AJAX
  8. Web development #8: Where to go from here

So what is AJAX all about? It’s an abbreviation for Asynchronous JavaScript And XML. It enables us to send a request to the server and receive a result without having to refresh our entire page. Now that’s pretty awesome! What’s also pretty awesome is that we don’t need to use XML. As Linus Torvalds, creator of Linux, already said “XML is crap. Really. There are no excuses. XML is nasty to parse for humans, and it’s a disaster to parse even for computers. There’s just no reason for that horrible crap to exist.” So what we’ll be using is a form of AJAX called AJAJ, where the last J stands for JSON (JavaScript Object Notation). To make it a bit more confusing, we’ll just call it AJAX anyway. Oh yeah, and it doesn’t have to be asynchronous either…

JavaScript objects and JSON

First of all we need to know what JavaScript Objects are and what they look like. After that JSON will come naturally. So JavaScript has objects and much like objects in other languages JavaScript objects are just wrappers around certain functionality. The difficulty in JavaScript, of course, lies in that anything can be anything and then can become anything else… Let’s just look at an example.

// Creates an empty object.
var obj = {};
// Gives the object a firstName property.
obj.firstName = 'Sander';
// Gives the object a lastName property.
obj.lastName = 'Rossel';
// Gives the object a getFullName function.
obj.getFullName = function () {
    return this.firstName + ' ' + this.lastName;
};

// Alternative for the above.
var person = {
    firstName: 'Sander',
    lastName: 'Rossel',
    getFullName: function () {
        return this.firstName + ' ' + this.lastName;
    }
};

Now this wouldn’t be JavaScript if we didn’t have even more methods to create objects (JavaScript also knows constructors). We’re not interested in those though. What we’re interested in is the second method I’m using. Notice that, to create an object, we use curly braces. We can then basically add anything to that object by simply defining keys (property or function names) and values (default values for properties or implementations for functions) seperated by colons. Each key and value is seperated by a comma. And of course objects can contain other objects too.

var outerObj = {
    innerObj: {
        someValue: null
    },
    anotherInnerObj: {
        innerInnerObj: {}
    },
    message: 'Phew, what syntax!'
};

You can work with objects as ways of namespaces so you can keep the ‘global namespace’ clean and minimize the chance for name conflicts with other libraries. Objects are also often used to create some sort of options that are given to a function. A function then simply checks if some property or method on the option object exists, what its value is, and acts accordingly. We’ll see this usage a little later when working with AJAX.

So then, what is JSON? It’s simply some text using almost the exact notation we just saw. So let’s look at some examples.

{
    "firstName": "Sander",
    "lastName": "Rossel"
}

{
    "innerObj": {
        "someValue": null
    },
    "anotherInnerObj": {
        "innerInnerObj": {}
    },
    "message": "Phew, what syntax!"
}

That’s looking pretty familiar now, doesn’t it? And, if you compare it to XML, it’s a lot more compact, saving you precious bits and bytes when you’re sending your data over the internet!

Making an AJAX request

So let’s look at an AJAX example. I’ll start very simple making a synchronous request that returns just plain text (so no XML or JSON) when the page loads. You’ll know that the request doesn’t refresh the page because if it would the page would keep refreshing (as it makes the request upon loading). Alternatively, you can track all requests your browser makes using your browsers developer tools (press F12 in IE, FireFox or Chrome and navigate to the Network tab). I’m using jQuery to get the page load event and to show the result of our AJAX request. So here’s the HTML (in a file called Ajax.html):

<!DOCTYPE html>
<html>
    <head>
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
        <script type="text/javascript" src="Ajax.js"></script>
    </head>
    <body>
        <p id="result"></p>
    </body>
</html>

Here’s our JavaScript (Ajax.js):

$(function () {
    var ajax = new XMLHttpRequest();
    ajax.open('GET', 'Ajax.php', false);
    ajax.send();
 
    $('#result').text(ajax.responseText);
});

And finally our PHP (Ajax.php):

<?php
    echo 'Result of AJAX request!';
?>

So all of these files go into the htdocs folder of your XAMPP installation and you’ll have to access your page by browsing to localhost/Ajax.html (notice I named all files ‘Ajax’). So what’s really interesting here is that in my JavaScript I’m using an XMLHttpRequest object. So we call the open method and pass in a string specifying the HTTP method, GET or POST. Next we’re telling it what URL to navigate to and last we’re specifying whether the request should be asynchronous (we’re calling it synchronous). Then we send the request to the server. So, because we’re calling it synchronous the browser blocks until we get response from the server. That means that on our next line of code we simply have our result, ajax.responseText. Now you’ll never do this, in fact, our browser even gives off a warning saying that this method is deprecated because it negatively affects the user experience. In our case we won’t notice the blocking, but if we’re downloading larger chunks of data our page will freeze up completely!

So let’s make that call asynchronous so the user can go about doing his business while our page gets our data for us. This isn’t actually to hard. We simply change our JavaScript to the following:

$(function () {
    var ajax = new XMLHttpRequest();
    ajax.onreadystatechange = function () {
        if (ajax.readyState == 4) {
            $('#result').text(ajax.responseText);
        };
    };
    ajax.open('GET', 'Ajax.php', true);
    ajax.send();
});

So I’m specifying an onreadystatechange function which gets called when the state of our ajax object changes. State 4 means it’s done and we can get the result.

Now there are quite some options we can set and check, but I’ll not get into that. You can check them on the XMLHttpRequest documentation page and play around with them yourself. Instead, we’re going to use jQuery to make AJAX requests.

Using jQuery for AJAX requests

You might be thinking if there’s anything jQuery cannot do? There’s actually plenty of stuff you don’t want to do using jQuery, but AJAX isn’t one of them. jQuery makes AJAX pretty easy actually. We were already using jQuery, so we can simply edit our JavaScript.

$(function () {
    $.ajax({
        type: 'GET',
        url: 'Ajax.php',
        complete: function (jqXHR) {
            $('#result').text(jqXHR.responseText);
        }
    });
});

So remember I was telling you about using an object to specify options? This is one such an example. We’re passing in an object and specify the type, the url and a function that will be called when the requests completes (jqXHR stand for jQuery XMLHttpRequest, but you can name it anything). We could’ve passed in much more, but we didn’t. So this does the same as the code we had earlier.

The jQuery.ajax function can actually do a whole lot of stuff! Next we’re going to pass in some parameters and echo them on our page.

$(function () {
    $.ajax({
        type: 'GET',
        url: 'Ajax.php',
        data: {
            artist: 'Led Zeppelin',
            song: 'Immigrant Song'
        },
        complete: function (jqXHR) {
            $('#result').text(jqXHR.responseText);
        }
    });
});

And now we need to alter our PHP too.

<?php
    if (isset($_REQUEST['artist']) &&
        isset($_REQUEST['song']))
    {
        $artist = $_REQUEST['artist'];
        $song = $_REQUEST['song'];
        echo "The song '$song' by $artist rocks!";
    }
?>

So that was pretty easy, right? We just passed in a JavaScript object with some properties and they were converted to parameters in our PHP automatically! So how does this work the other way around? This is where JSON comes into play! JSON stands for JavaScript Object Notation, so it should be pretty easy for JavaScript to create actual objects that we can use. So let’s start by modifying our PHP so that it returns JSON.

<?php
    class song
    {
        public $artist = NULL;
        public $name = NULL;
    }
 
    if (isset($_REQUEST['artist']) &&
        isset($_REQUEST['song']))
    {
        $song = new song();
        $song->artist = $_REQUEST['artist'];
        $song->name = $_REQUEST['song'];
 
        header('Content-Type: application/json');
        echo json_encode($song);
    }
?>

First of all, I’m using an object to store our data. We’ve seen this before. I’m setting our response header so that it tells our browser it’s json. Then I’m using the json_encode function to convert our object into JSON. If you now check out the result in your browser you’ll notice that we’ve received some actual JSON!

But what we really want is to use this JSON in our JavaScript as if it were just an object. Actually this is pretty easy! We can get the object from the XMLHttpRequest.

complete: function (jqXHR) {
    var song = jqXHR.responseJSON;
    $('#result').text("The song '" + song.name + "' by " + song.artist + " rocks!");
}

And that’s it. Alternatively, we can use the ‘success’ option, a function that passes us the returned data, the status of the request and the XMLHttpRequest.

$(function () {
    $.ajax({
        type: 'GET',
        url: 'Ajax.php',
        data: {
            artist: 'Led Zeppelin',
            song: 'Immigrant Song'
        },
        success: function (song, status, jqXHR) {
            $('#result').text("The song '" + song.name + "' by " + song.artist + " rocks!");
        }
    });
});

And likewise there is an ‘error’ option.

$(function () {
    $.ajax({
        type: 'GET',
        url: 'Ajaj.php',
        data: {
            artist: 'Led Zeppelin',
            song: 'Immigrant Song'
        },
        success: function (song, status, jqXHR) {
            $('#result').text("The song '" + song.name + "' by " + song.artist + " rocks!");
        },
        error: function (jqXHR, status, errorThrown) {
            $('#result').text('An error occurred: ' + jqXHR.status + ' ' + errorThrown);
        }
    });
});

Notice that I’m calling ‘Ajaj.php’, a page that doesn’t exist. Naturally we’ll get 404, Not found. When using the ‘complete’ option we used earlier you’d have to check for success yourself, our current implementation would actually break our page if we called ‘ajaj.php’.

So there’s actually quite a bit to think about when using AJAX. Did the server return a result, what kind of result did it return, was the request successful, etc. We can use the XMLHttpRequest object for this. Check ‘status’ to see if our request was successful (status 200 means success) and then ‘responseType’ and any of ‘response’, ‘responseText’, ‘responseJSON’ or ‘responseXML’ for the result.

Posting data

So in the previous examples we’ve taken a look at the GET method. In the next example I’m going to take our movies page we created in my previous blog posts, Web development #4: PHP in the back and Web development #5: User input with HTML Forms. So first of all we’ll have to edit the PHP file. We want the form to go, because that refreshes the page. We also want to add jQuery and a custom JavaScript file to our header. Last, we need to give some ids to some elements because now we need to update the page ourselves once we add a new movie (after all, the page isn’t refreshing). So without further delay, here’s the modified PHP.

<?php
    if (isset($_POST['movieName']))
    {
        $movieName = $_POST['movieName'];
        if ($movieName)
        {
            file_put_contents('movies.txt', htmlspecialchars($movieName) . "rn", FILE_APPEND);
        }
 
        exit();
    }
?>
<!DOCTYPE html>
<html>
    <?php
        function fileAsUnorderedList($fileName, $notFoundMessage)
        {
            if (file_exists($fileName))
            {
                echo '<ul id="movies">';
                $lines = file($fileName);
                foreach ($lines as $line)
                {
                    echo '<li>' . htmlspecialchars($line) . '</li>';
                }
                echo '</ul>';
            }
            else
            {
                echo $notFoundMessage;
            }
        }
    ?>
    <header>
        <title>My favourite movies!</title>
        <meta charset="utf-8">
        <meta name="description" content="A list of my favourite movies.">
        <meta name="keywords" content="Favourite,movies">
        <meta name="author" content="Sander Rossel">
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
        <script type="text/javascript" src="Movies.js"></script>
    </header>
    <body>
        <h1>My favourite movies!</h1>
        <p>
        <?php
            fileAsUnorderedList('movies.txt', 'No favourite movies found!');
        ?>
        </p>
        <h2>Add a movie!</h2>
        <div>
            <label for="movieName">Movie name</label>
            <input type="text" name="movieName" id="movieName" />
            <button id="submit">Submit</button>
        </div>
    </body>
</html>

And then we need to add a JavaScript file (I’ve called it Movies.js) to add an event handler to our button click event which takes the value of the input, posts it to the server and on success adds the movie to our list and empties the movie input.

$(function () {
    $('#submit').on('click', function () {
        var movieInput = $('#movieName');
        var movieName = movieInput.val();
        if (movieName) {
            $.ajax({
                type: 'POST',
                url: 'Movies.php',
                data: {
                    movieName: movieName
                },
                success: function (data, status, jqXHR) {
                    $('#movies').append('<li>' + movieName + '</li>');
                    movieInput.val(null);
                },
                error: function (jqXHR, status, errorThrown) {
                    alert("An error occurred while adding movie '" + movieName + "'.");
                }
            });
        };
    });
});

And there you have it. Looks complicated? I guess it is a bit, but once you get the hang of it it’s not so bad. And luckily the documentation is rather good!
Another cool addition to our page would be pagination. Let’s say we are going to add hundreds of movies. Getting those all in once might slow down our page quite a bit. So we can use AJAX to get just ten, or twenty, or fifty at a time. The page could load them on a button click or when we scroll to the end of the page (that is, get the movie titles and add them to our list using jQuery, also make sure you ‘remember’ what page you’re on). This principle is called pagination and can greatly enhance user performance (and for large websites it’s even a must).

So that’s it for AJAX. And actually, that’s it for web development! You’ve now seen everything involved in creating awesome, responsive web pages. Of course there’s still a long way to go as we’ve only scratched the surface of web development. We’ve seen the tools, but are by no means expert in any of them. In my next, and last, blog post I’ll give you some tips on frameworks and libraries that can help you create the pages you want.

Stay tuned!

One thought on “Web development #7: Dynamic page updates with AJAX”

Leave a Reply