Looking for help?
4.1. Custom Content Overview
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.
<?php perch_content_custom('News', $opts); ?>
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), DESC (descending) or RAND (random).
- 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. "/bhellob/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.
- paginate
- True of false. Enables pagination - use count to set the number of items per page.
- pagination_var
- The query string variable to use to hold the page number. Defaults to
page, e.g.?page=2 - hide_extensions
- True or false. Remove trailing file extensions when building pagination links.
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);
?>
Dealing with no results
Sometimes, if you filter the content of a region, you can end up with a situation where no items are matched. If you want to display something different in this situation, add a <perch:noresults></perch:noresults> section to your template.
Important Notes
The perch_content_custom() function differs from the perch_content() function, and is designed to supplement, not replace it.
- It cannot be used to define a new region.
- 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.
Pagination in templates
When using the pagination options, you need to also add some markup to your templates. An example would be:
<perch:after> <perch:if exists="paging"> <div class="paging"> Page <perch:content id="current_page" type="hidden" /> of <perch:content id="number_of_pages" type="hidden" /> <perch:if exists="not_first_page"> <a href="<perch:content id="prev_url" type="hidden" encode="false" />">Previous</a> </perch:if> <perch:if exists="not_last_page"> <a href="<perch:content id="next_url" type="hidden" encode="false" />">Next</a> </perch:if> </div> </perch:if> </perch:after>