Working with Perch categories

I've been working on a personal project. Horsham Pub Guide has been recoded so that it makes better use of Perch CMS. As part of that work, I've added pub categories and this post explains what I've done.

The pub page

My pub pages, such as The Royal Oak, have a Main Content region that uses a pub-details.html template with multiple fields, for example pub name, address, map, and image, and these are all standard Perch field-types.

I added a category set called Pubs with its categories in Perch admin and included these in my region template with the following code:

<perch:categories id="categories" set="pubs" label="I Like Because" display-as="checkboxes" order="6">
<perch:before><h3>I Like</h3><ul class="pub-categories"></perch:before>
<li><a href="/category/<perch:category id="catSlug" />"><perch:category id="catTitle" type="text" /></a></li>
<perch:after></ul></perch:after>
</perch:categories>

On the pub page, this gives me an unordered list of categories (styled) as links. I'm rewriting the category URL in the links so that it is a bit cleaner but it's actually /by-category.php?cat=catSlug. On the pub page, it looks like this:

In the admin, my categories appear on the edit region screen as checkboxes and it's easy to assign these to each pub.

The category page

Now, on the category page, I want to do a couple of things. I need to show pubs in the appropriate category when a user clicks through from an individual pub page and I also need to show a list of all categories if a user clicks through from somewhere else. Here's the code that does that:

<?php
 if (perch_get('cat')) {
 //output the category title and description, using default category.html template
 perch_categories(array(
 'set'=>'Pubs',
 'filter'=> 'catSlug',
 'match' => 'eq',
 'value' => perch_get('cat')
 )); 
// then we output a listing of pubs in that category
 perch_content_custom('Main Content', array(
 'template' => 'pub-listing.html',
 'page'=>'/*',
 'category' => 'pubs/'.perch_get('cat'),
 'sort'=> 'pubid',
 'sort-order' => 'ASC'
 )); }
else { // if no query string, just output a list of categories, displayed as 'tags'
 echo '<h2>The Categories</h2>';
 perch_categories(array(
 'set'=>'Pubs',
 'template'=>'category-list.html',
 )); 
 }
 ?>

Firstly, if a user clicks through from a category link, I'm using perch_categories to grab the category title and description and display on the page with the default category.html template in /perch/templates/categories.

After that, perch_content_custom is used with a pub-listing.html template to get the pubs in the category corresponding to the query string. I use the category path for the category value, i.e 'category' => 'pubs/'.perch_get('cat') and sort the pubs by an id value (essentially a slug of the pub name).

My pub-listing.html template, in /perch/templates/content, is quite standard.

<perch:before><ul class="pub-listing"></perch:before>
 <li>
 <perch:if exists="image"><a href="/<perch:content id="pubid" />.php">
 <img class="main-image fl" src="<perch:content id="image" type="image" width="100" height="75" crop="true" />" alt="<perch:content id="alt" />" /></a>
 </perch:if>
 <a href="/<perch:content id="pubid" />.php"><perch:content id="pubname" type="text" /></a> in <perch:content id="location" /></li>
<perch:after></ul></perch:after>

Finally, I need to list all categories if there is no query string, i.e the user is clicking through to the page from a non-category link. This goes in the else part of my if-else statement.

I use perch_categories again but with a different template, category-list.html, as follows:

<perch:before><p>Click on a link to see pubs in that category. The categories are my personal choice.</p>
<ul class="pub-categories"></perch:before>
<li><a href="/category/<perch:category id="catSlug" />"><perch:category id="catTitle" type="text" /></a></li>
<perch:after></ul></perch:after>

This template goes in /perch/templates/categories.

In summary

The key things here are 1) use perch_categories with two different templates and 2) use perch_content_custom and match the category to a category path containing the query string.

For me, this example was a good introduction to categories in Perch although it took me a while to figure out, partly through examples in the Perch documentation and the forum. I hope the above is useful for anyone else.

• Demo: The page examples are The Royal Oak and the By Category page.