class Selection (View source)

The Selection class holds all methods to filter and sort the collection of pages and return them as a new selection.

Every instance can return a filtered and sorted array of pages without hurting the original Automad object. That means the Automad class object has to be created only once. To get multiple different (sorted and filtered) collections, this class can be used by just passing the collection array.

All the filter function directly modify $this->selection. After all modifications to that selection, it can be returned once by $this->getSelection().

Methods

__construct(array $pages)

Pass a set of pages to $this->selection excluding all hidden pages.

excludeCurrent()

Exclude the current page from the selection.

excludePage(string $url)

Remove a page from the selection.

array
getSelection(boolean $excludeHidden = true, boolean $excludeCurrent = false, integer $offset = 0, integer $limit = NULL)

Return the array with the selected (filtered and sorted) pages.

filterBreadcrumbs(string $url)

Collect all pages along a given URL.

filterByParentUrl(string $parent)

Filter $this->selection by relative url of the parent page.

filterByTag(string $tag)

Filter $this->selection by tag.

filterByTemplate(string $regex)

Filter $this->selection by template. A regex can be used as filter string.

filterByKeywords(string $str)

Filter $this->selection by multiple keywords (a search string), if $str is not empty.

filterPrevAndNextToUrl(string $url)

Filter out the non-hidden neighbors (previous and next page) to the passed URL.

filterRelated(object $Page)

Filter all pages having one or more tag in common with $Page. If there are not tags defined for the passed page, the selection will be an empty array. (no tags = no related pages)

match(array $options)

While iterating a set of variable/regex combinations in $options, all pages where a given variable is not matching its assigned regex are removed from the selection.

sortPages(string $options = false)

Sorts $this->selection based on a sorting options string.

Details

__construct(array $pages)

Pass a set of pages to $this->selection excluding all hidden pages.

Parameters

array $pages (normally Automad::getCollection() or any other selection array)

excludeCurrent()

Exclude the current page from the selection.

excludePage(string $url)

Remove a page from the selection.

Parameters

string $url

array getSelection(boolean $excludeHidden = true, boolean $excludeCurrent = false, integer $offset = 0, integer $limit = NULL)

Return the array with the selected (filtered and sorted) pages.

Parameters

boolean $excludeHidden
boolean $excludeCurrent
integer $offset
integer $limit

Return Value

array $this->selection

filterBreadcrumbs(string $url)

Collect all pages along a given URL.

Parameters

string $url

filterByParentUrl(string $parent)

Filter $this->selection by relative url of the parent page.

Parameters

string $parent

filterByTag(string $tag)

Filter $this->selection by tag.

Parameters

string $tag

filterByTemplate(string $regex)

Filter $this->selection by template. A regex can be used as filter string.

For example passing 'page|home' as parameter will include all pages with a template that contains 'page' or 'home' as substrings.

Parameters

string $regex

filterByKeywords(string $str)

Filter $this->selection by multiple keywords (a search string), if $str is not empty.

Parameters

string $str

filterPrevAndNextToUrl(string $url)

Filter out the non-hidden neighbors (previous and next page) to the passed URL.

$this->selection only holds two pages after completion with the keys ['prev'] and ['next'] instead of the URL-key. If there is only one page in the array (has no siblings), the selection will be empty. For two pages, it will only contain the ['next'] page. For more than two pages, both neighbors will be set in the selection.

Parameters

string $url

filterRelated(object $Page)

Filter all pages having one or more tag in common with $Page. If there are not tags defined for the passed page, the selection will be an empty array. (no tags = no related pages)

Parameters

object $Page

match(array $options)

While iterating a set of variable/regex combinations in $options, all pages where a given variable is not matching its assigned regex are removed from the selection.

Parameters

array $options

sortPages(string $options = false)

Sorts $this->selection based on a sorting options string.

The option string consists of multiple pairs of a data key and a sort order, separated by a comma like this: $Selection->sortPages('date desc, title asc') The above example will sort first all pages in the selection by 'date' (descending) and then by 'title' (ascending).

Valid values for the order are 'asc' and 'desc'.
In case a sort order is missing in a key/order combination, the 'asc' is used as a fallback.

Parameters

string $options (comma separated list of keys and order)