One scenario where this has always appealed to me is in paginating data. Why reload an entire document each time you page through a dataset when you can use AJAX to fetch just the next page.

Now introduce the HTML5 History API, and all of a sudden you’ve got AJAX data updates with navigable, bookmarkable URLs.

In this article, I’m going to step through creating a paging controller action that updates the paged data via AJAX and maintains URL location for browsers that support the History API.

If you want to play along at home, all code used in this demo is available on github, with each stage represented by its own branch. Get the code at https://github.com/philBrown/Awesome-Pagination-Demo and checkout the “html-only” branch

git clone git://github.com/philBrown/Awesome-Pagination-Demo.git
cd Awesome-Pagination-Demo
git checkout -b origin/html-only

To start with, we have a vanilla ZF project with a layout and simple controller action that instantiates a paginator object (using the array adapter for this demo), grabs the “page” parameter from the request and assigns the paginator to the view.

public function indexAction()
{
    $paginator = Zend_Paginator::factory($this->getModels());
    $paginator->setCurrentPageNumber($this->getRequest()->getParam('page', 1));
    $this->view->paginator = $paginator;
}

Our view then displays the paginationControl helper

<?php $paginationControl = $this->paginationControl(
    $this->paginator, 'All', '_partials/paginator.phtml') ?>
 
<div class="pagination-control">
    <?php echo $paginationControl ?>
</div>

and a table with our data, looping over each item in the paginator.

What we end up with is something like this

Clicking on each paginator link loads an entirely new page with the requested data. Not horrible, but could be better.

Now checkout the “ajax-loading” branch

git checkout -b origin/ajax-loading

Our layout now includes the inlineScript helper with a link to jQuery on the Google CDN. The controller now initialises the AjaxContext helper to allow “html” AJAX requests for the index action.

public function init()
{
    $this->_helper->ajaxContext->addActionContext('index', 'html')
                               ->initContext();
}

The view has also been changed. We’ve added a link to our pagination JavaScript file (more on this later) and the guts of the view (pagination controls and data) has been moved into a new file index.ajax.phtml which is referenced using the render method.

// index.phtml
<?php $this->inlineScript()->appendFile('js/paginator.js') ?>
 
<div class="paged-data-container">
    <?php echo $this->render('index/index.ajax.phtml') ?>
</div>

The index.ajax.phtml file is the one delivered via the AjaxContext helper when an XMLHTTPRequest is intercepted with the “html” format parameter present. Including it in the default template caters for the first page load.

Now on to our JavaScript file. All this file needs to do is catch click events on any of the paginator links and fetch the contents via AJAX, repopulating the paginator controls and data.

In essence, it looks like this.

jQuery(function($){
    $('.pagination-control').find('a').live('click', function(){
        var link = $(this);
        var container = link.parents('.paged-data-container');
        $.get(link.attr('href'), { format: 'html' }, function(data){
            container.html(data);
        }, 'html');
        return false;
    });
});

We’re using the “live” binding as each AJAX load replaces the paginator controls. The { format: 'html' } parameter is added to the request to trigger the right context switch in the controller.

So now we have a basic AJAX paginator. The only problem here is that each page loads under the same URL. There’s also little visual feedback to let the user know the data is changing.

Taking a leaf out of GitHub’s “Tree Slider”, if you checkout the “ajax-loading-animations” branch, you’ll see some nifty left (next) and right (previous) scrolling.

So now we come to the final stage, utilising the HTML5 History API to add stateful URLs for each AJAX data load.

Checkout the master branch to see the code.

The gist of this is to use the history.pushState method to add history records on click and bind an event handler to the “popstate” event to catch navigation (back / forward) button presses.

The end result looks like this – http://apps.philipbrown.id.au/awesome-pagination/

Whilst it’s certainly not as snazzy as GitHub’s Tree Slider, it’s a step in the right direction.

After sorting through a few, I decided on this one from Jörn Zaefferer. The only problem was, I wanted to use the wonderfully simple Zend Framework AjaxContext Action Helper to produce JSON data as my auto-complete data source. I like JSON as it’s easy to produce and easy to deal with in disparate systems (such as PHP and JavaScript). Unfortunately, Jörn’s plugin is built to work with a simple, formatted ASCII list delimited by newlines. Fortunately, he also put a lot of work into this plugin, he just hasn’t gotten around to documenting it all yet.

For this post, I’ll assume my AJAX request is for some user data out of LDAP (or a similar data store) and resembles this

{"users":[
    {"uid":"123","displayName":"User 123","mail":"123@example.com"},
    {"uid":"456","displayName":"User 456","mail":"456@example.com"},
    {"uid":"789","displayName":"User 789","mail":"789@example.com"},
]}

The secret to extending the Autocomplete plugin is the ability to overwrite certain core functions, primarily parse. The internal version of this function simply loops over each line of the returned data and “parses” it into an array of objects, each containing the following attributes:

• data – the entire entry
• value – the default display value
• result – the data to populate the input element on selection

You can overwrite this by passing your own parse function as part of the options object to autocomplete. Mine also includes a custom formatItem function for displaying each entry.

var acOptions = {
    minChars: 3,
    max: 100,
    dataType: 'json', // this parameter is currently unused
    extraParams: {
        format: 'json' // pass the required context to the Zend Controller
    },
    parse: function(data) {
        var parsed = [];
        data = data.users;
 
        for (var i = 0; i < data.length; i++) {
            parsed[parsed.length] = {
                data: data[i],
                value: data[i].displayName,
                result: data[i].displayName
            };
        }
 
        return parsed;
    },
    formatItem: function(item) {
        return item.displayName + ' (' + item.mail + ')';
    }
};

The autocomplete plugin will now accept and parse JSON data.

Another thing I wanted to do with this page was to show one value but use another. In this case, I only want to display the user names and email addresses and use the UID without displaying it or putting it into the form field. This is where having each item available as a JSON object comes in very handy.

For this trick, I’ll add a hidden input field and place the UID into that when an item is selected. Here’s my form field

<input type="text" id="user_id" name="user_id">

and here’s the JavaScript

// autocomplete options as above
 
jQuery(document).ready(function($) {
    $('#user_id')
        .autocomplete('/path/to/ajax/data/source', acOptions)
        .attr('name', 'display_name')
        .after('<input type="hidden" name="user_id" id="ac_result">')
        .result(function(e, data) {
            $('#ac_result').val(data.uid);
        });
});

The reason I changed the name attribute of the original input and gave it to the new hidden one is so I can still submit the form normally and work with the submitted “user_id” value.

The Autocomplete result function receives the selected item’s data property when an item is selected. With the above configuration, this is the actual JSON object