Perch documentation

Creating Templates

After creating a Perch editable region on a page the first thing you do in the administration is define which template the region should use. Perch ships with some standard templates, to help you get started editing basic content quickly. However it is likely that you will also want to create your own.

Perch templates live inside the Perch folder, then inside templates/content.

As you can see these are just .html files and can be opened in your usual plain text editor.

Templates range from the very simple – such as text.html which just includes the Perch tag for adding a single line of text. To the more complex such as contact.html which has the mark-up for the Microformats hcard format along with a number of Perch tags. Selecting a contact template for a region in the admin would present the user with a form with several fields to complete.

How templates work is easiest to see with a simple example.

In my example site I have a section in the sidebar that I would like to make editable so the client can add a heading and a piece of text. Rather than just giving them a large text entry field and hoping they use the right type of heading, I am going to create a special template for that area with the mark-up I want.

In my about/index.php page I find the placeholder content for this area and copy out the entire module.

I save this as a new .html file inside perch/templates/content – named sidebar_module.php

Now I can add Perch tags to replace the text. Inside the h2 element I want the user to add a single line of text with no other mark-up – just the heading text so I use a text type:

<perch:content id="title" type="text" label="Heading" required="true" title="true" />

Under the heading I want to allow the client to add text that they can format with links, bold and italic and so on so I am using the textarea type with Textile set to true and the simple editor that ships with Perch ‘markitup’ set as the value for editor.

<perch:content id="text" type="textarea" label="Text" textile="true" editor="markitup" /> 

I am replacing all of the mark-up and content here as Textile will wrap a line of text in a paragraph element.

Save the template and go back to about/index.php

Replace the content that we copied out with a Perch editable region. I’m calling this one “sidebar module”.

Reload the page in the browser to tell Perch the new region is there and go back to Perch admin.

The new region should display. Click on and and select our new sidebar module template from the list. Submit the form and the edit page that will display to your editor will appear. You should be able to see that we have two fields – a heading and content area, the content area has a simple editing toolbar. Add some content and submit the form.

Back on our site, reload the page to see the new content appear. You have now created your first Perch template.

A detailed explanation of template tags can be found in the documentation at or continue to follow along with these videos for further template creation advice.