get_filtered_listing()

Get a filtered list of items.

Parameters

$Factory->get_filtered_listing($opts, $where_callback, $pre_template_callback);

Type	Description	Default
Array	Options array, see table below
Function	See where callback below	`null`
Function	See pre-template callback below	`null`

Option array

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`

Where callback

A function that returns a PerchQuery object. The query is merged with the database query generated by the get_filtered_listing() method.

$where_callback = function(PerchQuery $Query, $opts) {
  return $Query;
};

Type	Description
Object	PerchQuery object
Array	The options array passed from `get_filtered_listing()`

Pre-template callback

A function to apply to the returned rows before entering the templating phase.

$pre_template_callback = function($rows, $opts) {
  return $rows;
};

Type	Description
Array	An array of the returned rows
Array	The options array passed from `get_filtered_listing()`

Usage

$API = new PerchAPI(1.0, 'company_app');
$Articles = new CompanyApp_Articles($API);

$Articles->get_filtered_listing([
  'template' => $template,
  'filter' => 'status',
  'match' => 'eq',
  'value' => 'published',
]);