How to Create an AJAX Driven Theme for ProcessWire

You can install The Artist Profile to see how I’ve put together the theme and used AJAX in the main.js file. I will now walk through some of the concepts at work within this theme.

AJAX Data Strategies

AJAX allows our users to be shown new content from our site without reloading common page parts like the logo, footer and navigation. It also means our user will never see a blank white browser window while the new page is being requested.

Using AJAX we can request common data types from our website like HTML, JSON or XML. To keep things simple we’re going to request HTML from our site, however if you created or were using an existing frontend templating library, we could request JSON instead, cutting down on the amount of data per request (there are lots of libraries you can use on the frontend, one example being mustache).

In our theme I would like the logo, navigation and footer to stay the same, but for the main content area to change dynamically (or asynchronously) when we click on a link.

Using AJAX in Our ProcessWire Theme

To do this we need to create two container HTML elements to which we can add our new content. The container element will not change, but will hold the inner element and content appended to it. The new content will be appended while the old content is animated, then deleted. This will create a fluid look and feel.

With my _main.php file the containers look like this:

<div class="content-container cf">
    <div class="content current-content">
		<?php
		echo $content;
		?>
	</div>
</div>

Ok, so far so good. Now let’s add a check for the the handy ProcessWire variable $ajax. $ajax declares whether or not a request was from AJAX. Here’s the example check if not AJAX:

if(!$ajax):

Within my theme’s _main.php file I can wrap the content that I don’t need for the AJAX request, i.e. everything other than the echo $content. This looks like this:

<?php
// include page structure if not an ajax request
if(!$ajax):
    include("./head.inc");
?>

<div id="page">
	<header class="">
		<a id="logo" href="<?php echo $pages->get('/')->url; ?>">
			<h1>
			<?php echo $pages->get('/')->title; ?>
			</h1>
		</a>
	</header>
	<aside>
		<nav>
		<?php
		// nav content here	
		?>
		</nav>
	</aside>
	<div class="content-container cf">
		<div class="content current-content">
		<?php endif; // end if ajax ?>
		
        <?php
		// if ajax then only return $content
		echo $content;
		?>
		
        <?php if(!$ajax): ?>
		</div>
	</div>
<?php
    include("./foot.inc");
endif; // end if ajax
?>

Now we have our template ready to give us the whole page markup if a normal page request, or just the $content if an AJAX request.

Requesting a Page in JavaScript Using jQuery AJAX

I’m using the JavaScript library jQuery for my theme. I’ve referenced a main.js file in my foot.inc, after a link to the latest version of the jQuery library.

Using jQuery’s .on and .ajax functions we can create an AJAX request to the new page content anytime we click a link with a class .ajax-link.

So far our main.js code looks like this:

$(function() {

    var href;
	var title;

  	$('body').on('click','a.ajax-link',function(e) { // nav link clicked

      	href = $(this).attr("href");
      	title = $(this).attr("name");

		// load content via AJAX
      	loadContent(href);

		// prevent click and reload
    	e.preventDefault();
	});

	function loadContent(url){ // Load content

		// variable for page data
    	$pageData = '';

		// send Ajax request
    	$.ajax({
	        type: "POST",
	        url: url,
	        data: { ajax: true },
	        success: function(data,status){
				$pageData = data;
      		}
    	}).done(function(){ // when finished and successful

			// construct new content
      		$pageData = '<div class="content no-opacity ajax">' + $pageData + '</div>';

			// add content to page
			$('.content-container').append($pageData);

            // remove old content
            $('.content.current-content').remove();

            // show new content and clean up classes
            $(this).removeClass('no-opacity').removeClass('ajax').addClass('current-content');
            
    	}); // end of ajax().done()
  	} // end of loadContent()
});

The code above has an .on('click','a.ajax-link', function(){ OUR FUNCTIONS HERE }) which allows us to trigger our loadContent() function anytime a link is clicked. Within the loadContent() function we use the url from the link to send an ajax request, and then when .done() we append the data to the .content-container element.

All the above will work fine, but there are lots of little extras we can add to make everything seamless.

AJAX Tricks, Tips and Logic

Firstly, we can animate our content in and out (this links to the animate part of the main.js file). Animation is great for making slick looking websites, but can also act as a psychological trigger to highlight that something has changed.

Next, we want to reinitialise any JavaScript functions we need for the page, e.g. lightboxes, slideshows, masonry etc, and we put this in after we’ve added the new HTML data to the page. As the new content had been retrieved via AJAX it may not be bound with JavaScript listeners for clicks etc. and therefore won’t trigger unless we have reinitialised any functions we need on the page.

Creating an already loaded check is useful for preventing useless requests. Adding a quick check to see if the new link has already been clicked and then return true; if it has prevents users from accessing the same page multiple times.

Lastly, but probably most importantly, we can now use html5 history to keep track of the current page and reload past page content when the user pushes the back button.

• 

  JavaScript

  Lovely, Smooth Page Transitions With the History Web API

  Thoriq Firdaus

Wrapping up

Using some of the above strategies we can create a seamless AJAX experience for our website, and using ProcessWire we can integrate AJAX requests within our theme in no time.

For more on ProcessWire and AJAX check out our tutorials on Envato Tuts+.