Perch CMS Summit: Perch Template Tips and Tricks

Perch Template -ps & tricks
Rachel Andrew
The Perch Summit, 2015
Perch CMS Summit (Dec 2015)

What are Perch Templates?
• snippets of markup and Perch template tags
• some default templates can be found in perch/
templates/content
• you can create and add your own
• these can then be selected when deﬁning a Perch
Region

A Simple Template
This template contains a heading, date and main
content area.
<h2>
<perch:content id="heading" type="text" label="Heading" />
</h2>
<p class="date">
<perch:content id="date" type="date" label="Date" format="%d %B %Y" />
</p>
<perch:content id="body" type="textarea" label="Body" markdown="true" />

What makes Perch Templates
special?
• Perch templates deﬁne the output with any markup
combined with the content
• They also deﬁne the input
Perch templates become the edi9ng interface in
the Perch Control Panel

Making ﬁelds required
Set the required a,ribute on the Perch template tag.
<h2><perch:content id="heading" type="text"
label="Heading" required="true" /></h2>

Adding help
Help text can guide your users and ensure that they
maintain the tone of the site copy.
There are a few ways to add help to your templates.
• the help a)ribute on each ﬁeld
• the perch:help tag to add informa6on at the top
of the edit form
• the notes-before a)ribute to output help
before the ﬁeld

The help a&ribute
An a%ribute of help with a string to explain how this
ﬁeld should be used.
<h2>
<perch:content id="heading" type="text"
label="Heading" required="true"
help="Give the article a descriptive title." />
</h2>

The perch:help tag
A tag that can be used to add help at the top of the
form. This doesn't just need to be a string, it can
contain HTML.
• add a screenshot to guide the editor
• or even a short video!
<perch:help>
<p>Complete this form with your article.</p>
</perch:help>

The notes-before a&ribute
An a%ribute of notes-before on a ﬁeld will output
the value before the ﬁeld in the form.
<perch:content id="body" type="textarea"
label="Body" markdown="true"
notes-before="Keep these articles fairly short
- a couple of paragraphs just highlighting some
interesting information." />

Ordering ﬁelds in admin
The order a&ribute changes the order of ﬁelds in the
Perch Control Panel.
It does not change how the content displays on the
front-end of your site.

Ordering ﬁelds in admin
<perch:help>
<p>Complete this form with your article.</p>
</perch:help>
<h2>
label="Heading" required="true"
help="Give the article a descriptive title."
order="1" />
</h2>
<p class="date">
<perch:content id="date" type="date"
label="Date" format="%d %B %Y" order="3" />
</p>
notes-before="Keep these articles fairly short."
order="2" />

Adding a template divider
For longer forms, breaking up the content with a
divider can be helpful. There are two a;ributes - the
value is output inside the divider as a heading for that
sec=on.
• divider-before - outputs the divider before this
ﬁeld
• divider-after - outputs the divider a4er this
ﬁeld
<perch:content id="date" type="date" label="Date" format="%d %B %Y" order="3" divider-before="Meta data" />

Templates and Field Types
The type a&ribute in our form represents a Field
Type.
• type="text" creates a single line text input
• type="textarea" creates a mul1ple line textarea
field
• type="date" creates a three field date input
Some Field Types have extra a4ributes to change the
way the field is displayed or how the data is processed.

Included Field Types
In the docs: h,ps://docs.grabaperch.com/docs/templates/a,ributes/type/
• text
• textarea
• slug
• select
• radio
• map
• image
• hidden
• ﬁle
• date
• dataselect
• composite
• checkbox
• smar6ext

Adding your own Field Types
You can create and add your own Field Types to
Perch. It's a simple introduc:on to add-on
development.
You can take a look at some of our Field Types to see
how they work.
• Field Types API Docs
• Vimeo Field Type

Text entry op+ons
• text
• smar)ext
• textarea

type="smarttext"
A replacement for type="text" adds nicer typography:
• Straight quotes " and ' are turn into “curly” quotes
• Dashes -- and --- are turned into en- and em-dashes
• Three consecu<ve dots ... are turned into an ellipsis
Uses Unicode characters. If you are not serving pages as
UTF-8 you can choose to use HTML en==es by se?ng in
conﬁg:
define('PERCH_HTML_ENTITIES', true);

type="textarea"
Comes with a whole ra. of a0ributes to conﬁgure edi8ng:
• size
• count
• html
• tex/le
• markdown
• editor

I have added a size="m" and count="words" to
my textarea.
order="2" size="m" count="words" />

Adding an editor
Adding editor="markitup" adds the MarkItUp
editor that ships with Perch.
label="Body" markdown="true" editor="markitup"
order="2" size="m" count="words" />

Uploading resources from editors
Addi$onal a*ributes to manage resources uploaded inline:
• bucket
• imagewidth
• imageheight
• imagecrop
• imageclasses
• imagequality
• imagedensity
• imagesharpen

The imageclasses a,ribute
<perch:content id="body" type="textarea" label="Body" markdown="true"
editor="markitup" notes-before="Keep these articles fairly short."
order="2" size="m" count="words"
imagewidth="640" imageheight="480" imageclasses="left,right" />

Re-using content in the same
template
The id a&ribute in your template iden3ﬁes that piece
of content.
Unlike in HTML, you can reuse an ID in your template.
When you reuse an ID, the content editor sees that
ﬁeld once but the content is output as many 8mes as
you use the ID.

Reusing an ID in a template
To add an email address with a mailto link and the
email printed on the page we need to repeat the
email address.
<a href="mailto:example@example.com">
example@example.com
</a>

Reusing an ID in a template
Repeat the ID in the template. Content entered once
is then used twice.
<a href="mailto:<perch:content id="email"
type="text" label="Email" required="true" />">
<perch:content id="email" type="text"
label="Email" required="true" /></a>

Crea%ng excerpts
Excerpts are created by limi1ng the display to a number of words
or characters, using the chars or words a:ributes.
Words
label="Heading" required="true" order="1"
words="20" />
Chars
chars="20" />

Appending to show the content has
been shortened
Whatever you add as the value of the append
a2ribute will be output a6er the shortened content.
words="20" append="..." />

Looping structures in Perch
We have two ways to repeat the same template in
Perch:
• a Region set to "allow mul1ple items"
• Repeaters

Mul$ple Item Regions
Regions are set to allow mul0ple items in the Perch
Control Panel.
Set this when crea-ng the Region or by going to
Region Op-ons and selec-ng 'Allow Mul-ple Items'.

Edit 'all on one page', or not?

The title a&ribute
<h3 class="fn n">
<span class="given-name">
<perch:content id="givenname" type="text"
label="Given name" required="true" title="true" />
</span>
<span class="family-name">
<perch:content id="familyname" type="text"
label="Family name" required="true" title="true" />
</span>
</h3>

Adding mark-up before and a2er the
repea5ng sec5on
The perch:before and perch:after condi+onal tags are output before and a5er the looping sec+on.
The markup inside these tags will only display if there is at least one entry.
<perch:before>
<ul>
</perch:before>
<li>
<h3 class="fn n">
<span class="given-name">
<perch:content id="givenname" type="text"
label="Given name" required="true" title="true" />
</span>
<span class="family-name">
<perch:content id="familyname" type="text"
label="Family name" required="true" title="true" />
</span>
</h3>
</li>
<perch:after>
</ul>
</perch:after>

Repeaters
<perch:repeater id="links" label="Links" max="5">
<perch:before>
<ul class="links">
</perch:before>
<li><a href="<perch:content id="url" type="text" label="URL" />">
<perch:content id="linktext" type="text" label="Link Text" /></a>
</li>
<perch:after>
</ul>
</perch:after>
</perch:repeater>

Repeater A)ributes
A repeater has:
• a unique ID in the template
• a label which is output in the Control Panel
• an op8onal limit for the number of items that can
be added
<perch:repeater id="links" label="Links" max="5">
</perch:repeater>

Should I use a Mul-ple Item Region
or perch:repeater?
• Repeaters work best for small amounts of content: table rows,
list items, images.
• Mul:ple Item Regions should be used for larger templates so
you can beneﬁt from list/detail view.
• Mul:ple Item Regions can be ﬁltered, sorted and other
manipulated through perch_content_custom.
• Mul:ple Item Regions can also be easily converted into a
Collec:on when upgrading to Runway. Perfect if your site
grows.

Blocks
Blocks also allow the addi/on of mul/ple chunks of
data in one region.
This powerful feature means you can give your
content editor a choice of templates in a single region.
Blocks templates can contain repeaters and can also
be part of a Mul5ple Item Region.

Crea%ng a Blocks template
Wrap the whole template in <perch:blocks></
perch:blocks> tags.
Wrap each sub-template in <perch:block></perch:block>
tags.
Inside the <perch:block></perch:block> tags is your
template as normal, for that Block.
<perch:block> needs two a*ributes:
• type: an ID for the Block
• label: shows up in admin, a human readable label for the Block

A simple Blocks template
<perch:blocks>
<perch:block type="text" label="Text">
<div class="fullwidth">
label="Body" markdown="true" editor="markitup"
required="true" />
</div>
</perch:block>
<perch:block type="quote" label="Pull quote">
<blockquote>
editor="markitup" required="true" />
<p><perch:content id="name" type="text"
label="Name" required="true" title="true" /></p>
</blockquote>
</perch:block>
<perch:block type="image" label="Feature image">
<img class="feature" src="<perch:content
type="image" id="image" label="Image" />"
alt="<perch:content type="text" id="alt"
label="Description" required="true"
help="e.g. Photo of MD John Smith with his best wig on" title="true" />" />
</perch:block>
</perch:blocks>

Template Includes
<perch:blocks>
<perch:block type="3col" label="Three columns">
<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>
</perch:block>
<perch:block type="image text" label="Image and Text">
<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>
</perch:block>
</perch:blocks>

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

Condi&onals
• perch:before
• perch:after
• perch:if
• perch:else
• perch:every

perch:if
Test to see if something exists, matches or contains a
value before doing something.

If exists
Useful to check whether a ﬁeld has been completed
before outpu6ng markup around it.
<perch:if exists="heading">
<h2>
<perch:content id="heading" type="text" label="Heading" />
</h2>
</perch:if>

If not-exists
The reverse of exists, do something if the ﬁeld has not
been completed.
<perch:if not-exists="resources">
<p>No resources have been uploaded yet!</p>
</perch:if>

Checking to see if things match
To check if things match you need the following
a5ributes:
• id: the id of the content
• value: a string to compare against the content
• match: the type of comparison to do, if you omit this
a8ribute Perch defaults to eq - equals.
<perch:content type="text" id="say" label="What do you want to say?" />
<perch:if id="say" value="hello" match="eq" case="insensitive">
<p>Today we are saying hello.</p>
</perch:if>

Values for match
• eq: equal to
• neq: not equal to
• gt: greater than
• gte: greater than or equal to
• lt: less than
• lte: less than or equal to
• contains: the value exists within the content (a simple search)
• regex: using a PCRE regular expression
• between: match between two values
• eqbetween: match between two values inclusively
• in: match within a comma delimited content list (like a list of tags)

match="contains"
The following would match whether the content editor
entered:
• hello
• hello, world
• I am saying hello
• I am saying hello to Bob
<perch:content type="text" id="say" label="What do you want to say?" />
<perch:if id="say" value="hello" match="contains" case="insensitive">
<p>Today we are saying hello.</p>
</perch:if>

Showing part of a template based on
a checkbox value
Add a checkbox to your template.
It will only have a value if it is checked.
Use exists to see if it is checked then output the content.
Adding suppress="true" means the 1 will not show
on your site.
<perch:content type="checkbox" id="sale" value="1" label="Sale in progress" suppress="true" />
<perch:if exists="sale">
<div class="promo">Sale now on!</div>
</perch:if>

Checking mul-ple values
You can test for mul/ple values when using exists
using the keywords:
• AND
• OR
• XOR
You can also ﬂip the value with the ! operator.
<perch:if exists="is_live AND is_free"><a href="/link-to-content"></perch:if>

Using if different in a loop
We can use different to add headings or other
markup when something different happens to a field
in our loop.
I have added a template tag for department to my
employee lis4ng template (CSS inline for demo)
<perch:if different="department">
<h2 style="clear:left; padding-top: 2em;">
<perch:content id="department" type="select" label="Department"
options="Directors,Tea Makers,Web developers" /></h2>
</perch:if>

To use different order your region
by that field
In the Region Op-ons change the Sort By field under
Display to the field you are checking for 'different'.
Perch different checks to see if the current value of
that field is different to the last 5me we went through
the loop.

When using different make sure
editors enter what you expect
Using a select ﬁeld type means you can pre-populate
the list of op7ons.
<perch:if different="department">
<h2 style="clear:left; padding-top: 2em;">
<perch:content id="department" type="select" label="Department"
options="Directors,Tea Makers,Web developers" /></h2>
</perch:if>

perch:else
You can use perch:else in combina-on with
perch:if to do one thing if the if matches and
another if not.
This can be useful if you want to output diﬀerent
mark-up depending on the content entered.
<perch:if exists="heading">
<h2><perch:content id="heading" type="text" label="Section heading" /></h2>
<div class="intro">
<perch:else />
<div>
</perch:if>
<perch:content id="content" type="textarea" label="Content" />
</div>

Something Drew forgot to document
You can also do this:
<perch:content id="text" else="-" />
Which is the same as:
<perch:if exists="text">
<perch:content id="text" />
<perch:else />
-
</perch:if>
(We will add it to the docs!)

perch:every
Allows you to do something every n number of 5mes
through the loop.
Takes a value of a simple count OR CSS nth-child
values.

perch:every
<perch:every count="2">
<tr class="even">
</perch:every>
<perch:every nth-child="even">
<tr class="even">
</perch:every>
<perch:every nth-child="2n+1">
<tr class="odd">
</perch:every>
h"p://nth-test.com/

Use every to wrap groups of
elements in markup
<perch:every count="3">
</div>
<div class="row">
</perch:every>

String replacement
You can do simple string replacement with the replace
a4ribute.
The value before the pipe character is what you are
looking for, replace it with the value a8er the pipe.
<perch:content type="text" id="aperture"
label="Lens aperture" replace="f|ƒ" />

Use replace to keep links correct
A nice use of this is to remove h0p:// or h0ps:// from
links entered in the CMS - so you can add that in the
markup making sure links work.
Mul$ple replacements are separated by a comma.
<a href="http://<perch:content id="url" type="text"
label="Your website" replace="http://|,https://|" />">

The composite field type
This allows you to turn two individual fields into a
single field. Perhaps in order to filter on them as one
thing.
<perch:content id="firstname" type="text"
label="First name" />
<perch:content id="lastname" type="text"
label="Last name" />
<perch:content id="fullname" type="composite"
for="last name first name" join=", " />

Adding template comments
Perch template comments look a bit like HTML
comments but they have an addi:onal * character.

Passing a variable into a template
This only works for templates that are parsed at run5me -
so when using perch_content_custom.
I am se'ng a variable called 'lang'. I then display my region
using perch_content_custom passing in a template.
<?php
PerchSystem::set_var('lang', 'en');
perch_content_custom('My region', array(
'template'=>'template.html'
));
?>

Using a variable in a template
If I have set a variable using set_var I can then use it
like any other Perch template tag.
In this case I am using the en in the URL of a link, as I
might do in a branched mul9lingual site.
<a href="/<perch:content id="lang" />/contact/">Contact Us</a>

Including a layout in a template
You can include one of your layout fragments directly
in a template.
In your template use the tag perch:layout with a
path a3ribute with the layout (rela6ve to the perch/
layouts folder).
<perch:layout path="global.sidebar" />

Using content with a different
template
A"er you have added content, you can display it elsewhere on the site using an
alternate template.
When using perch_content_custom pass in your alternate template.
Use the same field IDs as the main template. You don't need to include all fields
and can format them differently.
<?php
perch_content_custom('News', array(
'page'=>'/news/index.php',
'template'=>'article-excerpt.html'
));
?>

"Master" templates
When working with mul0ple templates, the main
template for the Region or Collec0on item should be
seen as the Master Template.
This is the template where all ﬁelds are deﬁned - even
if they are not displayed in the main output.

Hiding content fields from the output
Any fields that are not used in your main template
should have an a4ribute of suppress="true".
Your alternate templates only need to include the
fields that they use.

Perch templates in First-Party Apps
The same template language applies through all Perch
Apps.
Where templates for regular Perch Content and
Collec5ons are namespace perch:content app
templates are namespaced with the name of the app,
e.g.: perch:blog or perch:shop.
Apps ship with default templates, to create your own
or modify ours copy them into perch/templates/
app_name.

All Apps have a Master Template
Apps use the concept of a Master Template - the
place where all fields for content entry are defined.
This will generally be the main item that the app
creates - for example in Blog the Master template is
post.html.
The same rules apply as for content templates, add all
of the fields you need to the Master template then
suppress those you do not want to show.

Reusing your content templates in
Apps
As App templates are namespaced you can't directly
use a content template in an App.
You can include content templates with template
includes.
When crea)ng your include use rescope="parent"
<perch:template path="content/another_template.html" rescope="parent" />

Template star+ng points
If you use a framework, create templates for the
diﬀerent pa8erns in that framework. You can then
start out with a set of built templates and tweak for
the individual site.
Even if you don't tend to use a framework you can
iden5fy common pa7erns and create reusable
templates as assets for your business.

Some templates we have created
• Bootstrap: h,ps://github.com/PerchCMS/perch-
bootstrap-templates
• Founda?on: h,ps://github.com/PerchCMS/perch-
founda?on-templates
• Material Lite: h,ps://github.com/PerchCMS/
material-lite-templates
Submit a Pull Request if you would like to add to
these!

How to debug template problems
The Perch Debug mode will show you which template is
being used to display content, when using dynamic content.
Add this line to your Perch Conﬁg ﬁle:
define('PERCH_DEBUG', true);
If you are using Runway this is all you need to do. If using
Perch add the following to each page (ideally in a bo:om
include).
<?php PerchUtil::output_debug(); ?>

See which ﬁelds are available in your
template
Add <perch:showall /> to any template to see a
lis/ng of the available ﬁelds.
Remember to remove it a,er development!

Thank you!
@rachelandrew
grabaperch.com

Perch CMS Summit: Perch Template Tips and Tricks

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Perch CMS Summit: Perch Template Tips and Tricks

Similar to Perch CMS Summit: Perch Template Tips and Tricks (20)

More from Rachel Andrew

More from Rachel Andrew (20)

Recently uploaded

Recently uploaded (20)

Perch CMS Summit: Perch Template Tips and Tricks