Perch and the Foundation 6 Framework: Building a portfolio layout

The latest version of the Foundation framework was released last week. As part of the Foundation site there are some example templates, demonstrating how to use Foundation to create a variety of layouts. I’m going to use one of those layouts to demonstrate a number of features of the Perch template language.

Watch this tutorial as a video

Perch and Foundation tutorial

My starting point is that I have Perch (or Perch Runway) installed. I have downloaded the Agency example page from the Foundation site and just dropped the single page template into my site folder. It already includes Foundation, using a CDN. So this is a very simple one-page example. We don’t need any additional files.

I have renamed the sample page as index.php so it can act as the homepage of my site.

To start using Perch on this page we first need to add the Perch runtime as the very first thing on the page. If you have downloaded Perch then you’ll find an example.php file with the runtime included – so you can just copy and paste.

<?php include('perch/runtime.php'); ?>

We can start with the big callout section at the top of the page.

Large Callout section

To create your template copy out all of the HTML and create a new file with just this fragment in. Save it into perch/templates/content as callout-large.html

I now want to make the content editable. I’m using the Perch template tag smarttext here for the heading and the strapline. This will convert quotes into nice quotes and a few other things but not add any other formatting.

In the full template below you can see how we keep the Foundation markup and just add our Perch tags where the content will be entered, replacing the dummy content from the example page.

The callout section contains two call to action buttons. I could add two buttons and just make the text and links editable. However I like to try and make my templates very flexible. So I am going to set this up so the box can have 1 or more buttons entered by using a repeater.

I am also using a select template tag to allow the ‘hollow’ class to be added to the button. I’ve used a select here in case I want to add other classes to this template in the future. The allow empty attribute on the select tag means that it is possible to not choose a value, which is what we need for a standard button.

template: perch/templates/content/callout-large.html

<div class="callout large">
  <div class="row column text-center">
  <h1><perch:content type="smarttext" id="heading" label="Heading" title="true" /></h1>
  <p class="lead"><perch:content type="smarttext" id="strapline" label="Strapline" /></p> 
  <perch:repeater id="buttons" max="3" label="Call to action buttons">
  <a href="<perch:content type="text" id="button_link" label="Button Link" />" class="button large <perch:content type="select" id="button_class" allowempty="true" options="hollow" />"><perch:content type="text" id="button_text" label="Button Text" /></a>
  </perch:repeater>
  </div>
</div>

Once I have created this template I can go back to my index.php page and delete the callout markup. Replace it with a Perch Region.

<?php perch_content("Homepage Feature"); ?>

After saving the page, we need to let Perch know that the new Region is there. We do this by reloading it in the browser. If I know log into the Perch Admin the new Region shows up, and I can select it and then choose my new callout-large template. This template then becomes the schema for my admin form.

Editing the large callout in Perch Admin

Fill in some content, save the form and the content and markup used in that template are now in place on the site. You can use the large-callout template anywhere you want this type of content to appear. Not just on the homepage.

We’ve now got some intro copy on the left and an image on the right. Then below that a set of three columns. I’m going to split these up and create two templates, one for the image and text two column layout and one for the three column layout.

Homepage content in the template

We can create a template for these in exactly the same way as the first template. I am saving the two column template as image-text.html.

I’m using the textarea tag, Markdown formatting and the MarkItUp editor for the content. This will enable content editors to use Markdown and give them a simple formatting toolbar to help. You could enable a WYSIWYG and HTML editing if you preferred.

For the image I’ll set a width and a height and set crop=true. Perch will then create an image with the correct dimensions if I upload something larger.

template: perch/templates/content/image-text.html

<div class="row">
  <div class="medium-6 columns medium-push-6">
  <img class="thumbnail" src="<perch:content type="image" id="image" label="Image" height="350" width="750" crop="true" />" alt="<perch:content type="text" id="alt" label="Alt Text for image" />">
  </div>
  <div class="medium-6 columns medium-pull-6">
  <h2><perch:content type="smarttext" id="heading" label="Heading" title="true" /></h2>
  <perch:content type="textarea" id="body" label="Body" editor="markitup" markdown="true" />
  </div>
</div>

The next template is for the three column section within row markup.

I’m going to create a template called cols3.html. Here I can use a Perch Repeater for these elements allowing the admin to add as many as I want. However we have markup before and after the repeating columns which creates the row in which our columns sit.

Inside the opening perch:repeater tag I add a pair of perch:before tags and add my row markup here. I close the row inside a pair of perch:after tags just before closing the repeater.

Between the before and after sections is just one column section with a smarttext heading and body content using Markdown as for the last template.

template: perch/templates/content/cols3.html

<perch:repeater id="columns" label="Columns">
  <perch:before>
  <div class="row">
  </perch:before>
  <div class="medium-4 columns">
  <h3><perch:content type="smarttext" id="heading" label="Heading" title="true" /></h3>
  <perch:content type="textarea" id="body" label="Body" editor="markitup" markdown="true" />
  </div>
  <perch:after>
  </div>
  </perch:after>
</perch:repeater>

I now have two templates that need to be added to my page in order that I can populate them with content. I could create two Perch Regions in my page, one for the two column section and one for the three column section. This would mean the editor had to add each of these in the position I had decided they should go.

Or, I could give the content editor the choice of which of these to use and the order they go in. I do this with Perch Blocks.

I create a blocks template saving that in perch/templates/content as foundation-blocks and then include my two templates each as a block.

template: perch/templates/content/foundation-blocks.html

<perch:blocks>
  <perch:block type="3col" label="Three columns">
    <perch:template path="content/cols3.html" />
  </perch:block>
  <perch:block type="imagetext" label="Image and Text">
    <perch:template path="content/image-text.html" />
  </perch:block>
</perch:blocks>

I’ve used Template Includes here but can add template markup directly inside the perch:block sections. However by creating individual templates and including them you now have the option of using the template on it’s own, or including it in Blocks. This is a great way of avoiding repeating yourself in your template code.

With this template saved we can add one Perch Region to the page and then select in Perch Admin the Blocks template. This then gives us the option to select either of the templates and add content. We could even add multiple instances of each template and drag them around to reorder them. Blocks gives a lot of control to content editors while still ensuring you remain in control of the mark-up. This is perfect when working with a framework like Foundation.

Editing with Blocks gives the editor a choice of template to use

We also have a little panel of stats, marked up as an ordered list.

The stats part of the design

Again, this is a great use of a Perch Repeater and the perch before and perch after tags.

template: perch/templates/content/stats.html

<perch:repeater id="stats" label="Statistics list">
  <perch:before>
    <hr>
    <div class="row column">
    <ul class="vertical medium-horizontal menu expanded text-center">
  </perch:before>

  <li><a href="<perch:content type="text" id="stat_link" label="Stat Link" size="m" />"><div class="stat"><perch:content type="text" id="stat_value" label="Stat Value" size="s" /></div><span><perch:content type="text" id="stat_label" label="Stat Label" size="m" /></span></a></li>

  <perch:after>
    </ul>
    </div>
    <hr>
  </perch:after>
</perch:repeater>

Once again this could be a standalone template added via a Perch Region, but equally I can add this to the Blocks template to give content editors the option of using this or not.

template: perch/templates/content/foundation-blocks.html

<perch:blocks>
  <perch:block type="3col" label="Three columns">
    <perch:template path="content/cols3.html" />
  </perch:block>
  <perch:block type="imagetext" label="Image and Text">
    <perch:template path="content/image-text.html" />
  </perch:block>
  <perch:block type="stats" label="Statistics">
    <perch:template path="content/stats.html" />
  </perch:block>
</perch:blocks>

Finally we have our portfolio items.

The portfolio images

These could be managed with a repeater but I think I will create these as a regular Perch Region set to allow multiple items. In the future I might want to link these to more detail about each portfolio item. Perch Repeaters are great for small amounts of content but if these expand out to a whole page of information then that would be too much content to edit all on one page in the Repeater box. If using Perch Runway then I would probably choose to create each Portfolio Item as a Project in a Collection and then show images from the Collection here.

The template however is much the same as the Repeater templates we created earlier with before and after sections for markup that needs to be output before and after the repeating section.

<perch:before>
  <div class="row column">
  <h3>Our Recent Work</h3>
  </div>
  <div class="row medium-up-3 large-up-4">
</perch:before>
<div class="column">
<img class="thumbnail" src="<perch:content type="image" id="image" label="Image" height="550" width="550" crop="true" />" alt="<perch:content type="text" id="alt" label="Alt Text for image" />">
</div> 
<perch:after>
  </div>
</perch:after>

I then add a region to my page and in the admin select my new template. In the region options I choose to allow multiples – and I’m also unchecking edit all on one page. So we’ll edit in list detail mode.

Perch Control Panel setting region options

I can now add my images, and see them appear on the site.

Perch has been designed to make working with exactly the markup that you need to use, possible and easy. We’ve looked at just a few of the features in this post:

Repeaters
Perch Before and Perch After
Template tag types image, smarttext, text, select and textarea
Blocks
Template Includes

Take a look at the full template documentation to see what else you can do with Perch.

The templates created for this tutorial can be found on GitHub. If you are using Foundation and have some templates to share, submit them as a Pull Request and we’ll add them to the repo.