Skip to main content

Easy sorting of tables with Django

Project description

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.

There are other powerful projects to sort tables such as django-tables2 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:

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:

    INSTALLED_APPS = [
        # ...
        'webstack_django_sorting',
    ]
    
  2. Check the request context processor is loaded in TEMPLATES options:

    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:

    {% 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:

    {% 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)

  5. Now, you want to display different headers with links to sort your objects_list:

    <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:

    <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:

    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:

    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.

    <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:

    {% 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).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

webstack_django_sorting-3.0.2.tar.gz (14.5 kB view details)

Uploaded Source

Built Distribution

webstack_django_sorting-3.0.2-py3-none-any.whl (9.1 kB view details)

Uploaded Python 3

File details

Details for the file webstack_django_sorting-3.0.2.tar.gz.

File metadata

File hashes

Hashes for webstack_django_sorting-3.0.2.tar.gz
Algorithm Hash digest
SHA256 5558df53dfd05ba8fb181724429d2b08aadef36ec2f7e19f9c1c62574af53a69
MD5 0274986acf6f12706d5d0d18294cbf5a
BLAKE2b-256 687609bbeb26373e6420cfd987da81c8f2399e20d5e685a518c6cc7d1ef0843f

See more details on using hashes here.

File details

Details for the file webstack_django_sorting-3.0.2-py3-none-any.whl.

File metadata

File hashes

Hashes for webstack_django_sorting-3.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 d6a1505128feb6c752b45d369e9832612f01daf8858ac57cbe74ac2a2c8c3fc9
MD5 3ca5d699e7c5a3de8ece7a4c1dec7c83
BLAKE2b-256 d30251b37e54fefbb99e511c962288d461f9478f7ec36b9f12eedfacc15534c9

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page