In this beginner’s tutorial you’ll learn about creating your own ProcessWire CMS themes. We’ll create a super simple site, covering templates, fields, theme structure and PHP variables.
Don’t forget to get up to speed by following the first of our tutorials How to Install and Setup ProcessWire CMS.
Where to Find Your ProcessWire Theme
Unlike other CMSs like WordPress, ProcessWire doesn’t have a theme selection process as part of its admin, where you can switch themes at the press of a well labeled button. However, this is not necessarily a bad thing. ProcessWire has its own system: the folder “site/templates” which contains all the files associated with your theme.
Creating a Blank Theme
The best way to create a blank theme, is to select the site-blank profile while installing ProcessWire (PW). Site-blank contains the most basic site structure within your “site/templates” folder – this includes folders and files
- /scripts
- /styles
- /errors
- home.php
- basic-page.php
- admin.php
You can create a new “site/templates” folder with your own files after installation if you wish, instead of starting with the site-blank profile, but make sure you at least have the files listed above.
Processwire Theme Structure
Routing
Learning how PW routes its pages will help us construct our custom templates later on.
When a PW page is requested (e.g. www.benbyford.com/about), PW looks at the page within the CMS and checks which template is assigned; in this case I’ve assigned the template “basic-page”; the file “basic-page.php” within the “site/templates/” is rendered and the requested HTML sent to the user (PW also allows easy use of other formats like JSON or XML).
Tip: by default, templates are referred to within PW with the same name as their PHP template file, however you can change the template name and associated file anytime after creation within the PW admin.
For an example, let’s add some HTML & PHP to our “home.php” file:
<!DOCTYPE html>
<html lang="en">
<head>
<title><?php echo $page->title; ?></title>
</head>
<body>
<h1><?php echo $page->title; ?></h1>
</body>
</html>
Now go to your site URL in the browser and notice the title and h1 should now be filled with the title of your homepage (by default: Home).
Including Other PHP Files
Making lots of templates files with very similar HTML isn’t very efficient, so let’s make a couple of .inc PHP files that can be included into each template. A common structure pattern within theming is to create “head.inc” and “foot.inc” files which are used to construct common HTML code like our <head>, navigation, logo, footer and scripts.
Let’s edit our “home.php” file again to implement the above:
<?php include('./head.inc'); // include header markup ?>
<h1><?php echo $page->title; ?></h1>
<?php include('./foot.inc'); // include footer markup ?>
Add our head.inc:
<!DOCTYPE html>
<html lang="en">
<head>
<title><?php echo $page->title; ?></title>
</head>
<body>
And foot.inc:
</body> </html>
Why use the .inc file type I hear you ask‽ Well, when adding a new template in PW’s admin, the system looks at the site/templates/ folder for any new .php files that haven’t been used by a template yet. By using the .inc file type instead of .php you won’t get confused between template files and files you wish to include in your template.
Associating New Templates with the CMS
You can make as many templates as you like for pages within your PW site, go wild! For example let’s make a new template for a new page called “Contact”. I start by:
- duplicating my “home.php” file and calling the new file “contact-page.php”
- in the PW admin, navigate to setup > templates > add new template
- select your “contact-page.php” from the checklist, select “home” from the duplicate fields list, and click Add Templates
The CMS now knows about your new template file and it will now show up as a
template option when creating a new page. Try creating a new page under your home page, name it “Contact” and select our new contact-page template. You now have at least two active templates in your site: “home”, and “contact-page”.
Amazing! We now know how to create template files, add them to PW, and create pages with our new templates.
ProcessWire Variables
Lastly, we want to know how to render content added to the PW admin within our templates, and even use vanilla PHP to our site. One of my favourite things about PW is that it gives the theme coder instant access to content via variables and a suite of useful functions for the most simple functionality. Anything it doesn’t have, you can write in PHP yourself without worrying about what the system might do with your code. Neither must you follow strict class structures or hooks (I’m looking at you Drupal). In otherwords: it gives you a set of tools, then gets out of your way.
For a summarized list of all the variables and functions within PW check out the Processwire API Cheatsheet, and for further explanation see the PW variable docs.
Let’s quickly example some of the main variables to make our templates more functional.
Editing our home.php again, let’s add the page title, body, and sidebar content using the $page variable. $page gives you access to all the content uploaded to that page within the PW admin.
<?php include('./head.inc'); // include header markup ?>
<div id='content'>
<?php
// output 'title'
echo "<h1>" . $page->title . "</h1>";
// output body copy
echo $page->body;
?>
</div><!-- end content -->
<div id='sidebar'>
<?php
// output sidebar text if the page has it
echo $page->sidebar;
?>
</div><!-- end sidebar -->
<?php include('./foot.inc'); // include footer markup ?>
Let’s also add a simple navigation to our head.inc using the $pages variable. $pages gives you access to other pages with your site, which you can then query for content.
<!DOCTYPE html>
<html lang="en">
<head>
<title><?php echo $page->title; ?></title>
</head>
<body>
<nav>
<?php
// Get all children of the homepage
$child_pages = $pages->get("/")->children;
// foreach through each child page
foreach ($child_pages as $child) {
// echo child page link and title
echo '<a href="'. $child->url .'">'. $child->title .'</a>';
}
?>
</nav>
Next Steps
Now you know some of the basics of theming in PW I would urge you to look at some of the other site profiles contained with the PW download to see how they are structured. In my opinion, experimenting and getting feedback from the community can also be hugely beneficial.
Tip: you will find lots of modules that can help you in your site build on the modules page. If you’re a lover of LESS and scripts minification, I recommend the AIOM module.
And, of course, look out for future tutorials here at Envato Tuts+.