Collections are big repositories that hold one type of content. You might have a collection of Articles and a collection of Authors. You can then create relationships between collections, for example to relate an Author to an Article.
In use, collections can be displayed in just the same way as basic content regions, but there are a few key differences.
Differences between Collections and Regions
- Regions are tied to a page or (for shared regions) to every page. Collections are not tied to any page.
- Version revisioning on collections is per item, whereas regions are versioned per region
- A link to manage a collection can be added to any number of your control panel pages, and to the sidebar where needed
Managing a collection from a page
Adding a link to edit a collection from a page particular page in the control panel enables you to provide a logical editing experience for your client. You might have a collection of news articles, and also a News page that displays them. Make life easy for your client by linking the collection from the News page, which is where they’d probably expect to find it.
- Create a collection from the Collections section under Pages
- Find your page and go to the Page Options
- You should see your collection listed in the Collections section. Check the box to add it to this page, and save.
When you go to edit the page, the collection should now be listed with the page’s regions. Clicking on it jumps you through to the collection edit page.
Adding a collection to the sidebar
- Go to Settings and to the Menu Manager
- Select an existing menu or create a new one
- Create a new menu item
- Enter a title and choose your collection from the “Link to Collection” list, and save.
Your collection will now appear in the choosen point in the sidebar menu.
Importing from a Region to a Collection
When moving from a Perch site to Runway, or if restructuring a site because it’s grown in ways you didn’t expect, it can be useful to import one or more regions into a collection.
To do this, the structure of the region(s) and the collection must be compatible - their templates need to include the same IDs and types.
- Create your new collection
- In the collection, go to the Import tab
- Select the page the region is on, click next
- Select the region, click next
- You’ll be asked to confirm your choices, click Import
Importing other data into a collection
If you need to import external data into a collection, that’s possible too. To give the most flexibility, this is done by writing a script to import the data using an import API. You can read about importing into a collection in the API docs.
Displaying content from collection
Content is displayed using the
perch_collection() page function, which works in the same way as perch_content_custom().
perch_collection('Articles', [ 'count' => 3, 'sort' => '_date', 'sort-order' => 'DESC', ]);
|template||The name of a template to use to display the content.|
|sort||The ID of the field to sort on.|
|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
|category||Filter by one or more categories. 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
|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
|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
|neq||not equal to|
|gte||greater than or equal to|
|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)|