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().

Properties

private $selection Initially holds the whole collection.

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.

filterBreadcrumbs(string $url)

Collect all pages along a given URL.

filterByKeywords(string $str)

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

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.

filterPrevAndNextToUrl(string $url)

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

filterRelated(Page $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)

array
getSelection(bool $excludeHidden = true, bool $excludeCurrent = false, int $offset = 0, int|null $limit = null)

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

match(array|null $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|null $options = null)

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

excludeHidden()

Exclude all hidden pages from the selection.

Details

__construct(array $pages)

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

Parameters

array $pages

excludeCurrent()

Exclude the current page from the selection.

excludePage(string $url)

Remove a page from the selection.

Parameters

string $url

filterBreadcrumbs(string $url)

Collect all pages along a given URL.

Parameters

string $url

filterByKeywords(string $str)

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

Parameters

string $str

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

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(Page $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

Page $Page

array getSelection(bool $excludeHidden = true, bool $excludeCurrent = false, int $offset = 0, int|null $limit = null)

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

Parameters

bool $excludeHidden
bool $excludeCurrent
int $offset
int|null $limit

Return Value

array $this->selection

match(array|null $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|null $options

sortPages(string|null $options = null)

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|null $options

private excludeHidden()

Exclude all hidden pages from the selection.