Category descriptions with the Perch blog app

Update: This is an outdated article. Don't try this with the latest version of Perch because the developers have now implemented category descriptions in their Categories app.

Update 2: Here's my updated post about Displaying blog category descriptions with Perch

The other day, I wanted to add a short category description to the blog post categories on CVW Web Design and display it above the blog posts for each category. For example, the description on this page that starts “Articles about Horsham and the coworking days…"

I'm using Perch to run the CVW site so this is an explanation of how I did this. It's essentially a write-up/summary of a post on the Perch forums where Martin Underhill asked about creating custom category text. Many thanks to Drew Maclellan from Perch for pointing me towards the best way to do this …. and to Martin for asking the original question.

Setting up new templates

Firstly, custom fields can be added to Perch blog categories by amending the categories.html template in /perch/templates/blog/. Here's my new categories.html template with an additional categoryDesc field for the category description.

<perch:blog id="categoryTitle" type="text" /> 
<perch:blog id="categorySlug" type="slug" for="categoryTitle" />
<perch:blog id="categoryDesc" type="textarea" label="Description" size="xs" html="false" editor="markitup" />

Upload the new categories.html template to your site, login to Perch and you should see the new description field on the edit category page. Of course, it's blank at this stage so enter a description for each of your blog post categories.

Now, we also need a template to display the category description field on the site. So, let's create one! In my case, it's called category_description.html. It goes in /perch/templates/blog/ like the category.html template.

Here's my category_description.html template.

<perch:if exists="categoryDesc">
<p><perch:blog id="categoryDesc" /></p>
</perch:if>

I've used a <perch:if> conditional, just in case any of the category descriptions are blank, and wrapped the category description in a paragraph tag.

Displaying the category description

Finally, let's use this template on our blog archive.php page after the category heading. I'm pretty much using the default Perch code on this archive page so my code is added to that.

Here's my additional code:

perch_blog_categories(array(
        'template' => 'category_description.html',
        'filter' => 'categorySlug',
        'match' => 'eq',
        'value' =>perch_get('cat'),
    ));

I'm filtering on perch_blog_categories so that the categorySlug field is matched to the query string cat value. i.e perch_get('cat'), and displaying this using my category_description.html template.

This additional code block is added after the categoryTitle heading on the archive.php page. Like this:

if (perch_get('cat')) {
       $mode = 'category';
       $categorySlug = perch_get('cat');
       $categoryTitle = perch_blog_category($categorySlug, true);
       echo '<h2>'.$categoryTitle.'</h2>';
       perch_blog_categories(array(
       'template' => 'category_description.html',
       'filter' => 'categorySlug',
       'match' => 'eq',
       'value' =>perch_get('cat'),
    ));

Note: There's a lot more of the original Perch archive.php code in the page and the code above only shows the bit that I've amended.

Wrapping up

OK, that's my short explanation for adding category descriptions to Perch blog. I hope it makes sense. You could also use this approach to add other category fields, for example, category images.

Anyway, I hope this post is useful. Let me know if you have questions.