Does your site run on Perch CMS? Hire me to help. Perch CMS Development

Working with Perch categories

Posted on by Clive Walker in Perch

I wrote this post a while back. The content can still be relevant but the information I've linked to may not be available.

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>

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:

Categories screenshot

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:

 if (perch_get('cat')) {
 //output the category title and description, using default category.html template
 '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',
 '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>';

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>
 <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>
 <a href="/<perch:content id="pubid" />.php"><perch:content id="pubname" type="text" /></a> in <perch:content id="location" /></li>

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>

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.

Does your site run on Perch CMS? Hire me to help. Perch CMS Development


  • Edward:

    15 Sep 2018 13:19:00

    Hi There. Is it possible to get copies of your page and content template. Not all but just the necessary. Struggling a bit to make it work. Thanks.

  • 15 Sep 2018 16:23:00

    The Perch code for the Category page is shown in its entirety in my post and the rest of the page is standard HTML. The Pub page contains a standard Perch template with the addition of the categories code section above. Which part isn’t working? Can you post this on the Perch forum and I’ll comment there.

Comments are OFF for this post.

© 2024 Clive Walker