# webstack-django-sorting
## What?
`webstack-django-sorting` is a Django app which allows for easy sorting of
data tables. You don't need to change anything to your views to use it. It
provides sorting links for table headers. It is the perfect companion of
[django-pagination](https://github.com/zyga/django-pagination).
There are other powerful projects to sort tables such as
[django-tables2](https://django-tables2.readthedocs.io/) but I don't like the
high level `render_table` tag because it requires to define the CSS in
`Table` classes or to write custom templates.
A demonstration of the features is provided in `testproj` directory. The file
`testproj/README.md` provides information on how to use it.
## Features
- Django or Jinja2 templates
- Django ORM or Python sorting
- Switches between ascending, descending, and no sorting
- Provides links to sort on different criterions
- Visual feedback on applied ordering
- Supports 3.6+
- Supports translation of link titles
To upgrade to `webstack-django-sorting` v1.0.0+, you must remove the old middleware
`webstack_django_sorting.middleware.SortingMiddleware` from `MIDDLEWARE_CLASSES` list.
## How to use it in your project
The provide is available on PyPI:
```shell
pip install webstack_django_sorting
```
The project provides examples of integration with Django and Jinja2 templates.
## For Django templates
1. Add the application to the `INSTALLED_APPS` list:
```python
INSTALLED_APPS = [
# ...
'webstack_django_sorting',
]
```
2. Check the request context processor is loaded in `TEMPLATES` options:
```python
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
# ...
'django.template.context_processors.request',
# ...
],
},
},
]
```
3. Add this line at the top of your template to load the sorting tags:
```html
{% load sorting_tags %}
```
4. Decide on a variable that you would like to sort, and use the
autosort tag on that variable before iterating over it:
```html
{% autosort object_list %}
```
You can pass the option `nulls=first` (or `nulls=last`) to explicitly define
the ordering of NULL (not supported by all databases,
[Indexing ASC, DESC and NULLS FIRST/LAST](https://use-the-index-luke.com/sql/sorting-grouping/order-by-asc-desc-nulls-last))
5. Now, you want to display different headers with links to sort
your objects_list:
```html
<tr>
<th>{% anchor first_name _("Name") %}</th>
<th>{% anchor creation_date _("Creation") %}</th>
</tr>
```
The first argument is a field or an attribute of the objects list, and the
second one (optional) is a title that would be displayed. The previous
snippet will be rendered like this in French:
```html
<tr>
<th><a href="/path/to/your/view/?sort=first_name" title="Nom">Nom</a></th>
<th><a href="/path/to/your/view/?sort=creation_date" title="Création">Création</a></th>
</tr>
```
An optional 3rd argument allows you to sort first by descending
(e.g. show most recent dates first) `{% anchor some_date _("Date") desc %}`
If your application doesn't support internationalization, you can use a
simple `{% anchor first_name Name %}`.
## For Jinja2 templates
1. Define the environment in the `TEMPLATES` options:
```python
TEMPLATES = {
{
"BACKEND": "django.template.backends.jinja2.Jinja2",
"DIRS": [],
"APP_DIRS": True,
"OPTIONS": {
"environment": "testproj.testapp.jinja2.env.JinjaEnvironment",
},
},
]
````
2. Your environment file should add `sorting_anchor` and `sort_queryset` to globals:
```python
from jinja2.environment import Environment
from webstack_django_sorting.jinja2_globals import sorting_anchor, sort_queryset
class JinjaEnvironment(Environment):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.globals["sorting_anchor"] = sorting_anchor
self.globals["sort_queryset"] = sort_queryset
```
3. Now, you can generate header links to sort your queryset.
```html
<tr>
<th>{{ sorting_anchor(request, "created_on", "Date") }}</th>
<!--...-->
<tr>
```
4. The queryset should be wrapped with `sort_queryset` to use the GET request arguments for sorting:
```html
{% for secret_file in sort_queryset(request, secret_files) %}
<!--...-->
{% endfor %}
```
That's it!
## Settings
The library provides a few settings that you can define in the Django settings of your project:
- `DEFAULT_SORT_UP`, the HTML character to display the up symbol in the column headers (' ↑' by default).
- `DEFAULT_SORT_DOWN`, the HTML character to display the down symbol in the column headers (' ↓' by default).
- `SORTING_INVALID_FIELD_RAISES_404`, if true, a 404 response will be returned on invalid use of query parameters (false by default).
Raw data
{
"_id": null,
"home_page": null,
"name": "webstack-django-sorting",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "St\u00e9phane Raimbault <stephane.raimbault@webstack.fr>",
"keywords": "django, sorting, table",
"author": null,
"author_email": "\"Karim A. (aka Directeur)\" <directeur@gmail.com>, Eric Florenzano <floguy@gmail.com>, St\u00e9phane Raimbault <stephane.raimbault@webstack.fr>, \"S. Kossouho\" <artscoop93@gmail.com>, \"Joffrey M.\" <joffrey.mander@polyconseil.fr>",
"download_url": "https://files.pythonhosted.org/packages/68/76/09bbeb26373e6420cfd987da81c8f2399e20d5e685a518c6cc7d1ef0843f/webstack_django_sorting-3.0.2.tar.gz",
"platform": null,
"description": "# webstack-django-sorting\n\n## What?\n\n`webstack-django-sorting` is a Django app which allows for easy sorting of\ndata tables. You don't need to change anything to your views to use it. It\nprovides sorting links for table headers. It is the perfect companion of\n[django-pagination](https://github.com/zyga/django-pagination).\n\nThere are other powerful projects to sort tables such as\n[django-tables2](https://django-tables2.readthedocs.io/) but I don't like the\nhigh level `render_table` tag because it requires to define the CSS in\n`Table` classes or to write custom templates.\n\nA demonstration of the features is provided in `testproj` directory. The file\n`testproj/README.md` provides information on how to use it.\n\n## Features\n\n- Django or Jinja2 templates\n- Django ORM or Python sorting\n- Switches between ascending, descending, and no sorting\n- Provides links to sort on different criterions\n- Visual feedback on applied ordering\n- Supports 3.6+\n- Supports translation of link titles\n\nTo upgrade to `webstack-django-sorting` v1.0.0+, you must remove the old middleware\n`webstack_django_sorting.middleware.SortingMiddleware` from `MIDDLEWARE_CLASSES` list.\n\n## How to use it in your project\n\nThe provide is available on PyPI:\n\n```shell\npip install webstack_django_sorting\n```\n\nThe project provides examples of integration with Django and Jinja2 templates.\n\n## For Django templates\n\n1. Add the application to the `INSTALLED_APPS` list:\n\n ```python\n INSTALLED_APPS = [\n # ...\n 'webstack_django_sorting',\n ]\n ```\n\n2. Check the request context processor is loaded in `TEMPLATES` options:\n\n ```python\n TEMPLATES = [\n {\n 'BACKEND': 'django.template.backends.django.DjangoTemplates',\n 'DIRS': [],\n 'APP_DIRS': True,\n 'OPTIONS': {\n 'context_processors': [\n # ...\n 'django.template.context_processors.request',\n # ...\n ],\n },\n },\n ]\n ```\n\n3. Add this line at the top of your template to load the sorting tags:\n\n ```html\n {% load sorting_tags %}\n ```\n\n4. Decide on a variable that you would like to sort, and use the\n autosort tag on that variable before iterating over it:\n\n ```html\n {% autosort object_list %}\n ```\n\n You can pass the option `nulls=first` (or `nulls=last`) to explicitly define\n the ordering of NULL (not supported by all databases,\n [Indexing ASC, DESC and NULLS FIRST/LAST](https://use-the-index-luke.com/sql/sorting-grouping/order-by-asc-desc-nulls-last))\n\n5. Now, you want to display different headers with links to sort\n your objects_list:\n\n ```html\n <tr>\n <th>{% anchor first_name _(\"Name\") %}</th>\n <th>{% anchor creation_date _(\"Creation\") %}</th>\n </tr>\n ```\n\n The first argument is a field or an attribute of the objects list, and the\n second one (optional) is a title that would be displayed. The previous\n snippet will be rendered like this in French:\n\n ```html\n <tr>\n <th><a href=\"/path/to/your/view/?sort=first_name\" title=\"Nom\">Nom</a></th>\n <th><a href=\"/path/to/your/view/?sort=creation_date\" title=\"Cr\u00e9ation\">Cr\u00e9ation</a></th>\n </tr>\n ```\n\n An optional 3rd argument allows you to sort first by descending\n (e.g. show most recent dates first) `{% anchor some_date _(\"Date\") desc %}`\n\n If your application doesn't support internationalization, you can use a\n simple `{% anchor first_name Name %}`.\n\n## For Jinja2 templates\n\n1. Define the environment in the `TEMPLATES` options:\n\n ```python\n TEMPLATES = {\n {\n \"BACKEND\": \"django.template.backends.jinja2.Jinja2\",\n \"DIRS\": [],\n \"APP_DIRS\": True,\n \"OPTIONS\": {\n \"environment\": \"testproj.testapp.jinja2.env.JinjaEnvironment\",\n },\n },\n ]\n ````\n\n2. Your environment file should add `sorting_anchor` and `sort_queryset` to globals:\n\n ```python\n from jinja2.environment import Environment\n from webstack_django_sorting.jinja2_globals import sorting_anchor, sort_queryset\n\n class JinjaEnvironment(Environment):\n def __init__(self, **kwargs):\n super().__init__(**kwargs)\n self.globals[\"sorting_anchor\"] = sorting_anchor\n self.globals[\"sort_queryset\"] = sort_queryset\n ```\n\n3. Now, you can generate header links to sort your queryset.\n\n ```html\n <tr>\n <th>{{ sorting_anchor(request, \"created_on\", \"Date\") }}</th>\n <!--...-->\n <tr>\n ```\n\n4. The queryset should be wrapped with `sort_queryset` to use the GET request arguments for sorting:\n\n ```html\n {% for secret_file in sort_queryset(request, secret_files) %}\n <!--...-->\n {% endfor %}\n ```\n\nThat's it!\n\n## Settings\n\nThe library provides a few settings that you can define in the Django settings of your project:\n\n- `DEFAULT_SORT_UP`, the HTML character to display the up symbol in the column headers (' ↑' by default).\n- `DEFAULT_SORT_DOWN`, the HTML character to display the down symbol in the column headers (' ↓' by default).\n- `SORTING_INVALID_FIELD_RAISES_404`, if true, a 404 response will be returned on invalid use of query parameters (false by default).\n",
"bugtrack_url": null,
"license": null,
"summary": "Easy sorting of tables with Django",
"version": "3.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/webstack/webstack-django-sorting/issues",
"changelog": "https://github.com/webstack/webstack-django-sorting/blob/master/CHANGELOG.md",
"repository": "https://github.com/webstack/webstack-django-sorting.git"
},
"split_keywords": [
"django",
" sorting",
" table"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d30251b37e54fefbb99e511c962288d461f9478f7ec36b9f12eedfacc15534c9",
"md5": "3ca5d699e7c5a3de8ece7a4c1dec7c83",
"sha256": "d6a1505128feb6c752b45d369e9832612f01daf8858ac57cbe74ac2a2c8c3fc9"
},
"downloads": -1,
"filename": "webstack_django_sorting-3.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ca5d699e7c5a3de8ece7a4c1dec7c83",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 9098,
"upload_time": "2024-10-10T13:06:29",
"upload_time_iso_8601": "2024-10-10T13:06:29.400048Z",
"url": "https://files.pythonhosted.org/packages/d3/02/51b37e54fefbb99e511c962288d461f9478f7ec36b9f12eedfacc15534c9/webstack_django_sorting-3.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "687609bbeb26373e6420cfd987da81c8f2399e20d5e685a518c6cc7d1ef0843f",
"md5": "0274986acf6f12706d5d0d18294cbf5a",
"sha256": "5558df53dfd05ba8fb181724429d2b08aadef36ec2f7e19f9c1c62574af53a69"
},
"downloads": -1,
"filename": "webstack_django_sorting-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "0274986acf6f12706d5d0d18294cbf5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 14478,
"upload_time": "2024-10-10T13:06:30",
"upload_time_iso_8601": "2024-10-10T13:06:30.346905Z",
"url": "https://files.pythonhosted.org/packages/68/76/09bbeb26373e6420cfd987da81c8f2399e20d5e685a518c6cc7d1ef0843f/webstack_django_sorting-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 13:06:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "webstack",
"github_project": "webstack-django-sorting",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "webstack-django-sorting"
}
JSON
