From e3815e78a82ba3abc12fc0daf61cb910186025ec Mon Sep 17 00:00:00 2001
From: =?utf8?q?Sven=20Sch=C3=B6ling?= <s.schoeling@linet-services.de>
Date: Fri, 23 Nov 2012 12:47:52 +0100
Subject: [PATCH] =?utf8?q?Bessere=20Doku=20f=C3=BCr=20das=20Zwischenformat?=
 =?utf8?q?=20des=20Paginated=20Helpers?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

---
 SL/DB/Helper/Paginated.pm | 48 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/SL/DB/Helper/Paginated.pm b/SL/DB/Helper/Paginated.pm
index 27daffedd..07e5b5e9c 100644
--- a/SL/DB/Helper/Paginated.pm
+++ b/SL/DB/Helper/Paginated.pm
@@ -114,7 +114,7 @@ In the template:
 
 Paginate will prepare information to be used for paginating, change the given
 args to use them, and return a data structure containing information for later
-display.
+display. See L<STRUCTURE OF PAGES> for information how the return is formatted.
 
 C<args> needs to contain a reference to a hash, which will be used as an
 argument for C<get_all>. After C<paginate> the keys C<page> and C<per_page>
@@ -129,6 +129,52 @@ Manager will be used.
 
 =back
 
+=head1 STRUCTURE OF PAGES
+
+The returned hashref will have the following structure:
+
+  { per_page => 20,   # how many entries per page
+    max      => 5,    # number of the last page
+    cur      => 2,    # number of the current page
+    common   => [     # an array of hashes for each page
+      ...,
+      { active  => 1, # set if this is the active page
+        page    => 2, # the string to display for this page
+        visible => 1, # should this be displayed in the paginating controls
+      },
+      ...
+    ]
+  }
+
+You may assume that C<cur> is sanitized to be within 1..C<max>.
+
+The common list is kept arbitrary by design, so that the algorithm to display
+the paginating controls can be changed by solely changing the
+C<make_common_pages> algorithm. If you need different glyphs for the pages or
+different boundaries, translate the C<page> entry for the page.
+
+The initial algorithm will show the following pages:
+
+=over 4
+
+=item *
+
+1, 2, 3
+
+=item *
+
+Last page
+
+=item *
+
+Current page +/- 5 pages
+
+=item *
+
+Current page +/- 10, 50, 100, 500, 1000, 5000
+
+=back
+
 =head1 TEMPLATE HELPERS
 
 =over 4
-- 
2.20.1