Perch functions are PHP functions used on PHP pages in Perch and in your Master Pages in Perch Runway. As these functions are PHP they cannot go into your templates, instead you add these to the pages of your site.
There are functions which make up the core functionality of Perch, add-ons also introduce their own functions. These are all detailed in this section of the documentation.
You use the most basic Perch Function when you get started and create your first Perch Region.
<?php perch_content('Intro'); ?>
Here we use the
perch_content() function, passing as a parameter the string ‘Intro’, this becomes the name of the Region in the Perch Admin.
Some functions have additional parameters, and the page for that function will explain what they are. In general you will be passing into a function one of the following things.
In the example above we pass a string into our function, and to indicate this we enclose the text in quotes. This value will be directly passed to the function, Perch then uses it as the name of that Region.
You can also pass numbers into functions. These do not need to be quoted.
Sometimes you will need to pass boolean values of
false to your function. An additional parameter for
perch_content() is to pass in the boolean
true after the name of the region. Boolean values should not be quoted.
<?php $my_var = perch_content('Intro', true); ?>
perch_content() without this value means that the content of that Region is directly output to the page, adding
true stores the content in a PHP Variable named
A PHP Variable
We saw a PHP Variable in the last example. PHP Variables start with the dollar symbol
$ and if you pass one into a Perch Function (or other PHP function) they should not be quoted. In the example below I am passing a variable named
$content into the
perch_template() function, along with a string to identify the template. You can see how the string is quoted and the variable is not.
Many Perch functions are passed an array. These arrays are essentially data stored in a key, value format. The key being the name that Perch expects the data to be referenced by and the value is the current value for that option. It’s a way of passing in lots of different options in a structured way.
In the example below I am using
perch_content_custom(), passing in the name of the region and then an array which contains two key value pairs. One with a key of
template, which assigns the template I want to use with this content and another with a key of
count which has a value of the number of items I want to display.
<?php perch_content_custom('News', array( 'template' => 'content/article.html', 'count' => 4 )); ?>
The keys and the values are separated with a double arrow
=> and each line, other than the last ends with a comma. If you are using PHP 5.4 or over you can use a simpler array syntax which replaces
array() wrapped around the set of key value pairs with
. Our function would then look like this:
<?php perch_content_custom('News', [ 'template' => 'content/article.html', 'count' => 4 ]); ?>
If you are using PHP 5.4+ you can take our pick as to which syntax to use.