This module helps dividing large lists of items into pages. The user is shown one page at a time and can navigate to other pages. Imagine you are offering a company phonebook and let the user search the entries. If the search result contains 23 entries but you may want to display no more than 10 entries at once. The first page contains entries 1-10, the second 11-20 and the third 21-23. See the documentation of the “Page” class for more information.
One page of items is represented by the Page object. A Page gets initalized with two parameters at least:
A simple example (ipython session):
# Set up the routes context (only if you are not using a Pylons application)
>>> from routes import Mapper; mapper=Mapper(); mapper.connect(':controller')
# Create a sample collection of 1000 items
>>> my_collection = range(1000)
# Create a Page object for the 3rd page (20 items per page is the default)
>>> my_page = Page(my_collection, page=3)
# The page object can be printed directly to get its details
>>> my_page
Page:
Collection type: <type 'list'>
(Current) page: 3
First item: 41
Last item: 60
First page: 1
Last page: 50
Previous page: 2
Next page: 4
Items per page: 20
Number of items: 1000
Number of pages: 50
<BLANKLINE>
# Print a list of items on the current page
>>> my_page.items
[40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59]
# The *Page* object can be used as an iterator:
>>> for my_item in my_page: print my_item,
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
# On a web page you will want to use a "pager" that creates links that
# the user can click on to load other pages in the set.
# [The ">>" prompt is to hide untestable examples from doctest.]
>> my_page.pager()
1 2 [3] 4 5 .. 50 (this is actually HTML)
# The pager can be customized:
>> my_page.pager('$link_previous ~3~ $link_next (Page $page of $page_count)')
1 2 [3] 4 5 6 .. 50 > (Page 3 of 50)
Please see the documentation on Page and Page.pager(). There are many parameters that customize the Page’s behavior.
Yes. See partial_param and onclick in Page.pager().
Page numbers and item numbers start at 1. This concept has been used because users expect that the first page has number 1 and the first item on a page also has number 1. So if you want to use the page’s items by their index number please note that you have to substract 1.
This module is the successor to the deprecated webhelpers.pagination module. It is NOT API compatible.
This version of paginate is based on the code from http://workaround.org/cgi-bin/hg-paginate that is known at the “Paginate” module on PyPi.
A list/iterator of items representing one page in a larger collection.
An instance of the “Page” class is created from a collection of things. The instance works as an iterator running from the first item to the last item on the given page. The collection can be:
A “Page” instance maintains pagination logic associated with each page, where it begins, what the first/last item on the page is, etc. The pager() method creates a link list allowing the user to go to other pages.
WARNING: Unless you pass in an item_count, a count will be performed on the collection every time a Page instance is created. If using an ORM, it’s advised to pass in the number of items in the collection if that number is known.
Instance attributes:
Return string with links to other pages (e.g. “1 2 [3] 4 5 6 7”).
Format string that defines how the pager is rendered. The string can contain the following $-tokens that are substituted by the string.Template module:
To render a range of pages the token ‘~3~’ can be used. The number sets the radius of pages around the current page. Example for a range with radius 3:
‘1 .. 5 6 7 [8] 9 10 11 .. 500’
Default: ‘~2~’
String to be displayed as the text for the %(link_first)s link above.
Default: ‘<<’
String to be displayed as the text for the %(link_last)s link above.
Default: ‘>>’
String to be displayed as the text for the %(link_previous)s link above.
Default: ‘<’
String to be displayed as the text for the %(link_next)s link above.
Default: ‘>’
String that is used to seperate page links/numbers in the above range of pages.
Default: ‘ ‘
When using AJAX/AJAH to do partial updates of the page area the application has to know whether a partial update (only the area to be replaced) or a full update (reloading the whole page) is required. So this parameter is the name of the URL parameter that gets set to 1 if the ‘onclick’ parameter is used. So if the user requests a new page through a Javascript action (onclick) then this parameter gets set and the application is supposed to return a partial content. And without Javascript this parameter is not set. The application thus has to check for the existance of this parameter to determine whether only a partial or a full page needs to be returned. See also the examples in this modules docstring.
Default: ‘partial’
if True the navigator will be shown even if there is only one page
Default: False
A dictionary of attributes that get added to A-HREF links pointing to other pages. Can be used to define a CSS style or class to customize the look of links.
Example: { ‘style’:’border: 1px solid green’ }
Default: { ‘class’:’pager_link’ }
A dictionary of attributes that get added to the current page number in the pager (which is obviously not a link). If this dictionary is not empty then the elements will be wrapped in a SPAN tag with the given attributes.
Example: { ‘style’:’border: 3px solid blue’ }
Default: { ‘class’:’pager_curpage’ }
A dictionary of attributes that get added to the ‘..’ string in the pager (which is obviously not a link). If this dictionary is not empty then the elements will be wrapped in a SPAN tag with the given attributes.
Example: { ‘style’:’color: #808080’ }
Default: { ‘class’:’pager_dotdot’ }
This paramter is a string containing optional Javascript code that will used as the ‘onclick’ action of each pager link. Use ‘%s’ in your string where the URL linking to the desired page will be inserted. This can be used to enhance your pager with AJAX actions loading another page into a DOM object. Note that the URL to the destination page contains a ‘partial_param’ parameter so that you can distinguish between AJAX requests (just refreshing the paginated area of your page) and full requests (loading the whole new page).
Additional keyword arguments are used as arguments in the links. Otherwise the link will be created with url_for() which points to the page you are currently displaying.