1. class
  2. Automad
  3. \
  4. Core
  5. \
  6. Selection

Selection

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

at line 69
__construct(array $pages)

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

Parameters

array $pages

at line 76
excludeCurrent()

Exclude the current page from the selection.

at line 85
excludePage(string $url)

Remove a page from the selection.

Parameters

string $url

at line 96
filterBreadcrumbs(string $url)

Collect all pages along a given URL.

Parameters

string $url

at line 128
filterByKeywords(string $str)

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

Parameters

string $str

at line 164
filterByParentUrl(string $parent)

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

Parameters

string $parent

at line 182
filterByTag(string $tag)

Filter $this->selection by tag.

Parameters

string $tag

at line 203
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

at line 226
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

at line 275
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

at line 303
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

at line 321
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

at line 353
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

at line 408
private excludeHidden()

Exclude all hidden pages from the selection.