Help / Custom Content

Using the custom content function

Content regions are defined using the perch_content() function, but there are times when you need more control over the output. The perch_content_custom() function exists for this purpose.

The function takes two arguments - the region name and then an associative array of options:

The possible options are as follows:

page

The path of the page from which to select the region.

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) or DESC (descending).

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. Possible values are:

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)

value

Used with filter and match. The value to match. For between and in, takes a comma delim string. For regex takes PCRE regular expression e.g. "/\bhello\b/i"

skip-template

True or false. Bypass template processing and return the content in an associative array.

raw

True or false. Returns unprocessed content, for use alongside skip-template.

The following example would show the most recent news item from the News page:

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

Important Notes

The perch_content_custom() function differs from the perch_content() function, and is design to supplement, not replace it.

1. It cannot be used to define a new region.
2. The contents are rendered at run time, unlike perch_content() which precompiles to HTML at edit time.

Care should be taken to use perch_content_custom() only when needed, and to use perch_content() at all other times.