Guides
Tutorials
Pop Tags

Includes & Layouts

There are typically quite a few different templates in a Webpop project. It’s common for sections to have their own template in addition to other templates for categories and entries.

Most sections have some differences, so making separate templates make sense. But the final HTML of most pages usually shares some common components such as a header, main navigation, footer or common sidebar.

Includes

A basic way to avoid repetition in your markup is to use includes. Any template can include any other template by using the <pop:include> tag. This example uses an include for a main menu:

includes/nav.tpl

<pop:sections wrap="ul" break="li">
  <a href="<pop:permalink/>" class="<pop:active>active</pop:active>"><pop:title/></a>
</pop:sections>

index.tpl

<!doctype html>
<html>
  <head>
    <title><pop:title/></title>
  </head>
  <body>
    <div id="main">
      <pop:content>
        <h1><pop:title/></h1>
        <pop:body/>
      </pop:content>
    </div>

    <div id="sidebar">
      <pop:include template="includes/nav" />
    </div>
  </body>
</html>

Place your includes in a folder called “includes” or prefix them with an underscore (like _nav.tpl). Then they won't show up in the dropdown used to associate a content with a template.

Right now, all other templates in this site would still need to repeat the doctype, the html, head and body tag and the structure for the #main div and the #sidebar. In many cases the only thing to change would be the content of the #main div. We can go further DRY up the code in the above example by using a layout.

Layouts

<pop:layout> can be thought of as the opposite of an include. While an include inserts another template, <pop:layout> works the other way around and insert your template into a layout.

Here’s how the same example as above would look if we used the layout approach instead:

layouts/default.tpl

<!doctype html>
<html>
  <head>
    <title><pop:title/></title>
  </head>
  <body>
    <div id="main">
      <pop:region name="main"/>
    </div>

    <div id="sidebar">
      <pop:sections wrap="ul" break="li">
        <a href="<pop:permalink/>" class="<pop:active>active</pop:active>"><pop:title/></a>
      </pop:sections>
    </div>
  </body>
</html>

index.tpl

<pop:layout name="default"/>
<pop:block region="main">
  <pop:content>
    <h1><pop:title/></h1>
    <pop:body/>
  </pop:content>
</pop:block>

The layouts/default.tpl mostly looks like the templates you’ve seen so far. The only difference is the new <pop:region name="main"> tag. This tag marks a region of the layout that a template can replace.

This index.tpl now only includes markup that deals with displaying the current content. <pop:layout> tells the PopTags engine to use the “default” layout with this template. <pop:block region="main"> specifies the region of the layout template to replace with the contents of the block.

If a template uses a layout, the <pop:layout> tag should be at the first line of the template and there should be no other markup outside of <pop:block> tags.

Layouts can have multiple regions and regions can have default values. Lets make the navigation in the sidebar optional and override it in the index template:

layouts/default.tpl

<!doctype html>
<html>
  <head>
    <title><pop:title/></title>
  </head>
  <body>
    <div id="main">
      <pop:region name="main"/>
    </div>

    <div id="sidebar">
      <pop:region name="sidebar">
        <pop:sections wrap="ul" break="li">
          <a href="<pop:permalink/>" class="<pop:active>active</pop:active>"><pop:title/></a>
        </pop:sections>
      </pop:region>
    </div>
  </body>
</html>

index.tpl

<pop:layout name="default"/>

<pop:block region="main">
  <pop:content>
    <h1><pop:title/></h1>
    <pop:body/>
  </pop:content>
</pop:block>

<pop:block region="sidebar">
  <h2>This Shows up instead of the sidebar region</h2>
</pop:block>

In this case we’ve put some markup inside the sidebar region. This markup will be shown for any template that doesn’t specify a block for the sidebar.

Continue to Forms »