Building a Full Featured Blog with Perch

08 December 2016 by Chad Tiffin

I’m a pretty strong Perch supporter, having used it to build almost 20 websites now. I’ve used the 1st party Blog add-on to create a blog for several of those sites, but the blogging needs of those website owners were very basic with no need for categories or commenting, so I haven’t truly flexed the muscle of the Perch Blog system to it’s full extent.

I’ve been intending to add a blog to my own website for quite some time now, and first tinkered with Wordpress set up on a subdomain, but since my own website is already powered by Perch, I wasn’t happy with the split-personality of running both Perch & Wordpress on the same website, so after a few weeks of the Wordpress blog languishing in a half-finished state I took the plunge into the Perch Blog.

I thought I’d share my process.

Installing

Installing the blog was extremely straightforward, the steps basically consisting of downloading the files from the Perch website, dumping them into the “/perch/addons/apps” folder, and then adding the “perch_blog” to the “/perch/config/apps.php” file.

Setting up the Blog Pages

Usually when I do simple single-category blogs, I only have 2 pages, a main blog listing page, that shows recent blog posts, and then a “Post” page, that shows a single blog post. Then for navigating the archive I set up a sidebar with posts listed sequentially in descending order, sorted by year into collapsible accordion boxes for easy navigation.

For a blog with multiple categories, we need a way to filter posts by category, so I would also need an “Archive” page as well, to show a listed of posts sorted by category.

All 3 of these pages would have the same basic layout, which would match my existing site, so I created 3 layout files:

blog_header.php: To add the HTML head, nav-bar (another included file from my main site layout), and this also includes the “blog_aside.php”
blog_footer.php: Basically just some closing tags and an include of my main site footer
blog_aside.php: This is my sidebar, more on this in a bit

Then I created a “/blog” subdirectory, and created 3 more files that would be my 3 blog pages:

Main blog page (index.php)

index.php

< ?php
include("blog_header.php");

echo "<h1>Recent Blog Posts</h1>";
perch_blog_recent_posts(5);

echo "<h3>Explore Some More Categories</h3>";
perch_blog_categories(); //list my categories at the bottom of the post feed to encourage users to explore more posts

include("blog_footer.php")

Notice the perch functions in there for listing recent blog posts, and displaying a list of categories. Perch will then spit out an un-styled list of blog posts/categories, according to the template that you’ve defined in the blog templates directory.

It comes with default templates by I had to modify mine to suit my purposes:

post_in_list.html – to display posts in a list (too obvious?)

<perch:before>
  <ul class="hfeed listing">
</perch:before>
    <li class="hentry">
         <perch:if exists="image"><img src="<perch:blog id="image" type="image" width="65" height="65" crop="true" />" alt="<perch:blog id="postTitle" />" /></perch:if>
        <h2><a href="<perch:blog id="postURL" />" rel="bookmark" class="entry-title"><perch:blog id="postTitle" /></a></h2>

        <p class="entry-published date"><perch:blog id="postDateTime" format="%d %B %Y" /></p>
        <div class="description entry-summary">
        <perch:blog id="excerpt" type="textarea" textile="true" />
        <perch:if id="postCommentCount" value="0" match="neq" />
            <p>Comments: <perch:blog id="postCommentCount"/></p>
        </perch:if>
        </div>
    </li>
<perch:after>
  </ul>
</perch:after>

Blog Post page (post.php)

The next page to set up is the post.php page, for showing a single blog post and the comments:

<?php
include("blog_header.php");

perch_blog_post(perch_get('s')); //get the actual blog post template, based on a url variable containing the post slug
perch_blog_author_for_post(perch_get('s')); //get the author template

perch_blog_post_comments(perch_get('s')); //get the comments template

perch_blog_post_comment_form(perch_get('s')); //get the comment form template

include("blog_footer.php");

In similar fashion to the perch functions on the main blog page, these functions (perch_blog_post, perch_blog_author_for_post, etc) all pull in a template file that defines the structure of the html for each of these blocks.

All these template files pre-made as a default, but you can modify them any way you like, which I did to all of them to suit my purposes, once you’re familiar with how perch works, its fairly straightforward. Perch has really good documentation on how to work with their templating system, but I found their documentation regarding how the internals of the blog work a little lacking. That said considering its basically only two of them doing everything (developing two different versions of Perch, manning the support forum, and developing Add-ons) I’m willing to cut them some slack on some sparse docs here and there.

Categories & Archive Page (archive.php)

Perch Categories is an extension to Perch that automatically ships with the core, so setting up my categories was as simple as going into the Perch Admin and adding the ones I wanted. They come already tied into the default “post.html” template, so it all mostly just worked as is, save for editing some of the templates that list out my categories to display it how I wanted.

Perch ships a pretty comprehensive example of an archive page, but for my archive all I need is to sort posts by category and display a list, so I just pulled that bit out of the example archive page and added my header and footer templates.

In short, the code below gets the blog category from the url, sets the template, and what field to sort by (the date), then fetches those posts.


<?php
include("blog_header.php");

// defaults for all modes
$posts_per_page = 10;
$template       = 'post_in_list.html';
$sort_order     = 'DESC';
$sort_by        = 'postDateTime';

// Have we displayed any posts yet?
$posts_displayed = false;

$cat = getURLSegment($_SERVER['REQUEST_URI'],"last"); //this splits the url into segments by "/", and then gets the last segment, which is the category

/* --------------------------- POSTS BY CATEGORY --------------------------- */
if ($cat) {

    echo "<h1>".perch_blog_category($cat,true)."</h1>";

    perch_blog_custom(array(
            'category'   => $cat,
            'template'   => $template,
            'count'      => $posts_per_page,
            'sort'       => $sort_by,
            'sort-order' => $sort_order,
            ));

    $posts_displayed = true;
}

    /* --------------------------- NO POSTS --------------------------- */

    if ($posts_displayed == false) {

    echo "<p>No posts found in this category.</p>";

    }

echo "<h3>Explore Some More Categories</h3>";
perch_blog_categories(); 

include("blog_footer.php");

Blog Aside (blog_aside.php)

The blog_aside.php file just gets included inside the blog_header.php file, and is pretty basic, just having a perch content region to let me manage some basic text and a title about what my blog is all about, and then a function to pull in a list of the category links:

<aside class="blog">
    <div class="inner">
        <?php perch_content("Blog Aside"); ?>

        <div class="categories">
            <h3>Categories</h3>
            <?php perch_blog_categories(); ?>
        </div>
    </div>
</aside>

URL Rewriting

Perch by default doesn’t do any URL rewriting, so by default page URLS have the file extensions and ugly url variables (ex. www.chadtiffin.com/blog/post.php?s=my-blog-post). For readability purposes (and a bit of an SEO advantage, I wanted my page urls to look more like this: “www.chadtiffin.com/blog/posts/my-blog-post”

We can change all of that with mod_rewrite in Apache’s htaccess file. We need two rules, one for matching the pretty post url to its “natural” url, and one to match the url that filters posts by category to the “natural” archive page:

<IfModule mod_rewrite.c>
RewriteEngine on

#blog post rewrite
RewriteRule ^blog/posts/([a-zA-Z0-9-/]+)$ blog/post.php?s=$1

#blog category archive rewrite
RewriteRule ^blog/([a-zA-Z0-9-/]+)$ blog/archive.php?s=$1

</IfModule>

Now that the url formats are different, I need to go back through my Perch template files and make sure any <a> tags are pointing to the properly formatting URLS now instead of the default “natural” ones.

For example, my category_link.html template, which is used to print out a list of categories, and their links to the filtered archive page needed to be changed from this:

<perch:before>
    <ul>
</perch:before>
    <li><a href="/blog/archive.php?s=<perch:category id="catSlug" />"><perch:category id="catTitle" /> (<perch:category id="count.blog.post" when-empty="0" />)</a></li>
<perch:after>
    </ul>
</perch:after>

to this (note the href difference):

<perch:before>
    <ul>
</perch:before>
    <li><a href="/blog/<perch:category id="catSlug" />"><perch:category id="catTitle" /> (<perch:category id="count.blog.post" when-empty="0" />)</a></li>
<perch:after>
    </ul>
</perch:after>

Perch Blog Settings

The last thing to do to get the whole thing working was in the Perch Admin settings, there is an option to define what the blog post page path is. This tells Perch what the proper urls for the blog posts are, so I needed to change this to the new URL format as well.

Perch blog settings

Styling

After that, all that’s left is to do some CSS styling. Perch doesn’t force styling on us, so we’re free to make the site look however we want.

Done!

Categories: General, Web Development,