2019-11-18 05:58:33 +01:00
---
2014-10-13 09:49:30 +02:00
title: How to Create a Paginated List
2019-11-18 05:58:33 +01:00
summary: Break up the result of a database query into multiple pages
---
2014-10-13 09:49:30 +02:00
# How to Create a Paginated List
In order to create a paginated list, create a method on your controller that first creates a `SS_List` that contains
2017-07-03 03:22:12 +02:00
all your record, then wraps it in a [PaginatedList ](api:SilverStripe\ORM\PaginatedList ) object. The `PaginatedList` object should also passed the
[HTTPRequest ](api:SilverStripe\Control\HTTPRequest ) object so it can read the current page information from the "?start=" GET var.
2014-10-13 09:49:30 +02:00
The `PaginatedList` will automatically set up query limits and read the request for information.
2018-06-25 00:39:53 +02:00
**app/code/Page.php**
2014-10-13 09:49:30 +02:00
2017-08-07 05:11:17 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\PaginatedList;
2017-10-26 02:22:02 +02:00
2017-10-27 04:38:27 +02:00
/**
* Returns a paginated list of all pages in the site.
*/
public function PaginatedPages()
{
$list = Page::get();
2014-10-13 09:49:30 +02:00
2017-10-27 04:38:27 +02:00
return new PaginatedList($list, $this->getRequest());
}
2017-08-07 05:11:17 +02:00
```
2014-10-13 09:49:30 +02:00
2019-11-18 05:58:33 +01:00
[notice]
2014-10-13 09:49:30 +02:00
Note that the concept of "pages" used in pagination does not necessarily mean that we're dealing with `Page` classes,
it's just a term to describe a sub-collection of the list.
2019-11-18 05:58:33 +01:00
[/notice]
2014-10-13 09:49:30 +02:00
2017-07-03 03:22:12 +02:00
There are two ways to generate pagination controls: [PaginatedList::Pages() ](api:SilverStripe\ORM\PaginatedList::Pages( )) and
[PaginatedList::PaginationSummary() ](api:SilverStripe\ORM\PaginatedList::PaginationSummary( )). In this example we will use `PaginationSummary()` .
2014-10-13 09:49:30 +02:00
The first step is to simply list the objects in the template:
2018-06-25 00:39:53 +02:00
**app/templates/Page.ss**
2014-10-13 09:49:30 +02:00
2017-08-07 05:11:17 +02:00
```ss
2017-10-27 04:38:27 +02:00
< ul >
< % loop $PaginatedPages %>
< li > < a href = "$Link" > $Title< / a > < / li >
< % end_loop %>
< / ul >
2017-08-07 05:11:17 +02:00
```
2014-10-13 09:49:30 +02:00
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:
2018-06-25 00:39:53 +02:00
**app/templates/Page.ss**
2014-10-13 09:49:30 +02:00
2017-08-07 05:11:17 +02:00
```ss
2017-10-27 04:38:27 +02:00
< % if $PaginatedPages.MoreThanOnePage %>
< % if $PaginatedPages.NotFirstPage %>
< a class = "prev" href = "$PaginatedPages.PrevLink" > Prev< / a >
< % end_if %>
2019-08-13 05:17:38 +02:00
< % loop $PaginatedPages.PaginationSummary %>
2017-10-27 04:38:27 +02:00
< % if $CurrentBool %>
$PageNum
< % else %>
< % if $Link %>
< a href = "$Link" > $PageNum< / a >
< % else %>
...
< % end_if %>
< % end_if %>
2018-08-14 05:35:28 +02:00
< % end_loop %>
2017-10-27 04:38:27 +02:00
< % if $PaginatedPages.NotLastPage %>
< a class = "next" href = "$PaginatedPages.NextLink" > Next< / a >
< % end_if %>
< % end_if %>
2017-08-07 05:11:17 +02:00
```
2014-10-13 09:49:30 +02:00
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
2017-07-03 03:22:12 +02:00
that you wish to display on the current page. In this situation the automatic limiting done by [PaginatedList ](api:SilverStripe\ORM\PaginatedList )
will break the pagination. You can disable automatic limiting using the [PaginatedList::setLimitItems() ](api:SilverStripe\ORM\PaginatedList::setLimitItems( )) method
2014-10-13 09:49:30 +02:00
when using custom lists.
2017-08-07 05:11:17 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\PaginatedList;
2014-10-13 09:49:30 +02:00
2017-10-27 04:38:27 +02:00
$myPreLimitedList = Page::get()->limit(10);
$pages = new PaginatedList($myPreLimitedList, $this->getRequest());
$pages->setLimitItems(false);
2017-08-07 05:11:17 +02:00
```
2014-10-13 09:49:30 +02:00
## Setting the limit of items
2017-08-07 05:11:17 +02:00
```php
2017-10-27 04:38:27 +02:00
$pages = new PaginatedList(Page::get(), $this->getRequest());
$pages->setPageLength(25);
2017-08-07 05:11:17 +02:00
```
2014-10-13 09:49:30 +02:00
2015-03-05 00:07:14 +01:00
If you set this limit to 0 it will disable paging entirely, effectively causing it to appear as a single page
list.
2014-10-13 09:49:30 +02:00
## Template Variables
| Variable | Description |
| -------- | -------- |
| `$MoreThanOnePage` | Returns true when we have a multi-page list, restricted with a limit. |
| `$NextLink` , `$PrevLink` | They will return blank if there's no appropriate page to go to, so `$PrevLink` will return blank when you're on the first page. |
| `$CurrentPage` | Current page iterated on. |
| `$TotalPages` | The actual (limited) list of records, use in an inner loop |
2020-09-14 13:56:33 +02:00
| `$FirstItem` | Returns the number of the first item being displayed on the current page. This is useful for things like “displaying 10-20”. |
| `$LastItem` | Returns the number of the last item being displayed on this page. |
2014-10-13 09:49:30 +02:00
| `$TotalItems` | This returns the total number of items across all pages. |
| `$Pages` | Total number of pages. |
| `$PageNum` | Page number, starting at 1 (within `$Pages` ) |
| `$Link` | Links to the current controller URL, setting this page as current via a GET parameter |
| `$CurrentBool` | Returns true if you're currently on that page |
2017-11-27 04:39:17 +01:00
## Related Lessons
* [Lists and pagination ](https://www.silverstripe.org/learn/lessons/v4/lists-and-pagination-1 )
2014-10-13 09:49:30 +02:00
## API Documentation
2017-07-03 03:22:12 +02:00
* [PaginatedList ](api:SilverStripe\ORM\PaginatedList )
2014-10-13 09:49:30 +02:00