When ProcessWire loads a template file, it hands it a copy of the current $page, along with all of the other ProcessWire API variables. Beyond that, it is just a regular PHP file. What happens within that file is entirely to the developer.

ProcessWire knows nothing about the type of output you intend to produce with that template file. In fact, you can produce any kind of output with your template file, which is one of the reasons why ProcessWire is so flexible. But with flexibility comes some ambiguity, especially for developers new to ProcessWire. Such developers may be asking themselves "what exactly should I put in this template file?" or "what are the best practices?".

With this tutorial, we hope to outline some of the more common strategies used by developers in structuring template files. So as not to extend the scope too broadly, we'll limit this tutorial to output of HTML documents and the different methodologies one might use.

Remember to enable debug mode

Regardless of what template file strategy you use, you will almost always want debug mode ON when you are working with template files. This ensures that you see error messages and notices as they occur. On a production site you would of course want error messages suppressed so that they do not interfere with the user–or worse–reveal sensitive details that might affect security. But when developing a site and making edits to template files, you most certainly want to see error messages and notices, otherwise it would be very difficult to make progress! Edit your /site/config.php file, locate the line referring to $config->debug and change it from false to true.


$config->debug = true; 

Remember to change it back to false before your site is live.

Next: Direct Output »

  1. Introduction
  2. Direct Output
  3. Direct Output with Includes
  4. Delayed Output
  5. More Strategies


  • Kristoffer

    Kristoffer 4 years ago 63

    If you are having trouble loading the $config->prependTemplateFile and $config->appendTemplateFile variables, make sure that your FTP user has write permissions to the ProcessWire Configuration File. When config.php is write protected ("chmod 444 config.php", or similar) on the FTP server, you may not notice that changes to config.php are not uploaded to the server.

  • Bernhard

    Bernhard 4 years ago 74

    really great tutorial! thank you ryan!

  • pwired

    pwired 4 years ago 52

    Thanks to the forum I arrived here after the release
    of pw-2.5.0. Pages 3, 4 and 5 explain very nice how
    header and have been evolved in pw-2.5.0

  • adrian

    adrian 4 years ago 32

    With the example shown on the above documentation, the output website page layout is fixed in $config->appendTemplateFile in config.php. If I have a page with a different layout, how to deal with it ?

    • ryan

      ryan 4 years ago 22

      There are any number of ways you could do it, but simplest would be just to go to your template settings (Setup > Templates > your-template > Files [tab]), and specify a different append/prepend file for that template.

  • James

    James 4 years ago 42

    Hi Ryan

    I am new to PW, having come from building many sites previously with Concrete5. With the Delayed Output approach, and the use of, does this not leave you with one file solely responsible for the structure of every page on the site? For example, what if I have a home page that is full width. I might also have some pages with sub nav, and hence the need for a sidebar. Maybe on my blog page I might want a three column approach with nav on one side and categories on the other.

    Is responsible for having to structure each of these pages? Or, would you approach this differently by having different versions of ie there might be a,, etc



    • ryan

      ryan 4 years ago 43

      James, the can be swapped out with whatever you want on a template-by-template basis (see my reply to Adrian below). However, the reality is that there's often going to be as much similar as there is different, regardless of layout. And you want to avoid repeating yourself. So you might choose to make your include different layout (.inc) files, or simply have something like if($sidebar) then output a sidebar column, etc. The default site profile has an example of this. Another way is to define a $layout variable (or whatever you want to call it) in your that indicates a default layout file. Then any of the template files can choose to change that. Then the file can take that $layout into account to render or include accordingly.

  • Alex

    Alex 2 years ago 20

    Suppose hat I have to create a set of new pages which uses a template(say template_2)different than the rest of the website. In my site/config, I have
    $config->prependTemplateFile = '_init.php';
    $config->appendTemplateFile = '_main.php';

    However, I do not want the sidebar and navigation I had defined in the main.php for the template_2. I want to have different footer,header and sidebar. Any suggestions how I can add an exception such that when I load template_2, I should not include the original _init.php and _main.php and should load from some _init2.php and _main2.php?

    • Pavel

      Pavel 2 years ago 00

      Hello Alex, look at this post.

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.