Skip to content

Commit

Permalink
Merge pull request codeigniter4#8256 from kenjis/docs-improve-pagination
Browse files Browse the repository at this point in the history 
docs: improve pagination
  • Loading branch information
@kenjis
kenjis committed Nov 28, 2023
2 parents fc500d0 + 0ea1c6a commit 93e9c6b
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 25 deletions.
21 changes: 11 additions & 10 deletions system/Pager/PagerRenderer.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,14 +25,14 @@
class PagerRenderer
{
/**
* First page number.
* First page number in the set of links to be displayed.
*
* @var int
*/
protected $first;

/**
* Last page number.
* Last page number in the set of links to be displayed.
*
* @var int
*/
Expand Down Expand Up @@ -85,8 +85,11 @@ class PagerRenderer
*/
public function __construct(array $details)
{
$this->first = 1;
$this->last = $details['pageCount'];
// `first` and `last` will be updated by `setSurroundCount()`.
// You must call `setSurroundCount()` after instantiation.
$this->first = 1;
$this->last = $details['pageCount'];

$this->current = $details['currentPage'];
$this->total = $details['total'];
$this->uri = $details['uri'];
Expand Down Expand Up @@ -122,8 +125,6 @@ public function hasPrevious(): bool
* page before the current page, but is the page just before the
* "first" page.
*
* You MUST call hasPrevious() first, or this value may be invalid.
*
* @return string|null
*/
public function getPrevious()
Expand Down Expand Up @@ -162,8 +163,6 @@ public function hasNext(): bool
* page after the current page, but is the page that follows the
* "last" page.
*
* You MUST call hasNext() first, or this value may be invalid.
*
* @return string|null
*/
public function getNext()
Expand Down Expand Up @@ -260,6 +259,8 @@ public function getCurrent(): string
* is represented by another array containing of the URI the link
* should go to, the title (number) of the link, and a boolean
* value representing whether this link is active or not.
*
* @return list<array{uri:string, title:int, active:bool}>
*/
public function links(): array
{
Expand Down Expand Up @@ -381,7 +382,7 @@ public function getNextPage()
}

/**
* Returns the page number of the first page.
* Returns the page number of the first page in the set of links to be displayed.
*/
public function getFirstPageNumber(): int
{
Expand All @@ -397,7 +398,7 @@ public function getCurrentPageNumber(): int
}

/**
* Returns the page number of the last page.
* Returns the page number of the last page in the set of links to be displayed.
*/
public function getLastPageNumber(): int
{
Expand Down
59 changes: 44 additions & 15 deletions user_guide_src/source/libraries/pagination.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,32 +227,39 @@ setSurroundCount()
In the first line, the ``setSurroundCount()`` method specifies than we want to show two links to either side of
the current page link. The only parameter that it accepts is the number of links to show.

.. note:: You must call this method first to generate correct pagination links.

hasPrevious() & hasNext()
-------------------------

These methods return a boolean true if there are more links that can be displayed on either side of the current page,
based on the value passed to ``setSurroundCount()``. For example, let's say we have 20 pages of data. The current
page is page 3. If the surrounding count is 2, then the following links would show up in the list: 1, 2, 3, 4, and 5.
Since the first link displayed is page one, ``hasPrevious()`` would return **false** since there is no page zero. However,
``hasNext()`` would return **true** since there are 15 additional pages of results after page five.
These methods return a boolean ``true`` if there are more links that can be displayed on either side of the current page,
based on the value passed to `setSurroundCount()`_.

For example, let's say we have 20 pages of data. The current
page is page 3. If the surrounding count is 2, then the following links would show up like this::

1 | 2 | 3 | 4 | 5

Since the first link displayed is page one, ``hasPrevious()`` would return ``false`` since there is no page zero. However,
``hasNext()`` would return ``true`` since there are 15 additional pages of results after page five.

getPrevious() & getNext()
-------------------------

These methods return the URL for the previous or next pages of results on either side of the numbered links.
These methods return the **URL** for the previous or next pages of results on either side of the numbered links.

For example, you have the current page set at 5 and you want to have the links before and after (the surroundCount) to be 2 each, that will give you something like this::

3 | 4 | 5 | 6 | 7

``getPrevious()`` returns the URL for page 2. ``getNext()`` returns the URL for page 8.

If you want to get page 4 and page 6, use ``getPreviousPage()`` and ``getNextPage()`` instead.
If you want to get page 4 and page 6, use `getPreviousPage() & getNextPage()`_ instead.

getFirst() & getLast()
----------------------

Much like ``getPrevious()`` and ``getNext()``, these methods return links to the first and last pages in the
Much like `getPrevious() & getNext()`_, these methods return the **URL** to the first and last pages in the
result set.

links()
Expand All @@ -263,9 +270,9 @@ title, which is just the number, and a boolean that tells whether the link is th

.. literalinclude:: pagination/013.php

In the code presented for the standard pagination structure, the methods ``getPrevious()`` and ``getNext()`` are used to obtain the links to the previous and next pagination groups respectively.
In the code presented for the standard pagination structure, the methods `getPrevious() & getNext()`_ are used to obtain the links to the previous and next pagination groups respectively.

If you want to use the pagination structure where prev and next will be links to the previous and next pages based on the current page, just replace the ``getPrevious()`` and ``getNext()`` methods with ``getPreviousPage()`` and ``getNextPage()``, and the methods ``hasPrevious()`` and ``hasNext()`` by ``hasPreviousPage()`` and ``hasNextPage()`` respectively.
If you want to use the pagination structure where prev and next will be links to the previous and next pages based on the current page, just replace the `getPrevious() & getNext()`_ methods with `getPreviousPage() & getNextPage()`_, and the methods `hasPrevious() & hasNext()`_ by `hasPreviousPage() & hasNextPage()`_ respectively.

See following an example with these changes:

Expand All @@ -274,21 +281,35 @@ See following an example with these changes:
hasPreviousPage() & hasNextPage()
---------------------------------

This method returns a boolean true if there are links to a page before and after, respectively, the current page being displayed.
This method returns a boolean ``true`` if there are links to a page before and after, respectively, the current page being displayed.

For example, let's say we have 20 pages of data. The current
page is page 3. If the surrounding count is 2, then the following links would show up like this::

1 | 2 | 3 | 4 | 5

``hasPreviousPage()`` would return ``true`` since there is page 2. And,
``hasNextPage()`` would return ``true`` since there is page 4.

Their difference to ``hasPrevious()`` and ``hasNext()`` is that they are based on the current page while ``hasPrevious()`` and ``hasNext()`` are based on the set of links to be displayed before and after the current page based on the value passed in ``setSurroundCount()``.
.. note:: The difference to `hasPrevious() & hasNext()`_ is that they are based
on the current page while `hasPrevious() & hasNext()`_ are based on the set
of links to be displayed before and after the current page based on the value
passed in `setSurroundCount()`_.

getPreviousPage() & getNextPage()
---------------------------------

These methods return a URL for the previous and next pages in relation to the current page being displayed, unlike ``getPrevious()`` and ``getNext()`` that return the URL for the previous or next pages of results on either side of the numbered links. See the previous paragraph for a full explanation.
These methods return a **URL** for the previous and next pages in relation to the current page being displayed.

For example, you have the current page set at 5 and you want to have the links before and after (the surroundCount) to be 2 each, that will give you something like this::

3 | 4 | 5 | 6 | 7

``getPreviousPage()`` returns the URL for page 4. ``getNextPage()`` returns the URL for page 6.

.. note:: `getPrevious() & getNext()`_ returns the URL for the previous or next
pages of results on either side of the numbered links.

If you want page numbers instead of URLs, you can use the following methods:

getPreviousPageNumber() & getNextPageNumber()
Expand All @@ -299,8 +320,16 @@ These methods return the page number for the previous or next pages in relation
getFirstPageNumber() & getLastPageNumber()
------------------------------------------

These methods return page numbers to the first and last pages in the
result set.
These methods return the page numbers of the first and last pages in the set of
links to be displayed. For example, if the set of links to be displayed is something like this::

3 | 4 | 5 | 6 | 7

``getFirstPageNumber()`` will return 3 while ``getLastPageNumber()`` will return 7.

.. note:: To obtain the page numbers of the first and last pages in the entire
result set, you can use the following approach: The first page number is always 1, and `getPageCount()`_ can be used to
retrieve the last page number.

getCurrentPageNumber()
----------------------
Expand Down

0 comments on commit 93e9c6b

Please sign in to comment.