Help / Content Templates

How templates work

When a new content tag is identified, the first step of editing is to choose a template. The template is an HTML file that represents the final output that Perch will insert into your pages. Perch defines a number of template tags that act as placeholders for content. The content editing page will present a form field of each of these placeholders.

This may be easiest to see through an example.

<h2>
    <perch:content id="heading" type="text" label="Heading" />
</h2>

<p class="date">
    <perch:content id="date" type="date" label="Date" />
</p>

<perch:content id="body" type="textarea" label="Body" />

This is a template for a simple article that has three elements to it - a heading, a date and the body of the story. When editing content that uses this template, the user will be presented with three edit fields - a simple text field for the heading, a date picker for the date and a textarea for the article body.

NB: The <perch:content /> tags are of course replaced by the published content, so no custom tags appear in the final page.

Where your templates live

Templates for your installation of Perch are in:
perch/templates/content

Templates are just HTML files. You can add as many templates as you like (they are shown by file name in the interface), and delete any that aren't already in use.

If you make a change to a template that is already in use, your changes won't show up until the content is next edited. This is because templates are applied as the content is edited, not as the page is loaded. (This keeps you pages nice and quick to load.)

Basic tags

The basic tag is:

<perch:content />

There are three required attributes:

id

A unique identifier for the content. Use letters, numbers and underscores only.

type

The type of content (see below).

label

A nice label to use for the field in the editing interface. May contain spaces, capitalisation etc. to look presentable.

So a basic tag might look like this:

<perch:content id="main_heading" type="text" label="Main heading" />

The id identifies the content uniquely, but not the tag. That is to say, if you want to reused the same content multiple times in a template, you can do so by reusing the id. The user will only be asked for the content once, but it can appear multiple times in the template.

You can email us at: 
<a href="mailto:<perch:content id="email" type="text" label="Email address" />"> 
    <perch:content id="email" type="text" label="Email address" />
</a>

Optionally, you can specify the following attributes:

required

True or false. States whether the content should be a required field in the editing interace.

order

Integer. Provides a mechanism for customising the order in which the items appear on the edit form. Specify order="1" to place an item first, order="2" to place an item second, and so on.

help

Text string. A brief piece of instructional text that will be displayed alongside the item on the edit form.

suppress

True or false. When true, the value of the field is not included in the output.

chars

Integer. The number of characters from the field to display in the output. Useful for creating excerpts.

words

Integer. The number of words from the field to display in the output. Useful for creating excerpts.

Types

The type attribute can take one of a number of values that control how the content is edited. Mostly this results directly in which type of form field is used in the editor.

type="text"

Text is the simplest content type - it represents a basic line of text, and is edited with a single-line text input. May optionally be used with:

textile

True or false. Whether to allow Textile formatting for the content.

markdown

True or false. Whether to allow Markdown formatting for the content.

html

True or false. Whether to allow HTML to be used in the content.

maxlength

Integer. The number of characters that can be input to the form field.

Note that you should only use one formatting language at a time (i.e. either Textile or Markdown).

type="textarea"

Textarea represents a multi-line block of text, and is edited with a textarea input field. May optionally be used with:

textile

True or false. Whether to allow Textile formatting for the content.

markdown

True or false. Whether to allow Markdown formatting for the content.

html

True or false. Whether to allow HTML to be used in the content.

editor

The name of the JavaScript content editor to apply to the textarea. Set to markitup to use the default editor.

type="date"

A date, edited using a group of select boxes (day, month, year). May optionally be used with:

format

Date formatting code, e.g. format="d M Y". Accepts either PHP date formatting (which does not support locale settings) and strftime formatting (which does).

time

True or false. Set to true to enable the selection of hours and minutes as well as days, months and years.

type="select"

A select box with a list of predefined options. May be used with:

options (required)

A comma-separated list of options e.g. options="House, Appartment, Room-share". If different values and labels are required, add the value after a vertical bar e.g. options="House|1, Appartment|2, Room-share|3"

allowempty

True or false. If set to true, the initial option in the list will be blank, allowing a no-value selection.

type="radio"

A set of radio buttons. May be used with:

options (required)

A comma-separated list of options e.g. options="House, Appartment, Room-share". If different values and labels are required, add the value after a vertical bar e.g. options="House|1, Appartment|2, Room-share|3"

type="checkbox"

A single on/off checkbox. May be used with:

value (required)

The value assigned to the checkbox when it is checked, and therefore what is added to the content.

type="image"

An image file upload facility. This template tag will return the path to the image, not a complete image tag. It can therefore be used in the src attribute of an image tag, with an additional text field used for the alt.

width

Integer. The maximum width allowed, in pixels. The image will be proportionally scalled down if the width exceeds the give value.

height

Integer. The maximum height allowed, in pixels. The image will be proportionally scalled down if the height exceeds the give value.

crop

True or false. Whether to crop the image to a fixed size. Requires both width and height to be set.

type="file"

A file upload facility. This template tag will return the path to the file.

type="slug"

Create a URL-safe slug from the content of one of the other fields. Doesn't display anything on the edit form, just works in the background.

for

The ID of the field to make the slug from.

<perch:content id="heading" type="text" label="Heading" required="true" />
<perch:content id="slug" type="slug" for="heading" />

type="hidden"

A special field that is not shown in the edit form, but its value is included in the output. This is used with predefined special values.

Conditional tags

Sometimes, you only want to output a section of the template if a piece of content has been given. For example, if no heading content has been given, you don't want to output a set of empty <h2></h2> tags. This is where conditionals come in. Here's an example:

<perch:if exists="heading">
    <h2>
        <perch:content id="heading" type="text" label="Heading" required="false" />
    </h2>
</perch:if>

The above example will only output the HTML inside the <perch:if></perch:if> tags if a value has been entered for the heading. You can wrap the conditional tags around any part of the template, and you may include one conditional tag inside another.

The <perch:if></perch:if> conditional tag takes the following attributes:

exists

The id of a content item to check for a value. If the item has no value, the HTML inside the conditional tags will not be used.

If you want to provide an alternative when the condition is not met, you can use the <perch:else /> tag. Anything that comes after it is treated as the else.

<perch:if exists="name">
    <perch:content id="name" type="text" label="Name" required="false" />
<perch:else />
    Author unknown
</perch:if>

User help

As well as providing instructional text alongside each field with use of the help attribute, you may specify a larger section of instruction at the top of the edit form.

This is achieved with the use of a help block:

<perch:help>
    <p>Any amount of HTML-formatted help can be specified here, 
        including images and links if required.</p>
</perch:help>

The help block is taken as-is and placed at the top of the edit form. When the content is published, the help block is not included in the HTML output.

Special values

There are a small number of predefined special values that can be used within a template. These would normally be hidden from the edit form, as the values are dictated by Perch.

The following special values are defined:

perch_item_index

The number of the item within a multiple-item region. Outputs 1 for the first item, 2 for the second and so on.

_id

The unique ID of that item of content within the region. This does not change throughout the life of the content.

perch_item_odd

Outputs odd for odd-numbered items with a multiple-item region, and nothing for even items.