Working with content in Perch - the Custom Functions

This is the first of a series of posts to introduce some of the things you can do with the custom functions in Perch and Perch Runway. In this first post I’ll introduce perch_content_custom.

Anything added using a template stored in perch/templates/content can be accessed using the perch_content_custom function. Perhaps you have added some Apartments for lease, as described in this earlier post. These got into Perch via a page with a regular Perch Region on it, in the admin you chose your apartment.html template, it looks like this.

<div class="apartment">
  <h3 class="<perch:if id="leased" value="yes">leased<perch:else/>available</perch:if>"><perch:content id="apartmentname" type="text" label="Name" required="true" title="true" /> <span>- <perch:if id="leased" value="yes">leased<perch:else/>available</perch:if></span></h3>
  <p>No. of rooms: <perch:content id="rooms" type="text" label="No. of bedrooms" required="true" size="s" /></p>
  <div class="description">
    <perch:content id="description" type="textarea" label="Description" markdown="true" editor="markitup" required="true" />
  </div>
</div>
<perch:content id="leased" type="checkbox" label="Apt. is leased" value="yes" suppress="true" />

An apartment is a collection of data, we have:

So with our regular Perch Region set to allow multiple items we can add multiple apartments and we have the ability to do some basic ordering of the data from within the Perch Admin Control Panel.

If you want more control, then this is where perch_content_custom comes in. The perch_content_custom function gives you options to filter and sort your data in many different ways.

The difference between content custom and content

The perch_content_custom function is a replacement for perch_content, however it cannot be used to create a region. To create a region you should use perch_content, or if you need to create a region in code perch_content_create.

You can create a region on a page with the perch_content function and switch it out for perch_content_custom if it turns out you need to use some of the custom functionality.

You can create a region in code with perch_content_create and then use perch_content_custom – note that in this case you need both functions on the page – the one that creates the region then the function to use it.

You can also use perch_content_custom to pull data from the page on which it is displayed using regular perch content, and display in in a different way.

Performance implications of using perch content custom

As you use perch content custom to display content by way of filters we cannot cache it in the way that we do Perch content. So the most performant method of displaying data on the page is regular Perch content, the data and templates for regular perch regions with perch content are all compiled at edit time because we know the options you have selected.

That said content custom is still very performant, but we’d suggest always opting for the highest performing option when you have the chance.

Custom functions for Collections and in First Party Apps

perch_content_custom is for use with Perch Content. If you are in a First Party App then you will find a perch_APPNAME_custom function that works in more or less the same way as perch_content_custom, check the App documentation for any differences or app specific additions, you can see the details for perch_blog_custom here.

Perch Runway Collections has the perch_collection function, this works in the same way as perch_content_custom.

In the next post in the series we take a look at how to pass options into these functions.