Cheat Sheet

The basic tag is:

Content tags must have the required attributes:

• id
• type
• label

A basic tag would be:

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.

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.

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

• text
• textarea
• date
• select
• radio
• checkbox
• image
• file
• slug
• hidden
• map

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

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

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

Date formatted as Sun 04 July 10 using date options:

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

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"

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"

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.

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.

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

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.

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

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.

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

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

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.

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

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

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

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

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.

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

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.

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

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.

Templates live inside: /perch/templates/content

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

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.

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:

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.

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

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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: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.

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:

Other examples:

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.

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:

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.