perch_content_custom()

To define editable regions you need to use perch_content() however there is a second page function for content that can give you more control over the output of your content.

The perch_content_custom() function takes the region name and an array of options to enable you to manipulate the content.

<?php
  perch_content_custom('News', []);
?>

When to use perch_content_custom

It is important to note that perch_content_custom() should not be used to replace all of your perch_content tags.

The perch_content_custom() tag cannot be used to define a new region, that has to be done using perch_content() or perch_content_create(). In addition perch_content_custom() is not cached at edit time, the processing has to happen at run time so loses the performance advantage that perch_content() has.

The most common use of this functionality is to reuse some content used elsewhere on the page or site. For example when creating a list of FAQ questions at the top of a FAQ page so the visitor can jump down from question to answer.

perch_content_custom options

Option Value
page The path or array of paths of the page from which to select the region. Should be root-relative. Can end in a * wildcard.
template The name of a template to use to display the content.
sort The ID of the field to sort on.
sort-order Either ASC (ascending), DESC (descending) or RAND (random).
sort-type Either alpha or numeric. Default is alpha.
count The number of items to display.
start The item number to start displaying from.
filter The ID of a field to filter the results by.
match Used with filter, see the below table for values
value Used with filter and match. The value to match. For between and in, takes a comma delimited string. For regex takes PCRE regular expression.
category Filter by one or more categories. See Category filtering
category-match Either any or all. See Category filtering
skip-template True or false. Bypass template processing and return the content in an associative array.
return-html True or false. For use with skip-template. Adds the HTML onto the end of the returned array with key html.
split-items True or false. Return an array of individually templated items.
raw True or false. Returns unprocessed content, for use alongside skip-template.
paginate True or false. Whether to use pagination.
count Integer. (When used with paginate) The number of items to show per page if pagination is being used.
pagination-var The URL query string parameter name to use for the page number. Defaults to page.
page-links True or false. Create numbered page links as well as previous and next links.
page-link-template The template to use (if not the default) to generate the page links.
page-link-style shortened or all. By default a shortened set of page links are generated. If you want a link for every page, set to all.

Possible values for match

Value Description
eq equal to
neq not equal to
gt greater than
gte greater than or equal to
lt less than
lte less than or equal to
contains the value exists within the content (a simple search)
regex using a PCRE regular expression
between match between two values
eqbetween match between two values inclusively
in match within a comma delimited content list (like a list of tags)

Example

The following example would show the most recent news item from the News page. It assumes that you have a page at /news/index.php that has an editable region on it (added using perch_content) called News.

The template is a template (a default template or one you have created) from /templates/content. If the template is directly within that folder just give the template filename, if it is inside a subfolder you should include the subfolder in this path.

<?php
  perch_content_custom('News', [
    'page'=>'/news/index.php',
    'template'=>'article.html',
    'sort'=>'date',
    'sort-order'=>'DESC',
    'count'=>1
  ]);
?>

Filtering content

You can filter a region to only display a subset of items. This is done with the filter option, which is always used with match and value.

Take the example of a multiple-item region containing properties (real estate). We could filter the list to only show properties where the bedrooms field as a value of 3 or higher.

<?php
perch_content_custom('Properties', [
    'filter'=>'bedrooms',
    'match'=>'gte',
    'value'=>3
]);
?>

Filtering by multiple fields

You can filter content regions by more than one field by setting an array of filters as the filter option. This is best shown in an example.

Using the same property search example, the below will find all properties with 3 or more bedrooms. To also filter by price, the filter option becomes an array of filters. Each item in the filter array is an array of filter, match, value.

<?php
perch_content_custom('Properties', [
    'filter'=> [
        [
            'filter'=>'bedrooms',
            'match'=>'gte',
            'value'=>3
        ],
        [
            'filter'=>'price',
            'match'=>'lte',
            'value'=>500000
        ],
    )
]);
?>

This would find properties with 3 or more bedrooms, costing 500,000 or less. Filters are AND by default. You can make it OR like this:

<?php
perch_content_custom('Properties', [
    'filter'=>[
        [
            'filter'=>'bedrooms',
            'match'=>'gte',
            'value'=>3
        ],
        [
            'filter'=>'price',
            'match'=>'lte',
            'value'=>500000
        ],
    ],
    'match'=>'or'
]);
?>

Using content from different pages

The page option can be used to pull content in from another page.

This will return the content for the region ‘Properties’ on the page /properties.php:

<?php
perch_content_custom('Properties', [
    'page'=>'/properties.php'
]);
?>

You can collect content from multiple pages by using an array:

<?php
perch_content_custom('Properties',  [
    'page' => ['/properties.php', '/properties-archive.php'],
]);
?>

Sometimes, you may need to pull content from a lot of pages, or you may not know the page name. This happens if your client is created pages once the site is live. You can use a wildcard at the end of the path to find any page that matches.

For example, this would find the ‘Product’ region on any page with a path that starts /products/:

<?php
perch_content_custom('Products', [
    'page' => '/products/*'
]);
?>

When doing this, you sometimes need to know where the content has come from. For example, you might have a list of items that has been pulled from multiple pages, and want to link to each item’s page. To help with this the special ID value _page is available within your template:

<a href="<perch:content id="_page" />">Read more</a>

Specifying an item callback function

When retrieving multiple items (such as a filtered list from a multiple item region) it is possible to specify a PHP callback function for processing each item before it is templated.

<?php
perch_content_custom('Products', [
    'each' => function($item) {
        // process as necessary, then return the modified array
        return $item;
    },
]);
?>

The each option should be specified as a PHP anonymous function or closure. The function will be passed a single argument, which is an associative array representing each item in turn. After processing, the function must return the array.

Retrieving content from multiple regions

The first argument to perch_content_custom() is the key (or name) of the region you want to fetch the content from.

This can also be an array of keys.

perch_content_custom(['News', 'Updates'], [...]);

Of course, this can lead to data of different ‘shapes’ being processed as one collection, so you’ll need to make sure your template or code can deal with that.