From a81e5d23594c7584d6ee3a6f748650bbc780e887 Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Mon, 1 May 2017 21:28:27 -0400
Subject: [PATCH] Add documentation for limitControl()

Refs cakephp/cakephp#10301
---
 en/appendices/3-5-migration-guide.rst |  3 ++
 en/views/helpers/paginator.rst        | 41 ++++++++++++++++++++-------
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/en/appendices/3-5-migration-guide.rst b/en/appendices/3-5-migration-guide.rst
index 7f8588b9c4..1beee05cfd 100644
--- a/en/appendices/3-5-migration-guide.rst
+++ b/en/appendices/3-5-migration-guide.rst
@@ -111,3 +111,6 @@ New Features
 * ``Cake\Validation\Validator::addDefaultProvider()`` was added. This method
   lets you inject validation providers into all the validators created in your
   application.
+* ``Cake\View\Helper\PaginatorHelper::limitControl()`` was added. This method
+  lets you create a form with a select box for updating the limit value on
+  a paginated result set.
diff --git a/en/views/helpers/paginator.rst b/en/views/helpers/paginator.rst
index ec9c376f02..9aa99466b4 100644
--- a/en/views/helpers/paginator.rst
+++ b/en/views/helpers/paginator.rst
@@ -396,6 +396,37 @@ There are a number of options for ``counter()``. The supported ones are:
   :php:meth:`PaginatorHelper::defaultModel()`. This is used in
   conjunction with the custom string on 'format' option.
 
+Generating Pagination URLs
+==========================
+
+.. php:method:: generateUrl(array $options = [], $model = null, $full = false)
+
+By default returns a full pagination URL string for use in non-standard contexts
+(i.e. JavaScript). ::
+
+    echo $this->Paginator->generateUrl(['sort' => 'title']);
+
+Creating a Limit Selectbox Control
+==================================
+
+.. php:method:: limitControl(array $limits = [], $default = null, array $options = [])
+
+Create a dropdown control that changes the ``limit`` query parameter::
+
+    // Use the defaults.
+    echo $this->Paginator->limitControl();
+
+    // Define which limit options you want.
+    echo $this->Paginator->limitControl([25 => 25, 50 => 50]);
+
+    // Custom limits and set the selected option
+    echo $this->Paginator->limitControl([25 => 25, 50 => 50], $user->perPage);
+
+The generated form and control will automatically submit on change.
+
+.. versionadded:: 3.5.0
+    The ``limitControl()`` method was added in 3.5.0
+
 Configuring Pagination Options
 ==============================
 
@@ -504,16 +535,6 @@ markers::
                  {{count}} total, starting on record {{start}}, ending on {{end}}'
     ]) ?>
 
-Generating Pagination URLs
-==========================
-
-.. php:method:: generateUrl(array $options = [], $model = null, $full = false)
-
-By default returns a full pagination URL string for use in non-standard contexts
-(i.e. JavaScript). ::
-
-    echo $this->Paginator->generateUrl(['sort' => 'title']);
-
 .. _paginator-helper-multiple:
 
 Paginating Multiple Results