perch_collection()

Displays a collection on the page by name.

Requires

Parameters

Type Description
String Name of the collection
Array Options array, see table below
Boolean Set to true to have the value returned instead of echoed.

perch_collection options

Option Value
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 Aliases Description
eq is, exact equal to
neq not, !eq 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)
!contains opposite of contains: the value does not exist within the content
regex regexp using a PCRE regular expression
between match between two values
!between opposite of between
eqbetween match between two values inclusively
!eqbetween opposite of eqbetween
in within match within a comma delimited content list (like a list of tags)
!in !within opposite of in

Example

The following example would show the most recent news item from the News collection.

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_collection('News', [
        'template'   => 'article.html',
        'sort'       => 'date',
        'sort-order' => 'DESC',
        'count'      => 1,
    ]);
?>

Filtering content

You can filter a collection 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 collection 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_collection('Properties', [
        'filter' => 'bedrooms',
        'match'  => 'gte',
        'value'  => 3,
    ]);
?>

Filtering by multiple fields

You can filter collection 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_collection('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_collection('Properties', [
    'filter' => [
        [
            'filter' => 'bedrooms',
            'match'  => 'gte',
            'value'  => 3,
        ],
        [
            'filter' => 'price',
            'match'  => 'lte',
            'value'  => 500000,
        ],
    ],
    'match' => 'or',
]);
?>

Specifying an item callback function

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

<?php
perch_collection('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.