In this tutorial we will look at setting up a simple theme in ProcessWire, we’ll investigate delayed output (now the default theme strategy within ProcessWire), and setup our site to request new content using AJAX.
To accompany this tutorial I have created a new theme for ProcessWire, making use of both AJAX and delayed output, which can be found on Github. You can also find a demo of the theme here: Artist Profile demo.
For instructions on installing ProcessWire, and to learn the fundamentals on AJAX, take a look at the following resources:
Direct and Delayed Output
ProcessWire (PW) has an incredibly flexible templating system; it allows you to code any structure of your choosing by creating php files within the /site/templates folder and then associate them within the ProcessWire admin in setup > templates > add new. This said, there are two common strategies found within the PW forums for templating: direct output and delayed output.
Direct Output
Direct output sees each php file in command of the specific page output. This can be great if each template is vastly different from the others. However, I’ve found this cumbersome if only minor changes are needed in each template. You may also find yourself copying from other templates or including lots of files. Here is a very basic template (eg. basic-page.php).
<?php
include("./_head.php");
echo "Your html content";
include("./_foot.php");
?>
Delayed Output
Delayed output sees common files (like _init.php) called before, and _main.php after the template file (e.g. basic-page.php). Your _main.php is used as the mothership for your markup (html) and the specific template is relegated to adding content to predefined variables output in the _main.php file.
In the example below I add the body and video fields from the template page to the variable $content and output the page markup in my _main.php file as it always executes afterwards.
basic-page.php:
<?php
$content = $page->body . $page->video;
?>
_main.php:
<?php
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
// echo nav links
$children = $pages->get('/')->children;
foreach($children as $child){
echo '<a name="'.$child->title.'" class="ajax-link'.$class.'" href="'. $child->url .'">'. $child->title .'</a>';
}
?>
</nav>
</aside>
<div class="content-container cf">
<div class="content current-content">
<?php
// add content to page from template file
echo $content;
?>
</div>
</div>
<?php
include("./foot.inc");
?>
The Artist Profile
The Artist Profile is an example of a theme which uses delayed output. The main HTML structure is written within the _main.php file and includes a page head, footer, logo and navigation. The current page template sets the $content variable–for example my basic-page.php.
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.
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+.
Comments