Merge pull request #6181 from kenjis/fix-docs-pagination.rst

docs: improve pagination.rst

Author: kenjis

user_guide_src/source/libraries/pagination.rst

@@ -18,9 +18,11 @@ to load it manually:
 
 .. literalinclude:: pagination/001.php
 
-***************************
-Paginating Database Results
-***************************
+.. _paginating-with-models:
+
+**********************
+Paginating with Models
+**********************
 
 In most cases, you will be using the Pager library in order to paginate results that you retrieve from the database.
 When using the :doc:`Model </models/model>` class, you can use its built-in ``paginate()`` method to automatically
@@ -37,8 +39,8 @@ The first element is the results from the database, **users**, which is retrieve
 the Model will hold on to the instance it used and store it in the public property, ``$pager``. So, we grab
 that and assign it to the ``$pager`` variable in the view.
 
-.. important:: It is important to understand that the Model::paginate() method uses the Model and QueryBuilder methods.
-    Therefore, trying to use ``$db->query()`` and Model::paginate() **will not work** because ``$db->query()`` executes
+.. important:: It is important to understand that the ``Model::paginate()`` method uses the **Model** and **QueryBuilder** methods.
+    Therefore, trying to use ``$db->query()`` and ``Model::paginate()`` **will not work** because ``$db->query()`` executes
     the query immediately and is not associated with a QueryBuilder.
 
 To define conditions for pagination in a model, you can:
@@ -91,29 +93,26 @@ like **https://domain.tld/foo/bar/[pageNumber]** instead of **https://domain.tld
 
 Please note: ``$segment`` value cannot be greater than the number of URI segments plus 1.
 
+*****************
 Manual Pagination
-=================
+*****************
 
 You may find times where you just need to create pagination based on known data. You can create links manually
 with the ``makeLinks()`` method, which takes the current page, the number of results per page, and
-the total number of items as the first, second, and third parameters, respectively::
+the total number of items as the first, second, and third parameters, respectively:
 
-    <?= $pager->makeLinks($page, $perPage, $total) ?>
+.. literalinclude:: pagination/015.php
 
 This will, by default, display the links in the normal manner, as a series of links, but you can change the display
 template used by passing in the name of the template as the fourth parameter. More details can be found in the following
-sections.
+sections::
 
-::
-
-    <?= $pager->makeLinks($page, $perPage, $total, 'template_name') ?>
+    $pager->makeLinks($page, $perPage, $total, 'template_name');
 
 It is also possible to use a URI segment for the page number, instead of the page query parameter, as described in
-the previous section. Specify the segment number to use as the fifth parameter to ``makeLinks()``.
-
-::
+the previous section. Specify the segment number to use as the fifth parameter to ``makeLinks()``::
 
-    <?= $pager->makeLinks($page, $perPage, $total, 'template_name', $segment) ?>
+    $pager->makeLinks($page, $perPage, $total, 'template_name', $segment);
 
 Please note: ``$segment`` value cannot be greater than the number of URI segments plus 1.
 
@@ -123,8 +122,9 @@ If you in need to show many pagers on one page then additional parameter which w
 
 Pagination library uses **page** query parameter for HTTP queries by default (if no group or ``default`` group name given) or ``page_[groupName]`` for custom group names.
 
+*************************************
 Paginating with Only Expected Queries
-=====================================
+*************************************
 
 By default, all GET queries are shown in the pagination links.
 

user_guide_src/source/libraries/pagination/015.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Controllers;
+
+use CodeIgniter\Controller;
+
+class UserController extends Controller
+{
+    public function index()
+    {
+        // ...
+
+        $pager = service('pager');
+
+        $page    = (int) ($this->request->getGet('page') ?? 1);
+        $perPage = 20;
+        $total   = 200;
+
+        // Call makeLinks() to make pagination links.
+        $pager_links = $pager->makeLinks($page, $perPage, $total);
+
+        $data = [
+            // ...
+            'pager_links' => $pager_links,
+        ];
+
+        return view('users/index', $data);
+    }
+}
+?>
+
+<!-- In your view file: -->
+<?= $pager_links ?>

user_guide_src/source/models/model.rst

@@ -34,7 +34,7 @@ CodeIgniter does provide a model class that provides a few nice features, includ
 - automatic database connection
 - basic CRUD methods
 - in-model validation
-- automatic pagination
+- :ref:`automatic pagination <paginating-with-models>`
 - and more
 
 This class provides a solid base from which to build your own models, allowing you to
@@ -116,7 +116,7 @@ The Model's CRUD methods will take a step of work away from you and automaticall
 the resulting data, instead of the Result object. This setting allows you to define
 the type of data that is returned. Valid values are '**array**' (the default), '**object**', or the **fully
 qualified name of a class** that can be used with the Result object's ``getCustomResultObject()``
-method. Using the special ``::class`` constant of the class will allow most IDEs to 
+method. Using the special ``::class`` constant of the class will allow most IDEs to
 auto-complete the name and allow functions like refactoring to better understand your code.
 
 $useSoftDeletes