Changes between Version 7 and Version 8 of HelperFunctions

Timestamp:

Sep 4, 2006, 5:18:38 PM (17 years ago)

Author:

cmlenz

Comment:

Add simple paginator example

HelperFunctions

@@ -105 +105 @@
 }}}
 
+== paginate() ==
+
+A basic pagination routine written by [http://www.cmlenz.net/ Christopher Lenz].
+
+{{{
+#!python
+from math import ceil
+
+def paginate(items, page=0, max_per_page=10):
+    """Simple generic pagination.
+    
+    Given an iterable, this function returns:
+     * the slice of objects on the requested page,
+     * the total number of items, and
+     * the total number of pages.
+    
+    The `items` parameter can be a list, tuple, or iterator:
+    
+    >>> items = range(12)
+    >>> items
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+    >>> paginate(items)
+    ([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 12, 2)
+    >>> paginate(items, page=1)
+    ([10, 11], 12, 2)
+    >>> paginate(iter(items))
+    ([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 12, 2)
+    >>> paginate(iter(items), page=1)
+    ([10, 11], 12, 2)
+    
+    This function also works with generators:
+    
+    >>> def generate():
+    ...     for idx in range(12):
+    ...         yield idx
+    >>> paginate(generate())
+    ([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 12, 2)
+    >>> paginate(generate(), page=1)
+    ([10, 11], 12, 2)
+    
+    The `max_per_page` parameter can be used to set the number of items that
+    should be displayed per page:
+    
+    >>> items = range(12)
+    >>> paginate(items, page=0, max_per_page=6)
+    ([0, 1, 2, 3, 4, 5], 12, 2)
+    >>> paginate(items, page=1, max_per_page=6)
+    ([6, 7, 8, 9, 10, 11], 12, 2)
+    """
+    if not page:
+        page = 0
+    start = page * max_per_page
+    stop = start + max_per_page
+
+    count = None
+    if hasattr(items, '__len__'):
+        count = len(items)
+
+    try: # Try slicing first for better performance
+        retval = items[start:stop]
+    except TypeError: # Slicing not supported, so iterate through the whole list
+        retval = []
+        for idx, item in enumerate(items):
+            if start <= idx < stop:
+                retval.append(item)
+            # If we already obtained the total number of items via `len()`,
+            # we can break out of the loop as soon as we've got the last item
+            # for the requested page
+            if count is not None and idx >= stop:
+                break
+        if count is None:
+            count = idx + 1
+
+    return retval, count, int(ceil(float(count) / max_per_page))
+}}}
+
+=== Example usage ===
+
+{{{
+#!xml
+<div py:with="items, num_items, num_pages = paginate(range(1, 24), cur_page - 1)">
+  <h1>Page ${cur_page} of ${num_pages}</h1>
+  <ul><li py:for="item in items">${item}</li></ul>
+  <hr />
+  <py:for="num in range(cur_page, num_pages + 1)">
+    <a href="?page=$num">$num</a>
+  </py:for>
+</div>
+}}}
+
+That should result in the following output:
+
+{{{
+#!xml
+<div>
+  <h1>Page 1 of 3</h1>
+  <ul><li>1</li><li>2</li><li>3</li><li>4</li><li>5</li><li>6</li><li>7</li><li>8</li><li>9</li><li>10</li></ul>
+  <hr />
+  <a href="?page=1">1</a>
+  <a href="?page=2">2</a>
+  <a href="?page=3">3</a>
+</div>
+}}}
+
 == countoccurrences() / countdistinct() ==