Getting to Know Perch CMS

Getting to Know Perch
(and Perch Runway!)
Abby Larsen
PDX CMS, June 2015

Abby Larsen
@abberdab, @happyfanfare 
http://www.abbylarsen.com

CMS Content Pain Points
FOR ME, WEB DESIGNER / FRONT-END DEVELOPER
• Opinionated content structure
• Programmatically inserted markup
• WYSIWYG tag soup!
• Programming required for custom content, customized admin
• Unnecessary overhead and complexity for simple content

CMS Content Pain Points
FOR MY CLIENTS, SITE OWNERS AND CONTENT EDITORS
• Scattered admin interfaces
• Superﬂuous, confusing admin options
• Expensive development time for anything custom
• Lengthy documentation
• Slow load times

Perch
http://www.grabaperch.com
• All content is custom — markup and content structure agnostic
• Use it a little or a lot, can exist alongside other frameworks
• Alternatives to WYSIWYG for rich text
• Tag-based template language, no programming required
• Admin interface mirrors content structure
• Reduced training/documentation time

Technical Requirements
• PHP 5.3 or newer with:
- PDO or mysqli, JSON libraries, GD or ImageMagick
• MySQL 5.0 or newer
• Linux recommended, but other platforms supported

Installation
1. Download Perch
2. Have database information in hand
3. Place the perch directory into the root of your web directory
4. Visit http://www.yourdomain.com/perch/setup in a web browser
5. Submit your license, personal, and database information
6. Log into your new Perch Dashboard!

Getting Started
Our dashboard is empty because Perch isn’t managing any pages, yet.  
To manage a page’s content, we need to:
• Add the Perch runtime statement
• Add a Perch editable region

Perch Runtime Statement
Add the perch runtime statement to the top of your page markup, above the  
<!doctype>. If your page exists in a subdirectory, change the path accordingly.
<?php include('perch/runtime.php');?>
<!doctype>
<html lang="en">
<head>
<title>Our Cats</title>
</head>

Perch Editable Regions
To start managing content on a page, add a Perch page function to that page.
This page function is a Perch editable region. It looks like this:
<section class="slide reverse">
<div class="hero">
<h1>Our Cats</h1>
<h2>by Harrison Weir</h2>
</div>
</section>

Perch Editable Regions
To start managing content on a page, add a Perch page function to that page.
This page function is a Perch editable region. It looks like this:
<section class="slide reverse">
<div class="hero">
<h1><?php perch_content('Heading'); ?></h1>
<h2>by Harrison Weir</h2>
</div>
</section>

Perch Templates
Perch templates contain a mix of markup and Perch template tags. Perch
templates deﬁne and format editable region content:
• Admin interface
• Data schema
• Markup

Default Templates
By default, Perch comes with the following content templates. These are just the
starting point!
• Text
• File
• Image
• Code Block
• Text Block
• Google Analytics
• Map
• Article

A Simple Perch Template
The default Text template contains a single Perch template tag of type="text",
and no markup. A Text template controls the “Our Cats” Heading region.
<perch:content id="text" label="Text" type="text"
required="true" title="true" />

Anatomy of a Perch Template Tag
A Perch template tag opens with perch:content and requires id, label, and
type attributes.
<perch:content id="text" label="Text" type="text"
required="true" title="true" />

A more complex, but
typical, Template
This is a portion of the
default Article template.
It contains a mix of
Perch template tags and
markup.
<h2><perch:content id="heading" type="text"
label="Heading" required="true" title="true" /></h2>
<p class="date"><perch:content id="date" type="date"
label="Date" format="%d %B %Y" required="true" /></
p>
<perch:content id="body" type="textarea"
label="Body" markdown="true" editor="markitup"
required="true" />
<p class="vcard">
© <perch:content id="date" type="date"
label="Date" format="Y" />
<span class="fn n">
<perch:content id="author_given_name"
type="text" label="Author given name" />
<perch:content id="author_family_name"
type="text" label="Author family name" />
</span>
</p>

An “Opinion” Region
Our “Opinion” region
will contain a mix of
content and markup,
courtesy of the Article
template.
<!doctype html>
<html lang="en">
<head>
</head>
<body>
…
<section class="opinion">
<h1>Opinion</h1>
<h2>Regarding the National Cat Club</h2>
<p class="date">15 June 2015</p>
<p>In my former edition of “Our Cats,” I wrote
hopefully and expectantly of much good to be derived
from the institution of the so-called National Cat
Club…</p>
<p class="vcard">© 2015 <span class="fn
n">Harrison Weir, F.H.S.</span></p>
</section>

An “Opinion” Region
Our “Opinion” region
will contain a mix of
content and markup,
courtesy of the Article
template.
<!doctype html>
<html lang="en">
<head>
</head>
<body>
…
<section class="opinion">
<h1>Opinion</h1>
<?php perch_region('Opinion'); ?>
</section>

<!doctype>
<html lang="en">
<head>
</head>
label="Heading" required="true" title="true" /></h2>
<p class="date"><perch:content id="date" type="date"
label="Date" format="%d %B %Y" required="true" /></
p>
label="Body" markdown="true" editor="markitup"
required="true" />
<p class="vcard">
© <perch:content id="date" type="date"
label="Date" format="Y" />
<span class="fn n">
<perch:content id="author_given_name"
type="text" label="Author given name" />
<perch:content id="author_family_name"
type="text" label="Author family name" />
</span>
</p>

Perch Tag Types
By default, Perch comes with the following tag types.
• text
• smarttext
• textarea
• date
• select
• radio
• checkbox
• image
• ﬁle
• slug
• hidden
• map
• composite
• dataselect

Perch Region Options
Region options are controlled through the Perch Dashboard.
• Multiple Item Regions
• Shared Regions

Multiple Item Regions
Allows your editors to add multiple items, simple or complex, to a region.
EDITING OPTIONS
• All on one page (best for simple items)
• List /detail mode (best for complex items)
DISPLAY OPTIONS
• Customize sort order
• Control number of items displayed

Title Text
Allow multiple items in a region.

Shared Regions
Shared regions allow you to edit content for multiple pages in a single place.

Shared Regions
Shared regions are useful for footer text, contact information, or other global
content.
<footer>
<p>
Read the complete <em>Our Cats and All About Them</em>
at <a href="http://www.gutenberg.org/">Project Gutenberg</a>.
</p>
</footer>

Shared Regions
Shared regions are useful for footer text, contact information, or other global
content.
<footer>
<?php perch_region('Footer');>
</footer>

Template Options
Useful options for your template code.
• Repeaters
• Blocks

Repeaters
When you don’t know how many of something you need to manage in a content
item, when editors need the option to add lots or none at all, use a repeater!
• Images
• Documents
• Related links
• Versions of a downloadable thing
• ?

Anatomy of a Repeater
A Perch repeater tag opens with perch:repeater. It requires an id and a label
attribute. An optional max attribute puts a cap on the number of somethings.
<ul>
<perch:repeater id="links" label="Related Links" max="10">
<li><a href="<perch:content id="url" type="text"
label="URL" />"><perch:content type="text" id="desc" label="Link
Text" /></a></li>
</perch:repeater>
</ul>

A job for Perch conditional tags!

Perch Conditional
Tags, in Brief
<perch:before> and
<perch:after> contain
the parts of our
template that should
only display if items
have been added to the
repeater.
<perch:repeater id="links" label="Related Links"
max="10">
<perch:before>
<div class="related-links">
<h3>Related Links</h3>
<ul>
</perch:before>
<li><a href="<perch:content id="url"
type="text" label="URL" />"><perch:content
type="text" id="desc" label="Link Text" /></a></li>
<perch:after>
</ul>
</div>
</perch:after>
</perch:repeater>

Blocks
Perch Blocks in your content template code give content editors a choice of
multiple content formatting options. Each Block is like a micro-template inside
of your content template.
• Can feature custom markup for diﬀerent content or layout scenarios
• Can contain repeaters and conditionals

Blocks
Blocks exist within a
<perch:blocks> tag
pair. Template tags and
markup for each block
exist within a
<perch:block> tag pair.
<perch:block> tags
require type and label
attributes.
<perch:blocks>
<perch:block type="text" label="Text">
…
</perch:block>
<perch:block type="quote" label="Quote">
…
</perch:block>
<perch:block type="image" label=“Big image">
…
</perch:block>
<perch:block type="image" label=“Inline
image">
…
</perch:block>
</perch:blocks>

Blocks <perch:blocks>
…
</perch:block>
<perch:block type="quote" label="Quote">
…
</perch:block>
<perch:block type="image" label=“Big image">
…
</perch:block>
<perch:block type="image" label=“Inline
image">
…
</perch:block>
</perch:blocks>
Blocks exist within a
<perch:blocks> tag
pair. Template tags and
markup for each block
exist within a
<perch:block> tag pair.
<perch:block> tags
require type and label
attributes.

Example:  
Photo Essay
Template with Blocks
<div class="photo-essay">
<header
style="background:url('<perch:content
id="heading_image" type="image" width="1600"
label="Heading Image" />') center center no-
repeat; background-size:cover;">
label="Heading" required="true" title="true" /
></h1>
</header>
<perch:blocks>
…
</perch:blocks>
</div>
A custom template with
blocks for text, pull
quotes, big images, and
inline images.

Example:  
Photo Essay
Template with Blocks
<perch:content id="text" type="textarea" markdown="true"
editor="markitup" size="s" label="Text" />
</perch:block>
<perch:block type="pullquote" label="Pull quote">
<blockquote>
<perch:content id="quote" type="textarea" markdown="true"
size="xs" label="Quote" />
<cite>— <perch:content id="cite" type="smarttext"
label="By" /></cite>
</blockquote>
</perch:block>
<perch:block type="image" label="Big image">
<figure class="hero">
<img src="<perch:content id="image" type="image" width="1600"
label="Image" />" class="img-responsive" />
<figcaption><perch:content id="caption" type="smarttext"
label="Caption" /></figcaption>
</figure>
</perch:block>
<perch:block type="inlineimage" label="Inline image">
<figure class="inline <perch:content id="class" type="select"
options="Pull left|pull-left,Pull right|pull-right" label="Alignment"
order="2" />">
<img src="<perch:content id="image" type="image" width="360"
density="2" label="Image" order="1" />" class="img-responsive" />
</figure>
</perch:block>
A custom template with
blocks for text, pull
quotes, big images, and
inline images.

Perch Demo
Photo Essay with Blocks
ADMIN · DISPLAY

List / Detail Pages
Creating this common website pattern in Perch requires the following:
• A detail view content template that includes a slug ﬁeld
• A list view content template
• A multiple item content region
• The <?php perch_content_custom(); ?> function in your page

Detail template
This is the master
template. It controls the
admin and the individual
news item view.
The existing article
template is included
with <perch:template>.
<perch:template path="content/article.html" />
<perch:content id="slug" for="heading"
type="slug" suppress="true" />

Detail template
The slug ﬁeld type
makes a URL-friendly
version of our news title
for linking.
The suppress="true"
attribute hides this ﬁeld
from the admin.
<perch:template path="content/article.html" />
<perch:content id="slug" for="heading"
type="slug" suppress="true" />

List template
The list template
references content ids
deﬁned in the detail
template and contains
the markup for our list
view.
<h2>
<a href="?s=<perch:content id="slug"
type="slug" />">
<perch:content id="heading"
type="text" />
</a>
</h2>
words="20" append="..." />
<p>
<a href="?s=<perch:content id="slug"
type="slug" />">
Read More »
</a>
</p>

Initialize a  
multi-item region
Back in our page, we’ll
create our region
programmatically, using
perch_content_create.
This takes care of our
region initialization and
settings in one go.
<?php
perch_content_create('News', array(
'template' => 'custom/detail.html',
'multiple' => true,
'edit-mode' => 'listdetail',
));
?>

List/detail code
Also in our page, we use
the Perch helper
function perch_get()
to check for and get the
slug from the URL.
<?php
if (perch_get('s')) {
perch_content_custom('News', array(
'filter' => 'slug',
'match' => 'eq',
'value' => perch_get('s'),
'count' => 1,
'paginate'=>true
));
} else {
'template' => 'custom/list.html'
));
}
?>

List/detail code
If a slug exists,
perch_content_custom
displays a slug match
with our detail template.
Otherwise, it displays all
items with the list
template.
<?php
if (perch_get('s')) {
'filter' => 'slug',
'match' => 'eq',
'value' => perch_get('s'),
'count' => 1,
'paginate'=>true
));
} else {
'template' => 'custom/list.html'
));
}
?>

Limitations of Perch
If your site is very content-heavy, you might find Perch an awkward fit for the
following reasons:
• Every page requires a corresponding file on the server
• Multi-item regions are versioned at the region level
• All content must be associated with a specific page

Perch Runway
• Pages no longer need to be a ﬁle on the server
• Collections
- Content is no longer tied to a page
- Content can be edited anywhere that makes sense
- Items are individually versioned
- Collections can have relationships to other Collections

Perch Runway
Runway features enterprise-y stuﬀ that might be overkill for smaller sites.
• Multiple page routes
• Task scheduling
• CDN delivery
• Cloud Storage
• Backup to the Cloud or Dropbox
• Varnish support

Collections
Collections are not tied to any page, instead they are managed via the
Collections menu.

Collections
While not tied to a page, Collections can be associated with any (or all!) pages
that would make sense to your content editors.

Relationships
Collections can have relationships to other Collections.
Related Collection content can then be displayed alongside the content for a
diﬀerent Collection.

Relationships
The <perch:related>
tag in your content
template enables you to
create relationships
between Collections,
then display that related
content.
<perch:related id="author" collection="Authors"
label="Author">
<perch:before>
<h3>Authored by</h3>
<ul>
</perch:before>
<li><a href="/authors/<perch:content
id="slug" type="slug" />"><perch:content
id="author_first_name" type="text" />
<perch:content id="author_last_name" type="text"
/></a></li>
<perch:after>
</ul>
</perch:after>
</perch:related>

Getting to Know Perch CMS

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to Getting to Know Perch CMS

Similar to Getting to Know Perch CMS (20)

Recently uploaded

Recently uploaded (20)

Getting to Know Perch CMS