newPagelist

Creates a new pagelist object. The current pagelist will be replaced. A foreach loop can be used to iterate over the pagelist object. This method does not have any output. To only update the configuration of the current pagelist, without resetting all other parameters, the pagelist method can be used instead.

<@ newPagelist { options } @>

Options

context: false String|false

An optionally fixed URL for the context of a pagelist of type breadcrumbs or children. In case this parameter is false, within a loop the context always changes dynamically to the current page.

excludeCurrent: false Boolean

Defines whether the current page is excluded from the pagelist.

excludeHidden: true Boolean

Defines whether hidden pages are excluded from the list.

filter: false String|false

Filters the pagelist by a given tag.

limit: NULL Integer|NULL

Limits the pagelist to a maximum number of pages.

match: false JSON String|false

Filters the pagelist by a set of variable/regex combinations. While iterating the set of combinations, all pages where a given variable value is not matching its assigned regex are removed from the pagelist. Note that the set of combinations has to be passed as a JSON formatted string and not as a JSON object. A valid value looks like '{"url": "/(work|blog)/"}' or even '{"url": "@{ regex }"}'.

offset: 0 Integer

Offsets the selection of pages. The given number of pages will be stripped from the start of the selection.

page: false Integer|false

The current page of the pagination. This parameter should be used in combination with the limit parameter.

search: false String|false

Filters the pagelist by a given search string. The string can contain multiple keywords separated by spaces. Only pages containing all given keywords get included in the pagelist.

sort: false String|false

Sorts the pagelist by a combination of a variable and order. Multiple combinations can be specified.
For example sort: "date desc, title asc" will first sort all pages by date in descending order and then by title in ascending order. Setting this parameter to false will sort the pages by :basename asc.

template: false String|false

Filters the pagelist by template names matching a specified regex. Multiple templates can therefore be matched by using the | operator, like template: "page|home".

type: false String|false

Sets the pagelist type.

Examples

To get all pages of the first level and iterate over them, like a simple top navigation, you can use the following snippet:

<@ newPagelist { 
    type: 'children', 
    context: '/' 
} @>
<@ foreach in pagelist @>
    <a href="@{ url }">@{ title }</a>
<@ end @>

A more complex example could be a search results page with filters and pagination.
Note that it is possible to use query string parameters in the option array for dynamic filtering, searching and pagination (lines 3, 4 and 8).

<@ newPagelist { 
    excludeHidden: false,
    filter: @{ ?filter }, 
    search: @{ ?search },
    sort: ':basename asc',
    template: 'documentation',
    limit: 10,
    page: @{ ?page | def (1) }
} @>

Filtering a pagelist by using the match option can be done as follows. Note that the JSON string is wrapped in single quotes.

<@ newPagelist { 
    match: '{"url": "@{ regex }"}'
} @>

It is also possible to match pages by passing multiple regex patterns.

<@ newPagelist { 
    match: '{"url": "@{ regex }", ":level": "/2/"}'
} @>