Perch Layouts

In Perch 2.2 we introduced a new feature to help in structuring your Perch sites – Layouts.

Perch does not have any concept of themes – you can always just include Perch and add Perch regions to your existing sites without changing your workflow. However, if you are building a brand new site and know you are using Perch from the outset, layouts are just one way we can help you structure your site. Layouts can be used for those parts of your site that do not change – for example a header and footer. They can include HTML, PHP and even Perch function calls.

Earlier this year I launched a new blog to write about my fitness adventures. I’m not a designer and so used the default Quill Feather to get the site up and running quickly. You can see the site at After upgrading to 2.2 I thought that I would use the new layouts feature to tidy up my pages.

Adding layouts is simple, just create a folder in perch/templates named layouts. Inside that folder place your layout fragments as PHP files. You can find some suggestions on naming conventions in the layouts documentation. My layouts are as follows:


<!DOCTYPE html>
<html lang="en">
  <meta charset="utf-8">
  <title><?php perch_layout_var('title'); ?></title>
  <meta name="viewport" content="width=device-width, 
target-densitydpi=160dpi, initial-scale=1.0" />
  <?php perch_get_css(); ?>
<header class="layout-header"><img src="/img/header.jpg" alt="" />
  <nav class="main-nav">
      <li><a href="/">Home</a></li>
      <li><a href="/blog">Blog</a></li>
      <li><a href="/events">Events</a></li>
      <li><a href="/stats">Stats</a></li>
<div class="wrapper cols2-nav-right">

<h3>Things I like</h3>
<p><a href="">
<img src="/img/perch.png" alt="This site runs on Perch - the really little CMS" /></a></p>
<p><a href="">
<img src="/img/sportpursuit.gif" alt="Sport Pursuit" /></a></p>


<footer class="layout-footer">
  <div class="wrapper">
    <small>Copyright &copy; <a href="">Rachel Andrew</a>
 <?php echo date("Y"); ?></small>
<?php perch_get_javascript(); ?>

Including the layouts

As you can see from the above these layouts include HTML, PHP and Perch functions – such as the calls to perch_get_css() and perch_get_javascript() used to include the Quill Feather.

To use these layouts in your site, on a site page use the function perch_layout() and pass in the filename of the layout. To call in my footer I use:

<?php perch_layout('global.footer'); ?>

Passing in variables

You may notice that in my header include I use the following code in the title element.

<?php perch_layout_var('title'); ?>

A useful feature of layouts is having the ability to pass in variables. We do that by creating an array and passing it into the perch_layout function. This means I can have a unique title on each page even though I am using a layout. When I include the header layout on the homepage I use the following code.

<?php perch_layout('global.header', array(
	'title'=>'Trying not to come last, the personal fitness blog of Rachel Andrew'
)); ?>

This then makes title available as a variable inside the layout.

On my blog post page I want to pass in the title of the post as part of the title. I can do this by get the title of the post and creating a string including that to pass to perch_layout:

  $title = perch_blog_post_field(perch_get('s'), 'postTitle', true) .' - trying not to come last';
  perch_layout('global.header', array('title'=>$title)); ?>

Example site

I have posted my files and Perch templates onto Github so that you can use them as a starting point. They demonstrate a simple site using Layouts, the Quill Feather, Blog and Events. Feel free to use this as a starting point for your own site or as a learning tool.

Read the layouts documentation for more information about how Layouts work.