How to Develop a Processwire Theme

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


Learning how PW routes its pages will help us construct our custom templates later on.

When a PW page is requested (e.g., 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:

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 “” and “” 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:

Add our


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.

Let’s also add a simple navigation to our using the $pages variable. $pages gives you access to other pages with your site, which you can then query for content.

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+.

Leave a comment

Your email address will not be published.