# Better Elided Pagination
Better Elided Pagination extends the Django Pagination class to provide elided pagination (pagination with ellipses) that does not change lengths when the selected page is near the start or end of the list. The list of pagination nodes will have a predictable and fixed length when the number of nodes exceeds the desired length of the node list.
The following illustrates the difference between Django's built in elided pagination and this project's "better" elided pagination:<br>
<img src="https://github.com/sheckathorne/django-better-elided-pagination/blob/main/screenshots/comparison.png?raw=true" width="50%" /> <br>
Compatible with Django **3.0+**
Compatible with Tailwind **1.9.6+** if using Tailwind CSS
## Installation
### PIP
This will install the latest stable release from PyPi.
```
pip install django-better-elided-pagination
```
## Usage
The complete example in the next section assumes you are using Tailwind CSS in your project. The html_list property will generate a list of HTML nodes styled using Tailwind CSS classes. If you prefer to style the pagination nodes yourself, you may simply use:
```
from better_elided_pagination.paginators import BetterElidedPaginator
def some_view(request):
items = [str(x) for x in range(1, 41)] # the items to be paginated - can be a list or queryset
pagination = BetterElidedPaginator(
request,
items,
3, # items per page
)
elided_list = pagination.get_elided_page_range()
```
.get_elided_page_range() will return a generator fuction that you can comprehend into a list, or you can loop over to view the nodes:
```
print([p for p in elided_list])
```
The generator function will return a list of tuples with the first element representing the integer page number of the node, and the second element represeting the text label of the node.
The content that is being paginated (i.e. the actual list of items to be displayed) can be viewed by using the .item_list property of the BetterElidedPaginator class:
```
# continued from the example above:
item_list = pagination.item_list
print(item_list)
```
## Example
Import the BetterElidedPaginator to the .py file constructing pagination (views.py) in this example
```
# views.py
from better_elided_pagination.paginators import BetterElidedPaginator
```
Then use the class inside a view fuction:
```
# views.py
def homepage(request):
# the items to be paginated - can be a list or queryset
items = [str(x) for x in range(1, 41)]
pagination = BetterElidedPaginator(
request,
items,
3, # items per page
)
return render(request=request,
template_name="home.html",
context={
"pagination_items": pagination.html_list,
"display_items": pagination.item_list
})
```
In this example, the pagination is in its own template using Tailwind CSS:
```
# pagination.html
<div class="flex items-center space-x-1 w-full my-2">
{% for item in pagination_items %}
{{ item }}
{% endfor %}
</div>
```
## BetterElidedPaginator - Required Positional Arguments**
- **request (Django request object)** - The request object made to the view
- **object_list (list or queryset)** - The list or queryset of objects that is being paginated
- **per_page (int)** - The number of items per page
## BetterElidedPaginator - All Optional Arguments**
- **current_page_num [default = 1]** - Override the page num typically provided by the request (not recommended)
- **pages_on_each_side [default = 2]** - The number of pagination nodes that will appear on either side of the middle node when the seleced page is near the middle of the list. A total of five middle nodes will appear by default. If set to "1", three nodes will appear in the middle (the selected node, plus on one each side).
- **pages_on_ends [default = 1]** - The number of nodes always showing next to the "next" and "prev" buttons.
- **next_and_prev_buttons [default = True]** - Boolean value for whether the next/prev buttons should be shown on the ends of the pagination element.
- **next_button [default = "»"]** - String value for the Next button. May use any string such as "Next" or an HTML icon such as Font Awesome.
- **prev_button [default = "«"]** - String value for the Previous button. May use any string such as "Previous" or an HTML icon such as Font Awesome.
- **display_item_range [default = False]** - Boolean value for whether the pagination nodes will display item range values instead of page numbers. If the pagination displays five items per page, the first button will have text: "1 - 5" and second button "6-10" instead of "1" and "2".
- **css_classes [default = (see below)]** - A dictionary which will define the Tailwind CSS classes to use when rendering the pagination elements. The default dictionary may be overriden, but none of the indices should be removed when doing so. The default dictionary is:
```
css_classes = {
"tw_base": "rounded py-2 px-4 text-center",
"tw_enabled_hover": "hover:bg-blue-100 hover:text-gray-900 hover:shadow",
"tw_enabled_text_color": "text-gray-800",
"tw_disabled": "bg-transparent text-gray-500 cursor-default focus:shadow-none",
"tw_active": "text-white bg-blue-600 shadow-xl",
"outer_div": "",
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/sheckathorne/django-better-elided-pagination",
"name": "django-better-elided-pagination",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Sean Heckathorne",
"author_email": "heckathorne.s@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ad/74/96297aea0a37a5bfc409c3a1f60ef39214d92b28f0187a6bd8ba05b998f2/django-better-elided-pagination-1.2.2.tar.gz",
"platform": null,
"description": "# Better Elided Pagination\n\nBetter Elided Pagination extends the Django Pagination class to provide elided pagination (pagination with ellipses) that does not change lengths when the selected page is near the start or end of the list. The list of pagination nodes will have a predictable and fixed length when the number of nodes exceeds the desired length of the node list.\n\nThe following illustrates the difference between Django's built in elided pagination and this project's \"better\" elided pagination:<br>\n\n<img src=\"https://github.com/sheckathorne/django-better-elided-pagination/blob/main/screenshots/comparison.png?raw=true\" width=\"50%\" /> <br>\n\nCompatible with Django **3.0+** \nCompatible with Tailwind **1.9.6+** if using Tailwind CSS \n\n## Installation\n\n### PIP\n\nThis will install the latest stable release from PyPi.\n\n```\npip install django-better-elided-pagination\n```\n\n\n## Usage\nThe complete example in the next section assumes you are using Tailwind CSS in your project. The html_list property will generate a list of HTML nodes styled using Tailwind CSS classes. If you prefer to style the pagination nodes yourself, you may simply use:\n```\nfrom better_elided_pagination.paginators import BetterElidedPaginator\n\ndef some_view(request):\n items = [str(x) for x in range(1, 41)] # the items to be paginated - can be a list or queryset\n\n pagination = BetterElidedPaginator(\n request,\n items,\n 3, # items per page\n )\n\n elided_list = pagination.get_elided_page_range()\n```\n.get_elided_page_range() will return a generator fuction that you can comprehend into a list, or you can loop over to view the nodes:\n```\nprint([p for p in elided_list])\n```\nThe generator function will return a list of tuples with the first element representing the integer page number of the node, and the second element represeting the text label of the node.\n\nThe content that is being paginated (i.e. the actual list of items to be displayed) can be viewed by using the .item_list property of the BetterElidedPaginator class:\n```\n# continued from the example above:\nitem_list = pagination.item_list\nprint(item_list)\n```\n\n\n## Example\nImport the BetterElidedPaginator to the .py file constructing pagination (views.py) in this example\n```\n# views.py\nfrom better_elided_pagination.paginators import BetterElidedPaginator\n```\n\nThen use the class inside a view fuction:\n```\n# views.py\ndef homepage(request):\n # the items to be paginated - can be a list or queryset\n items = [str(x) for x in range(1, 41)]\n\n pagination = BetterElidedPaginator(\n request,\n items,\n 3, # items per page\n )\n\n return render(request=request,\n template_name=\"home.html\",\n context={\n \"pagination_items\": pagination.html_list,\n \"display_items\": pagination.item_list\n })\n```\n\nIn this example, the pagination is in its own template using Tailwind CSS:\n```\n# pagination.html\n<div class=\"flex items-center space-x-1 w-full my-2\">\n {% for item in pagination_items %}\n {{ item }}\n {% endfor %}\n</div>\n```\n\n\n## BetterElidedPaginator - Required Positional Arguments**\n- **request (Django request object)** - The request object made to the view\n- **object_list (list or queryset)** - The list or queryset of objects that is being paginated\n- **per_page (int)** - The number of items per page\n\n\n## BetterElidedPaginator - All Optional Arguments**\n- **current_page_num [default = 1]** - Override the page num typically provided by the request (not recommended)\n- **pages_on_each_side [default = 2]** - The number of pagination nodes that will appear on either side of the middle node when the seleced page is near the middle of the list. A total of five middle nodes will appear by default. If set to \"1\", three nodes will appear in the middle (the selected node, plus on one each side).\n- **pages_on_ends [default = 1]** - The number of nodes always showing next to the \"next\" and \"prev\" buttons.\n- **next_and_prev_buttons [default = True]** - Boolean value for whether the next/prev buttons should be shown on the ends of the pagination element.\n- **next_button [default = \"»\"]** - String value for the Next button. May use any string such as \"Next\" or an HTML icon such as Font Awesome.\n- **prev_button [default = \"«\"]** - String value for the Previous button. May use any string such as \"Previous\" or an HTML icon such as Font Awesome.\n- **display_item_range [default = False]** - Boolean value for whether the pagination nodes will display item range values instead of page numbers. If the pagination displays five items per page, the first button will have text: \"1 - 5\" and second button \"6-10\" instead of \"1\" and \"2\".\n- **css_classes [default = (see below)]** - A dictionary which will define the Tailwind CSS classes to use when rendering the pagination elements. The default dictionary may be overriden, but none of the indices should be removed when doing so. The default dictionary is: \n ```\n css_classes = {\n \"tw_base\": \"rounded py-2 px-4 text-center\",\n \"tw_enabled_hover\": \"hover:bg-blue-100 hover:text-gray-900 hover:shadow\",\n \"tw_enabled_text_color\": \"text-gray-800\",\n \"tw_disabled\": \"bg-transparent text-gray-500 cursor-default focus:shadow-none\",\n \"tw_active\": \"text-white bg-blue-600 shadow-xl\",\n \"outer_div\": \"\",\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Django app to provide elided pagination that is just... better",
"version": "1.2.2",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c481757d3d2ce6979ded0470d272ebee96ec772d17cfb7d5ea2ae816b140c1c1",
"md5": "fddf62e032f7d1520951271f83abf42e",
"sha256": "166476d2d6ee6d060cfcb464cca24718f4e13d7705a26300fe768beeaab657be"
},
"downloads": -1,
"filename": "django_better_elided_pagination-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fddf62e032f7d1520951271f83abf42e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6215,
"upload_time": "2023-01-28T15:57:59",
"upload_time_iso_8601": "2023-01-28T15:57:59.356349Z",
"url": "https://files.pythonhosted.org/packages/c4/81/757d3d2ce6979ded0470d272ebee96ec772d17cfb7d5ea2ae816b140c1c1/django_better_elided_pagination-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad7496297aea0a37a5bfc409c3a1f60ef39214d92b28f0187a6bd8ba05b998f2",
"md5": "214b0e9a51762f8ee6859c5dfb0cd357",
"sha256": "548d1b7f37c73b7265c095184790210109e4c494e3ba99a68952adb691a23e23"
},
"downloads": -1,
"filename": "django-better-elided-pagination-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "214b0e9a51762f8ee6859c5dfb0cd357",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6218,
"upload_time": "2023-01-28T15:58:01",
"upload_time_iso_8601": "2023-01-28T15:58:01.573628Z",
"url": "https://files.pythonhosted.org/packages/ad/74/96297aea0a37a5bfc409c3a1f60ef39214d92b28f0187a6bd8ba05b998f2/django-better-elided-pagination-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-28 15:58:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "sheckathorne",
"github_project": "django-better-elided-pagination",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Django",
"specs": [
[
">=",
"3.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"60.2.0"
]
]
}
],
"lcname": "django-better-elided-pagination"
}
JSON
