Cheat Sheet

Content Tags: <perch:content/>

What is a content tag?

The basic tag is:

<perch:content/>

Content tags must have the required attributes:

  • id
  • type
  • label

A basic tag would be:

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

The id template attribute is a unique identifier for the content. It is a required attribute. Use letters, numbers and underscores only for an id.

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

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

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

The value of the type attribute may be one of the following:

  • text
  • textarea
  • date
  • select
  • radio
  • checkbox
  • image
  • file
  • slug
  • hidden
  • map
Documentation
type="text"

Text is the simplest content type – it represents a basic line of text, and is edited with a single-line text input.

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

Textarea represents a multi-line block of text, and is edited with a textarea input field.

<perch:content id="body" type="textarea" label="Article body" textile="true" editor="markitup" /> Documentation
type="date"

A date, edited using a group of select boxes (day, month, year).

Date formatted as Sun 04 July 10 using date options:

<perch:content id="event_date" type="date" label="Date of event" format="D d F y" />

Locale-compatible date Sunday, 4 July 2010 using strftime options:

<perch:content id="event_date" type="date" label="Date of event" format="%A, %e %B %Y" /> Documentation
type="select"

A select box with a list of predefined options. This requires a list of options.

Options is a comma-separated list of options e.g. options="House, Apartment, 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"

<perch:content id="course_time" type="select" label="Time of course"
options="AM, PM, Full day, Evenings" allowempty="false" required="true" />
Documentation
type="radio"

A set of radio buttons with a list of predefined options. This requires a list of options.

Options is a comma-separated list of options e.g. options="House, Apartment, 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"

<perch:content id="course_time" type="radio" label="Time of course"
options="AM, PM, Full day, Evenings" allowempty="false" required="true" />
Documentation
type="checkbox"

A single on/off checkbox. Requires the value attribute to also be part of the tag. The value attribute is the value assigned to the checkbox when it is checked, and therefore what is added to the content.

<perch:content id="sale_item" type="checkbox" label="Sale item" value="sale" /> Documentation
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.

<perch:content id="logo" type="image" label="Logo" width="200" height="100" crop="true" /> Documentation
type="file"

A file upload field, the tag will return the path to the file.

<perch:content id="report" type="file" label="Annual report PDF" /> Documentation
type="slug"

Creates a URL-safe slug from the content of one of the other fields. This template tag doesn't display anything on the edit form, it just works in the background.

Requires a for attribute, this is the ID of the field to make the slug from.

The following takes the value entered into the heading field and makes a URL-safe version of it, storing it as the slug field.

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

A special field that is not shown in the edit form, but whose value is included in the output.

<perch:content id="order" type="hidden" label="Order" /> Documentation
type="map"

Map embeds a Google Map in the page. The editor can search for a location, position and zoom the map, set the map type and place a pin on the map.

<perch:content id="map" type="map" label="Address" width="400" height="300" zoom="15" /> Documentation Video: adding a Google map to your site
label

The label attribute is used to present a nicer field description when editing content. It may contain spaces, capitalisation etc. to look presentable.

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

States whether the content should be a required field in the editing interface.

<perch:content id="main_heading" type="text" required="true" label="Main heading" /> Documentation
order

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.

<perch:content type="text" id="heading" label="Heading" order="1" /> Documentation
help

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

<perch:content type="text" id="heading" label="Heading" help="Give the article a title" /> Documentation
suppress

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

<perch:content type="checkbox" id="instock" label="Item is in stock" value="true" suppress="true" /> Documentation
chars

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

<perch:content type="text" id="heading" label="Heading" chars="100" /> Documentation
words

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

<perch:content type="text" id="heading" label="Heading" words="20" /> Documentation
title

Whether the field should be used as the title field for the item in the Perch editing interface.

If multiple fields have title="true" set, they are concatenated together with a space to form the title.

<perch:content type="text" id="heading" label="Heading" title="true" /> Documentation
default

The default value for the field when a new item is created.

<perch:content type="text" id="heading" label="Heading" default="This is the news" /> Documentation
format

The format attribute can be used to change the formatting of the content as it is output.

  • Dates and times: When used on a date (or date and time) field, format ccepts either PHP date formatting (which does not support locale settings) and strftime formatting (which does).
  • Numbers: To format a number, start your formatting code with #: followed by the number of decimal places to use: format="#:2"
  • Money: To format currency values, Perch again hooks into some native PHP functionality. Begin your value with $: and then add any valid PHP money format string.
Documentation
urlify

The urlify attribute converts the value of a field to a basic URL-safe version.

<perch:content id="title" type="text" label="Title" urlify="true" /> Documentation
replace

The replace attribute offers some basic string replacement as the content is output. It's not intended for heavy-lifting, just small tweaks.

The value of the replace attribute is the value to search for, followed by a | followed by the value to replace it with. Multiple items can be added with commas.

<perch:content type="text" id="aperture" label="Lens aperture" replace="f|ƒ" /> Documentation

Basics & Configuration

Where are my templates?

Templates live inside: /perch/templates/content

You can edit the default templates or create new templates of your own.

Documentation
Creating & naming templates

Templates must be .html files, they can contain any html and Perch tags, however they may not contain PHP code.

Any template added will appear in the web interface to select when creating new content. If you do not want the template to appear start the name with an underscore _hidden.html.

Tutorial video: creating templates
Using a .html file extension

If your host allows you can set your server to parse PHP in .html files in addition to .php files by adding the following to your .htaccess file:

AddType application/x-httpd-php .php .htm .html Documentation
Enabling/Disabling HTML5

HTML5 markup is enabled by default.

If you wish to stick with HTML 4 or XHTML, set the HTML5 constant to false in your config file.

define('PERCH_HTML5', false); Documentation

Providing help

Adding help text to a template

You can add a block of help text to the top of a template by using the perch:help tags

<perch:help>
<p>Specify your HTML formatted help here.</p>
</perch:help>
Documentation
Adding help to a field within a template

Use the help attribute to add a brief piece of instructional text that will be displayed alongside the item on the edit form.

<perch:content type="text" id="heading" label="Heading" help="Give the article a title" /> Documentation

Working with images

How can users upload images?

Perch provides a number of ways for your users to work with images. You can use the image content type in a template for full control of location and size of images or allow uploads via the MarkItUp or ckEditor plugins.

Documentation: image content type
Images in templates: resizing and cropping

Using the image content type will present a file upload field in the administration form and the editor can upload an image from their computer. It is most likely that you will want to have some control over the dimensions of the image and so you can set the following attributes:

  • width
  • height
  • crop
  • quality

Setting width and height will scale the image. If you only set width then the image ratio will remain the same to scale the height, likewise if you set height we will scale the image within the correct ratio to get the width. If you want to force the image to a certain width AND height (for example making a square thumbnail) you need to set both width and height and also set the attribute crop to true.

The quality attribute lets you control the compression Perch applies. Values are between 0 (very compressed) to 100 (not compressed). The default is 85.

<perch:content id="thumbnail" type="image" label="Thumbnail" width="40" height="40" crop="true" /> Documentation: image content type
MarkItUp Editor: resizing and cropping

The editor included in Perch has the ability to upload files into a textarea content block in Perch. Images can be optionally resized by using the imagewidth, imageheight and imagecrop attributes on the textarea content tag

<perch:content id="body" type="textarea" label="Article body" textile="true" editor="markitup" imagewidth="100" imageheight="100" imagecrop="true" /> Documentation: image content type

Conditional Tags

if

The <perch:if></perch:if> conditional tag can be used to only include a section of the template if a value has been set for one of the fields. It takes the attribute exists which is 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.

<perch:if exists="name">
    <h2><perch:content id="name" type="text" label="Name" /></h2>
</perch:if>
Documentation Video: creating a contact details template using perch:if
else

If you want to provide an alternative when a <perch:if> 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">
     <h2><perch:content id="name" type="text" label="Name" /></h2>
<perch:else />
     Author unknown
</perch:if>
Documentation
before

The <perch:before></perch:before> conditional tag is used to contain any part of the template to be output at the start of the region, if the region contains content.

For multiple item regions, the content inside <perch:before> tags is only displayed before the first item in the region.

<perch:before>
    <h2>Latest news</h2>
</perch:before>

<h3><perch:content id="newsTitle" label="Title" type="text" /></h3>
<perch:content id="newsSummary" label="Summary" type="textarea" words="30" />
Documentation Video: using perch:before and perch:after
after

The <perch:after></perch:after> conditional tag is used to contain any part of the template to be output at the end of the region, if the region contains content.

For multiple item regions, the content inside <perch:after> tags is only displayed after the last item in the region.

<perch:before>
    <ul>
</perch:before>

        <li><perch:content id="newsTitle" label="Title" type="text" /></li>

<perch:after>
    </ul>
</perch:after>
Documentation Video: using perch:before and perch:after
every

The <perch:every></perch:every> conditional tags are used within a template which outputs multiple items. They can be used if you need to output something different every other item, or every 3 items and so on. They take the following attributes:

  • count - A simple integer. A value of 3 would match for every third item.
  • nth-child - An alternative to count. Takes CSS-style nth-child values.
<perch:every count="3">
  This happens every 3 items.
</perch:every>

<perch:every nth-child="odd">
  Odd items only
</perch:every>

<perch:every nth-child="2n+3">
  I'm not even going to pretend I understand these - but they work!
</perch:every>
Documentation

Search

Search Basics

In the Perch download you should find an example page in the root of the download called search.php. This is an example of the page that users will visit to search your site.

Also in the Perch download is a template in perch/templates/search. This template has all of the search template fields in it, including paging and can be used as is or you can edit the mark-up as with any Perch template.

To get search working make sure you have the template in your site in perch/templates/search then visit search.php in your browser and search for things that appear in your content.

Documentation Video: using Search
The Search template

The default search template can be found in perch/templates/search it is a fully featured template containing all of the possible things you might want to have on your search page, including a search form.

It uses perch:before and perch:after tags to dictate what displays if a listing is present.

Documentation
Setting titles on listings

By default, the search will display the page path as the 'title' of the result, unless the item has title="true" set on one if the items in the template.

That's the same attribute that changes the "Item 1, Item 2, Item 3" list on the edit page to something meaningful. So it's recommended that you set title="true" in your templates wherever possible, and then resave your content so it takes effect.

Documentation
Searching list/detail pages

If you have multiple item regions set up in a list/detail arrangement with perch_content_custom, you need to go into your region options and set the "URL for search results" option. This is how you tell the search result page how to display content for that region. You'd set it to something like /news-article.php?s={slug} and the {slug} will get replaced out with the value of the slug field for that item when the results are shown.

Documentation
Customize search listings

The perch_content_search() function accepts 3 variables:

  1. The keywords you want to search for - this is required.
  2. An array of options, which can include:
    • count: count (default 10) number of items to show per page
    • from_path, to search only part of a site, e.g. '/en/' to just search your English pages
    • excerpt_chars (default 250) number of characters for the excerpt on the result page
    • template - which is a filename inside templates/search
  3. return results (default false) whether to echo or return the result
<?php
  if (isset($_GET['q'])) {
    $query = $_GET['q'];
  }else{
    $query = '';
  }
  $opts = array(
    'count'=>5,
    'from_path'=>'/articles',
    'excerpt_chars'=>300,
    'template'=>'my_template.html'
  );
  perch_content_search($query,$opts);
?>
Documentation

Forms

Overview of form

Forms can be created which submit to an external script (for example if you are sending signups to Campaign Monitor or Mailchimp) or can submit to your site in which case you would need to install the Form App which enables you to decide how to process the forms. You can choose to send the data in an email and/or capture and store the data in your admin area where it may be downloaded as a CSV. You could then save this into Excel for example.

Perch Forms implement all the new HTML5 input types and elements if you have set Perch to use HTML5. In a supporting browser this gives your users all the benefits of these new fields. In addition the validation implements a serverside version of these elements, so if the user does not have a supporting browser the serverside validation will catch the required formats.

Documentation Video: working with forms
Form tags: perch:form

To create a form in Perch it must open and close with perch:form tags.

<perch:form id="contact" method="post" app="perch_forms">

</perch:form>
Documentation
Form tags: perch:label

perch:label creates a label element for the form. It requires a for attribute which contains the ID of the field that this label relates to.

<perch:label for="message">Message</perch:label> Documentation
Form tags: perch:input

perch:input is a self-closing tag which creates an input element in your form.

Perch enables you to use the HTML5 form input elements. Any user completing the form with a browser which supports these will get the additional validation and form input widgets in HTML5. These degrade to standard input elements in non-supporting browsers.

Documentation
Form tags: perch:error

You can have multiple perch:error tags for a perch:input field to cover different error states. For example one message to display in the case of a required field not being complete and a second error to display if the field is completed but the wrong format is used where you are validated email addresses for example.

Required validation:

<perch:error for="message" type="required">
  <span class="error">Please add a message.</span>
</perch:error>

Other examples:

<perch:error for="color" type="format">
  <span class="error">Please enter a valid colour.</span>
</perch:error>

<perch:error for="cv" type="filetype">
  <span class="error">File must be a PDF or Office document.</span>
</perch:error>

<perch:error for="cv" type="fileupload">
  <span class="error">Couldn't upload the file - could be too big.</span>
</perch:error>
Documentation
Form tags: perch:success

You can display a success message using the perch:success tag. Inside these tags can be any text, mark-up and also perch:content tags. So you can enable the administrator to update the success text.

This content will be shown when the form validates. It must be nested inside perch:form tags. If the success message is displayed then the rest of the form will not be displayed.

<perch:success>
  <perch:content id="thankyou" label="Success message" type="textarea" textile="true" editor="markitup" />
</perch:success>
Documentation
Using forms without any content

In most cases Perch Forms contain content perch:content tags and as such are used in the same way as any content on a Perch site.

If you have the Forms app installed you can also include forms without them needing to be added as content. You do this by placing a form template into perch/templates/forms then calling it on your page with the following function:

<?php perch_form('contact.html'); ?> Documentation
The Forms App

The Forms app works with the forms capability in Perch to give you an area where form options may be set and responses viewed. You require this app if you are using forms that will be processed by Perch. If you use forms that submit to external scripts then you do not need to install the Forms app.

Documentation