perch_blog_custom()

Much like the default perch_content_custom() function, Blog has perch_blog_custom(). This function enables you to get a blog listing customized by any of the available parameters.

The perch_blog_custom function is very useful for displaying a specific list of posts on a homepage for example.

The options for filter, match and value work just like perch_content_custom. Category and tag can be either a single item or an array. To exclude a category or tag from the results, prefix its name with an exclamation point, e.g. !news.

Requires

Parameters

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

Options array

Name Value
tag A single tag or array of tags to return content for. To exclude a tag, prefix its name with an exclamation point.
category A single category slug or array of category slugs to return content for. To exclude a category, prefix its name with an exclamation point.
author A single author slug or ID to filter the results by.
section A single section slug to filter the results by.
blog The slug of the blog to pull content from. See Multiple Blogs.
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.

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

Usage examples

The below example filters on postDateTime, returning entries equal to or between the 1st January 2009 and 1st March 2009 which are in the category news or announcements. I have also passed in a custom template for this listing.

<?php
perch_blog_custom(array(
    'filter' => 'postDateTime',
    'match' => 'eqbetween',
    'value' => '2009-01-01, 2009-03-01',
    'category' => array('news', 'announcements'),
    'template' => 'special_listing.html',
));
?>