Direct Output with Includes

When we want to utilize the convenience of direct output, but don't want to repeat the same markup in every template file, we move the code that we want to re-use into separate files. That way we can have multiple template files that pull in the same bits of code without us having to repeat ourselves. The benefit is that if we need to change something, we only need to change it in one place rather than in all of our template files.

To get started, lets figure out the parts of our basic-page.php template file that we want to re-use in other template files. In this case, we know that the markup at the top of all our template files will be the same, so lets move that to a head.inc file (or whatever you want to name it). We'll use the .inc extension for the file just to clarify that it is a file meant to be included in others, rather than a dedicated template file of it's own (though this naming convention is optional).

/site/templates/head.inc

<html>
  <head>
    <title><?php echo $page->title; ?></title>
  </head>
  <body>
    <h1><?php echo $page->title; ?></h1>

We also know that the markup at the end of all our template files will be the same, so we'll move that markup into a foot.inc file.

/site/templates/foot.inc

</body>
</html>

Where the template files will vary is what's in-between head.inc and foot.inc. So we'll use our basic-page.php template file to do the following, in this order:

  1. include the head.inc file
  2. output content
  3. include the foot.inc file

Here's how we might do that:

/site/templates/basic-page.php

<?php
include("./head.inc");
echo $page->body;
include("./foot.inc"); 

The output is identical to when basic-page.php was an entire HTML document. But our template file has become a lot smaller, and we can re-use our head.inc and foot.inc in any other template files that we want to. For instance, we might have another template called sidebar-page (with file sidebar-page.php) that produces output similar to basic-page.php while being able to support separate bodycopy and sidebar columns:

/site/templates/sidebar-page.php

<?php include("./head.inc"); ?>
  <div id='bodycopy'>
    <?php echo $page->body; ?>
  </div>
  <div id='sidebar'>
    <?php echo $page->sidebar; ?>
  </div>
<?php include("./foot.inc"); ?>

Using includes for head.inc and foot.inc is just for starters. You can use includes for literally anything. Many people refer to these types of includes as partials. You can extend their use to anything that you might want to repeat or reuse in any template file.

Direct output with automatic inclusions

It's not actually necessary to manually include("./head.inc") and include("./foot.inc") in each of your template files. You can make this happen automatically by editing your /site/config.php file and populating these two lines like so:

$config->prependTemplateFile = 'head.inc';
$config->appendTemplateFile = 'foot.inc';

What the above essentially says is to automatically load the contents of head.inc file before your template file (prepend), and load the contents of foot.inc after your template file (append). The result is that it's no longer necessary to manually include those in each of your template files. These automatic inclusions actually come in handy in other template file strategies too, so keep them in mind!

Disadvantages of direct output

Where direct output starts to fall apart is when you want to affect the output in multiple regions on a page. In our examples above, our template files only control the output for what comes between head.inc and foot.inc. While we could accommodate more regions with additional includes, it starts to get a little cumbersome. What if any of our template files could populate any region in our markup without us having to know exactly where it will go ahead of time? That leads into our next strategy…

Next: Delayed Output »


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

Comments

  • Kristoffer

    Kristoffer 3 years ago 52

    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 3 years ago 64

    really great tutorial! thank you ryan!

  • pwired

    pwired 3 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 footer.inc have been evolved in pw-2.5.0

  • adrian

    adrian 3 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 3 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 3 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 main.inc, 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 main.inc responsible for having to structure each of these pages? Or, would you approach this differently by having different versions of main.inc? ie there might be a sidenav-page.inc, full-width.inc, blog-entry.inc etc

    Regards

    James

    • ryan

      ryan 3 years ago 43

      James, the main.inc 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 main.inc 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 init.inc that indicates a default layout file. Then any of the template files can choose to change that. Then the main.inc file can take that $layout into account to render or include accordingly.

  • Alex

    Alex 9 months ago 10

    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 8 months ago 00

      Hello Alex, look at this post.
      https://processwire.com/talk/topic/8767-regarding-delayed-output/?do=findComment&comment=84604

Post a Comment

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