|
1 | 1 | django-pagination-py3 |
2 | | -===================== |
| 2 | +==================== |
3 | 3 |
|
4 | | -A port of django-pagination to Python 3, also compatible with Python 2.x ;) |
| 4 | + [](https://pypi.python.org/pypi/django-pagination-py3)  [](https://codecov.io/gh/matagus/django-pagination-py3) [](https://opensource.org/licenses/BSD-3-Clause) |
| 5 | + |
| 6 | +A port of [ericflo/django-pagination](https://github.com/ericflo/django-pagination) to Python 3. Updated to be compatible with Django 4.x and 5.0. |
| 7 | + |
| 8 | +For versions compatible with Django 3.x and Python 2.7+ please install or download version `1.2.0` from [Releases](https://github.com/matagus/django-pagination-py3/releases) or |
| 9 | +[Pypi](https://pypi.org/project/django-pagination-py3/). |
| 10 | + |
| 11 | +Features |
| 12 | +======== |
| 13 | + |
| 14 | +- Really easy to use at template level. |
| 15 | +- It preserves all request's querystring parameters. |
| 16 | +- Settings to customize behavior. |
| 17 | +- Translated to fr, de, es, pt, pl and pt_BR. |
| 18 | +- A fully working example project. |
5 | 19 |
|
6 | 20 |
|
7 | 21 | Installation |
8 | | ------------- |
| 22 | +============ |
| 23 | + |
| 24 | +Install using `pip` command: |
| 25 | + |
| 26 | +```bash |
| 27 | +pip install django-pagination-py3 |
| 28 | +``` |
| 29 | + |
| 30 | +...or clone the repo and install it using `pip`: |
| 31 | + |
| 32 | +```bash |
| 33 | +git clone git://github.com/matagus/django-pagination-py3.git |
| 34 | +cd django-pagination-py3 |
| 35 | +pip install -e . |
| 36 | +``` |
| 37 | + |
| 38 | +Add `pagination` INSTALLED_APPS to your `settings.py`: |
| 39 | + |
| 40 | +```python |
| 41 | +INSTALLED_APPS = ( |
| 42 | + # ... |
| 43 | + "pagination", |
| 44 | +) |
| 45 | +``` |
| 46 | + |
| 47 | +Add the middleware: |
| 48 | + |
| 49 | +```python |
| 50 | + MIDDLEWARE_CLASSES = ( |
| 51 | + # ... |
| 52 | + 'pagination.middleware.PaginationMiddleware', |
| 53 | + ) |
| 54 | +``` |
| 55 | + |
| 56 | +Add this line at the top of your template to load the pagination tags: |
| 57 | + |
| 58 | +```html |
| 59 | + {% load pagination_tags %} |
| 60 | +``` |
| 61 | + |
| 62 | +Decide on a variable that you would like to paginate, and use the autopaginate tag on that variable before iterating |
| 63 | +over it. This could take one of two forms (using the canonical `object_list` as an example variable): |
| 64 | + |
| 65 | +```html |
| 66 | + {% autopaginate object_list %} |
| 67 | +``` |
| 68 | + |
| 69 | +This assumes that you would like to have the default 20 results per page. If you would like to specify your own amount |
| 70 | +of results per page, you can specify that like so: |
| 71 | + |
| 72 | +```html |
| 73 | + {% autopaginate object_list 10 %} |
| 74 | +``` |
| 75 | + |
| 76 | +Note that this replaces ``object_list`` with the list for the current page, so you can iterate over the `object_list` |
| 77 | +like you normally would. |
| 78 | + |
| 79 | + |
| 80 | +Now you want to display the current page and the available pages, so somewhere after having used autopaginate, use the |
| 81 | +paginate inclusion tag: |
| 82 | + |
| 83 | +```html |
| 84 | + {% paginate %} |
| 85 | +``` |
| 86 | + |
| 87 | +This does not take any arguments, but does assume that you have already called autopaginate, so make sure to do so first. |
| 88 | + |
| 89 | + |
| 90 | +That's it! You have now paginated `object_list` and given users of the site a way to navigate between the different |
| 91 | +pages--all without touching your views. |
| 92 | + |
| 93 | + |
| 94 | +Running Tests |
| 95 | +------------- |
| 96 | + |
| 97 | +`hatch run test:test` will run the tests in every Python + Django versions combination. |
| 98 | + |
| 99 | +`hatch run test.py3.12-5.0:test`: will run them for python 3.12 and Django 5.0. Please see possible combinations using |
| 100 | +`hatch env show` ("test" matrix). |
| 101 | + |
9 | 102 |
|
10 | | -Install it from pypi.python.org: |
| 103 | +License |
| 104 | +======= |
11 | 105 |
|
12 | | - pip install django-pagination-py3 |
| 106 | +`django-pagination-py3` is released under an BSD License - see the `LICENSE` file for more information. |
13 | 107 |
|
14 | | -or just clone this repository and run: |
15 | 108 |
|
16 | | - python setup.py install |
| 109 | +Acknowledgements |
| 110 | +================ |
17 | 111 |
|
| 112 | +Develop & built using [](https://github.com/pypa/hatch) [](https://github.com/astral-sh/ruff) [](https://github.com/psf/black) |
18 | 113 |
|
19 | | -Usage |
20 | | ------ |
| 114 | +Posts I learned from: |
21 | 115 |
|
22 | | -Use it the same way you use django-pagination. |
| 116 | +- [Switching to Hatch](https://andrich.me/2023/08/switching-to-hatch/) |
| 117 | +- [Automate Hatch Publish with GitHub Actions](https://blog.pecar.me/automate-hatch-publish) |
0 commit comments