mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
# Paginating A List
|
|
|
|
Adding pagination to a `[api:SS_List]` is quite simple. All
|
|
you need to do is wrap the object in a `[api:PaginatedList]` decorator, which takes
|
|
care of fetching a sub-set of the total list and presenting it to the template.
|
|
|
|
In order to create a paginated list, you can create a method on your controller
|
|
that first creates a `SS_List` that will return all pages, and then wraps it
|
|
in a `[api:PaginatedList]` object. The `PaginatedList` object is also passed the
|
|
HTTP request object so it can read the current page information from the
|
|
"?start=" GET var.
|
|
|
|
The paginator will automatically set up query limits and read the request for
|
|
information.
|
|
|
|
:::php
|
|
/**
|
|
* Returns a paginated list of all pages in the site.
|
|
*/
|
|
public function PaginatedPages() {
|
|
return new PaginatedList(Page::get(), $this->request);
|
|
}
|
|
|
|
Note that the concept of "pages" used in pagination does not necessarily
|
|
mean that we're dealing with `Page` classes, its just a term to describe
|
|
a sub-collection of the list.
|
|
|
|
## Setting Up The Template
|
|
|
|
Now all that remains is to render this list into a template, along with pagination
|
|
controls. There are two ways to generate pagination controls:
|
|
`[api:PaginatedList->Pages()]` and `[api:PaginatedList->PaginationSummary()]`. In
|
|
this example we will use `PaginationSummary()`.
|
|
|
|
The first step is to simply list the objects in the template:
|
|
|
|
:::ss
|
|
<ul>
|
|
<% loop $PaginatedPages %>
|
|
<li><a href="$Link">$Title</a></li>
|
|
<% end_loop %>
|
|
</ul>
|
|
|
|
By default this will display 10 pages at a time. The next step is to add pagination
|
|
controls below this so the user can switch between pages:
|
|
|
|
:::ss
|
|
<% if $PaginatedPages.MoreThanOnePage %>
|
|
<% if $PaginatedPages.NotFirstPage %>
|
|
<a class="prev" href="$PaginatedPages.PrevLink">Prev</a>
|
|
<% end_if %>
|
|
<% loop $PaginatedPages.Pages %>
|
|
<% if $CurrentBool %>
|
|
$PageNum
|
|
<% else %>
|
|
<% if $Link %>
|
|
<a href="$Link">$PageNum</a>
|
|
<% else %>
|
|
...
|
|
<% end_if %>
|
|
<% end_if %>
|
|
<% end_loop %>
|
|
<% if $PaginatedPages.NotLastPage %>
|
|
<a class="next" href="$PaginatedPages.NextLink">Next</a>
|
|
<% end_if %>
|
|
<% end_if %>
|
|
|
|
If there is more than one page, this block will render a set of pagination
|
|
controls in the form `[1] ... [3] [4] [[5]] [6] [7] ... [10]`.
|
|
|
|
## Paginating Custom Lists
|
|
|
|
In some situations where you are generating the list yourself, the underlying
|
|
list will already contain only the items that you wish to display on the current
|
|
page. In this situation the automatic limiting done by `[api:PaginatedList]`
|
|
will break the pagination. You can disable automatic limiting using the
|
|
`[api:PaginatedList->setLimitItems()]` method when using custom lists.
|
|
|
|
## Setting the limit of items to be displayed on a page ##
|
|
|
|
To set the limit of items displayed in a paginated page use the `[api:PaginatedList->setPageLength()]` method. e.g:
|
|
|
|
:::php
|
|
/**
|
|
* Returns a paginated list of all pages in the site, and limits the items displayed to 4 per page.
|
|
*/
|
|
public function PaginatedPagesLimit() {
|
|
$paginatedItems = new PaginatedList(Page::get(), $this->request);
|
|
$paginatedItems->setPageLength(4);
|
|
return $paginatedItems;
|
|
}
|
|
|
|
## Related
|
|
|
|
* [Howto: "Grouping Lists"](/howto/grouping-dataobjectsets)
|