django-pure-pagination provides advanced pagination features and is fully compatible with existing code based on Django's core pagination module. (aka no need to rewrite code!)
Requirements
- Django 3.2+
- Python 3.10+
The django app offers advanced pagination features without forcing major code changes within an existing project.
Django-pure-pagination is based upon Django's core pagination module and is therefore compatible with the existing api.
Documentation for Django core pagination module
- Uses same API as django.core.pagination and therefore is fully compatible with existing code.
- Has dynamic query string creation, which takes into consideration existing GET parameters.
- Out-of-the-box html rendering of the pagination
- Additional methods make it easier to render more advanced pagination templates.
Install package from PYPI:
pip install django-pure-pagination
or clone and install from repository:
git clone git@github.com:jamespacileo/django-pure-pagination.git
cd django-pure-pagination
python setup.py install
Add pure_pagination to INSTALLED_APPS
INSTALLED_APPS = (
...
'pure_pagination',
)
Finally substitute from django.core.paginator import Paginator with from pure_pagination import Paginator
A few settings can be set within settings.py
PAGINATION_SETTINGS = {
'PAGE_RANGE_DISPLAYED': 10,
'MARGIN_PAGES_DISPLAYED': 2,
'SHOW_FIRST_PAGE_WHEN_INVALID': True,
}
PAGE_RANGE_DISPLAYED is the number of pages neighbouring the current page which will be displayed (default is 10)
MARGIN_PAGES_DISPLAYED is the number of pages neighbouring the first and last page which will be displayed (default is 2)
Set SHOW_FIRST_PAGE_WHEN_INVALID to True when you want to just show first page when provided invalid page instead of 404 error
Following is a simple example for function based views. For generic class-based views, see bellow.
view file: views.py
# views.py
from django.shortcuts import render
from pure_pagination import Paginator, EmptyPage, PageNotAnInteger
def index(request):
try:
page = request.GET.get('page', 1)
except PageNotAnInteger:
page = 1
objects = ['john', 'edward', 'josh', 'frank']
# Provide Paginator with the request object for complete querystring generation
p = Paginator(objects, request=request)
people = p.page(page)
return render('index.html', {
'people': people,
}
template file: index.html
{# index.html #}
{% extends 'base.html' %}
{% block content %}
{% for person in people.object_list %}
<div>
First name: {{ person }}
</div>
{% endfor %}
{# The following renders the pagination html #}
<div id="pagination">
{{ people.render }}
</div>
{% endblock %}
There a few different way you can make use of the features introduced within django-pure-pagination.
Easiest way to render the pagination is to call the render method i.e. {{ page.render }}
Alternatively you can access the Page object low level methods yourself
Special note: page_obj and current_page both point to the page object within the template.
{% load i18n %}
<div class="pagination">
{% if page_obj.has_previous %}
<a href="?{{ page_obj.previous_page_number.querystring }}" class="prev">‹‹ {% trans "previous" %}</a>
{% else %}
<span class="disabled prev">‹‹ {% trans "previous" %}</span>
{% endif %}
{% for page in page_obj.pages %}
{% if page %}
{% ifequal page page_obj.number %}
<span class="current page">{{ page }}</span>
{% else %}
<a href="?{{ page.querystring }}" class="page">{{ page }}</a>
{% endifequal %}
{% else %}
...
{% endif %}
{% endfor %}
{% if page_obj.has_next %}
<a href="?{{ page_obj.next_page_number.querystring }}" class="next">{% trans "next" %} ››</a>
{% else %}
<span class="disabled next">{% trans "next" %} ››</span>
{% endif %}
</div>
Documentation for Django generic class-based views on https://docs.djangoproject.com/en/dev/ref/class-based-views/
view file:
-
views.py
# views.py from django.views.generic import ListView from pure_pagination.mixins import PaginationMixin from my_app.models import MyModel class MyModelListView(PaginationMixin, ListView): # Important, this tells the ListView class we are paginating paginate_by = 10 # Replace it for your model or use the queryset attribute instead object = MyModel
template files:
Note that the Django generic-based list view will include the object page_obj in the context. More information on https://docs.djangoproject.com/en/dev/ref/generic-views/#list-detail-generic-views
-
_pagination.html
{% load i18n %} <div class="pagination"> {% if page_obj.has_previous %} <a href="?{{ page_obj.previous_page_number.querystring }}" class="prev">‹‹ {% trans "previous" %}</a> {% else %} <span class="disabled prev">‹‹ {% trans "previous" %}</span> {% endif %} {% for page in page_obj.pages %} {% if page %} {% ifequal page page_obj.number %} <span class="current page">{{ page }}</span> {% else %} <a href="?{{ page.querystring }}" class="page">{{ page }}</a> {% endifequal %} {% else %} ... {% endif %} {% endfor %} {% if page_obj.has_next %} <a href="?{{ page_obj.next_page_number.querystring }}" class="next">{% trans "next" %} ››</a> {% else %} <span class="disabled next">{% trans "next" %} ››</span> {% endif %} </div> -
my_app/myobject_list.html
{# my_app/myobject_list.html #} {% extends 'base.html' %} {% block content %} {% for object in object_list %} <div> First name: {{ object.first_name }} </div> {% endfor %} {# The following renders the pagination html #} {% include "_pagination.html" %} {% endblock %}
pip install -e .
cd example_project
python manage.py runserver
pip install -e .
cd example_project
python manage.py test pure_pagination