• Home

« When Django Apps Grow Up | Home | Constructive reasons to use Django instead of Rails (Proxied) »

Auto Adjusting Pagination As A Template Tag Plus Include

By Paul Kenjora | December 16, 2007

This post has been updated, the source code is available for download on Digg Style Pagination In Django Revisited.

Django has made me really lazy. I never in my wildest dreams imagined I’d be wanting something simpler than the pagination already built into Django, but it has happened. On several projects now I’ve run into an issue of too many pages to dsiplay to the user. Once you get over twenty or so pages the links start to look way messy. So I decided to write a function that would create nice sliding page ranges for the user. A bit like Digg.com does. That worked except I was frustrated that the the layout and templating of each set of links was difficult to synch up from the back end. So I eventually ended up creating a template tag I can include in my pages and quickly create pagination.

What Does Auto Adjusting Mean?

I’ve labeled the pagination tag "auto adjusting" because it is designed to give up to three easily readable ranges of pages for the user to click. Range one will always be page one through some configurable number (more on this later). Range two appears only if enough pages exist and the current page is far enough out, it shows a subset of pages in the neighborhood of the current page. Range three appears only if there are enough pages and shows the last few pages, also configurable. The three ranges are automatically created if required to ensure the user can easily navigate through large page numbers. For details on how to configure the ranges see the "Using The Pagination Template Tag" section at the bottom.

The Source

The code consists of a template tag and an HTML file. The template tag sets up thge page ranges and does all the math. The HTML file allows me to quickly customize the look and feel of the page links for any given site. I’ve also thrown in a sample CSS file for reference on formatting the look and feel of the links.

Source Download

Using The Pagination Template Tag

Making this part as simple and straight forward as possible was my main goal. To use the new tag simply load it, call the paginate function on any list, specify page number, entries per page, and the name of the resulting list. Once the call is made you can use the new list and include the "pagination.html" file to get a cool sliding set of pagination links. Dont forget to apply the style sheets.

For reference as the sample below illustrates the API for the pagination tag is:

{% paginate [query set to be paginated] [current page] [items per page] [length of page groups] [new paginated list] %}

• query set to be paginated – same as what gets passed into the standard Django paginator
• current page – your application should still maintain a mechanism for passing the current page around
• items per page – an integer representing the length of each page
• length of page groups – page links are broken down into groups, the size of the groups is given here
• new paginated list – the name of the variable that will store the resulting pagination query

Source Download

Conclusion

Dont worry about all the code under the hood. You only need to copy and paste each of the sample files and you’re ready to go, this works for any model type. The HTML and CSS files are yours to modify, the template tag code requires no modification. Now you can paginate any page on your Django site with a smart sliding set of page links in just 3 lines of code. If you’re worried about efficiency don’t be, Django queries are lazy, and the template tag only does one DB hit to fetch a count. Yes I could have used the native paginator for some of the math but it would have been overkill. Hope this is handy.

More from Aware Labs

• Digg Style Pagination In Django Revisited
• Everything A Django Developer Needs To Create Logins
• Custom Actions In Django Admin Object Editor
• Another IfModulo Template Tag Or If Else End Tutorial
• Digg For Django Is Here

Aware Labs Recommends

• An Interview with Jacob Kaplan-Moss – Creator of Django (USwaretech)
• An interview with Michael Trier (USwaretech)
• An interview with Russell Keith-Magee – Django core contributor (USwaretech)

Topics: Template Tags | Comments