Displaying blog category descriptions with Perch

I described how to create and display category descriptions with the Perch blog add-on earlier this year. Now, that article is no longer accurate because Perch have created a Categories app as part of the core functionality.

So, here's an update which describes how to display blog category descriptions using the latest version of Perch (2.6.6 as I write this). In hindsight, this is relatively simple but it took me longer than expected to figure it out … so hopefully this post will help you as well.

What we want to do

Display a single category description on a blog page which lists posts in that category.

You can see this in action on my site. For example, for posts in the Tips and Tricks category, I am displaying the description that begins “Web design and development tips and tricks that can help improve your website…." above the posts.

Create a Perch template for the category description

The default category.html template in /perch/templates/categories/ already contains a field for the category description. Now, what we need is a different template that displays only the category description. I've called mine category_description.html and it just contains the same <perch:category> tag like this:

<perch:category id="desc" type="textarea" label="Description" editor="markitup" markdown="true" size="s" />

The template category_description.html goes in /perch/templates/categories/ as well.

Display the category description on the post listing page

In archive.php, which is one of the default blog pages with Perch, there is logic to display blog posts filtered by category, tag, year etc. I'm using the same code on my blog posts archive page. On that page, within the section of code for Posts by Category, I've added this code:

perch_categories(array(
                       'set'=>'blog',
                       'template'=>'category_description.html', 
                       'filter'=> 'catSlug',
                       'match' => 'eq',
                       'value' => perch_get('cat')            
));

What I'm doing here is using perch_categories to display the category set 'blog' using my category_description.html template and filtering on the catSlug field so that it matches the query string cat value in the URL. This gives me a single category and displays the relevant category description on my blog posts archive page.

So, it's similar code to my older category descriptions post but updated to work with the new Categories app in Perch.

Now, add some blog category descriptions via the Perch admin and you should be good to go. Yay!

Info: Here is the Perch documentation that describes Categories page functions.

Follow-up: You could also use this method to display other category fields. For example, category images.