Seamless integration between Django REST framework and Datatables (https://datatables.net)

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for izi from gravatar.com izi

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers

Project description

django-rest-framework-datatables

Travis build codecov-image Documentation Status Pypi version Python versions

Overview

This package provides seamless integration between Django REST framework and Datatables.

Install django-rest-framework-datatables, call your API with ?format=datatables and it will return a JSON structure that is fully compatible with what Datatables expects. It handles searching, filtering, ordering and most usecases you can imagine with Datatables.

The great benefit of django-rest-framework-datatables is that you don’t have to create a different API, your API still work exactly the same unless you specify the datatables format on your request.

Full documentation is available on Read the Docs !

You can play with a demo of the example app on Python Anywhere.

Requirements

  • Python (3.8, 3.9, 3.10, 3.11, 3.12)

  • Django (3.2, 4.1, 4.2)

  • Django REST Framework (3.14)

We highly recommend and only officially support the latest patch release of each Python, Django and Django Rest Framework series.

Quickstart

Installation

Just use pip:

$ pip install djangorestframework-datatables

Configuration

To enable Datatables support in your project, add 'rest_framework_datatables' to your INSTALLED_APPS, and modify your REST_FRAMEWORK settings like this:

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
        'rest_framework_datatables.renderers.DatatablesRenderer',
    ),
    'DEFAULT_FILTER_BACKENDS': (
        'rest_framework_datatables.filters.DatatablesFilterBackend',
    ),
    'DEFAULT_PAGINATION_CLASS': 'rest_framework_datatables.pagination.DatatablesPageNumberPagination',
    'PAGE_SIZE': 50,
}

And that’s it !

Your API is now fully compatible with Datatables and will provide searching, filtering, ordering and pagination without any modification of your API code !

Always Serialize Specific Fields

Sometimes you may want to expose fields regardless of datatable’s url parameters. You can do so by setting the datatables_always_serialize tuple like so:

class ArtistSerializer(serializers.ModelSerializer):
    id = serializers.IntegerField(read_only=True)

    class Meta:
        model = Artist
        fields = (
            'id', 'name',
        )
        datatables_always_serialize = ('id',)

An example of Datatable

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Rolling Stone Top 500 albums of all time</title>
  <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.0.0/css/bootstrap.css">
  <link rel="stylesheet" href="//cdn.datatables.net/1.10.16/css/dataTables.bootstrap4.min.css">
</head>

<body>
  <div class="container">
    <div class="row">
      <div class="col-sm-12">
        <table id="albums" class="table table-striped table-bordered" style="width:100%">
          <thead>
            <tr>
              <th>Rank</th>
              <th>Artist</th>
              <th>Album name</th>
              <th>Year</th>
              <th>Genres</th>
            </tr>
          </thead>
        </table>
      </div>
    </div>
  </div>
  <script src="//code.jquery.com/jquery-1.12.4.js"></script>
  <script src="//cdn.datatables.net/1.10.16/js/jquery.dataTables.min.js"></script>
  <script src="//cdn.datatables.net/1.10.16/js/dataTables.bootstrap4.min.js"></script>
  <script>
      $(document).ready(function() {
          var table = $('#albums').DataTable({
              "serverSide": true,
              "ajax": "/api/albums/?format=datatables",
              "columns": [
                  {"data": "rank", "searchable": false},
                  {"data": "artist_name", "name": "artist.name"},
                  {"data": "name"},
                  {"data": "year"},
                  {"data": "genres", "name": "genres.name", "sortable": false},
              ]
          });
      });
  </script>
</body>
</html>

Example project

To play with the example project, just clone the repository and run the dev server.

$ git clone https://github.com/izimobil/django-rest-framework-datatables.git
$ cd django-rest-framework-datatables
$ pip install -r requirements-dev.txt
$ python example/manage.py runserver
$ firefox http://127.0.0.1:8000

Testing

Install development requirements.

$ pip install -r requirements-dev.txt

Run the tests.

$ python example/manage.py test

You can also use the excellent tox testing tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:

$ tox

If you want to check the coverage, use:

$ coverage run ./example/manage.py test
$ coverage report -m

Documentation

The documentation is available online on Read the Docs.

To build the documentation, you’ll need to install sphinx.

$ pip install -r requirements-docs.txt

To build the documentation:

$ cd docs
$ make clean && make html

Changelog

Version 0.7.2 (2024-06-14):

  • Django 5.0 and 5.1 support

  • Allow overriding queryset.count() with two additional methods

Many thanks to all the contributors on this release !

Version 0.7.1 (2024-03-06):

  • Django 4.2 support

  • Dependencies versions updates

  • Fixed deprecation warnings on tests

Many thanks to all the contributors on this release !

Version 0.7.0 (2021-12-09):

  • Django 4.0 compatibility

  • Added global search support to YADCFModelMultipleChoiceFilter

  • Various fixes on filters

  • Various fixes on pagination

  • Fixed / improved documentation and examples

Many thanks to all the contributors on this release !

Version 0.6.0 (2021-02-09):

  • Integration with django-filter

  • Example of using yadcf and django-filter to create a multi-select column

  • Fixed support for POST requests from datatables

  • Some fixes on pagination

Many thanks to all the contributors on this release !

Version 0.5.2 (2020-04-10):

  • Added support for POST requests from datatables

  • Avoid extra count queries

  • Handle dummy columns gracefully

Version 0.5.1 (2020-01-13):

  • Added support for Django 3.0

  • Added support for disabling pagination when the client requests it with length=-1 parameter

  • Added optional column sorting to handle ties

  • Minor code fixes

Version 0.5.0 (2019-03-31):

  • Fixed total number of rows when view is using multiple filter back-ends

  • New meta option datatables_extra_json on view for adding key/value pairs to rendered JSON

  • Minor docs fixes

Version 0.4.1 (2018-11-16):

  • Added support for Django 2.1 and DRF 3.9

  • Updated README

Version 0.4.0 (2018-06-22):

  • Added top level filtering for nested serializers

  • Added multiple field filtering

  • Added a ?keep= parameter that allows to bypass the filtering of unused fields

  • Better detection of the requested format

  • Fixed typo in Queryset.count() method name

Version 0.3.0 (2018-05-11):

  • Added a serializer Meta option datatables_always_serialize that allows to specify a tuple of fields that should always be serialized in the response, regardless of what fields are requested in the Datatables request

  • Optimize filters

  • Use AND operator for column filtering instead of OR, to be consistant with the client-side behavior of Datatables

Version 0.2.1 (2018-04-11):

  • This version replaces the 0.2.0 who was broken (bad setup.py)

Version 0.2.0 (2018-04-11):

  • Added full documentation

  • Removed serializers, they are no longer necessary, filtering of columns is made by the renderer

Version 0.1.0 (2018-04-10):

Initial release.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for izi from gravatar.com izi

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers

Release history Release notifications | RSS feed

This version

0.7.2

0.7.1

0.7.0

0.6.0

0.5.2

0.5.1

0.5.0

0.4.1

0.4.0

0.3.0

0.2.1

0.2.0

0.1.0

Download files

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

Source Distribution

djangorestframework_datatables-0.7.2.tar.gz (19.6 kB view details)

Uploaded Source

Built Distribution

djangorestframework_datatables-0.7.2-py2.py3-none-any.whl (15.3 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file djangorestframework_datatables-0.7.2.tar.gz.

File metadata

File hashes

Hashes for djangorestframework_datatables-0.7.2.tar.gz
Algorithm Hash digest
SHA256 d7953968088ceb14968621a0c0a83d2f39ec1cda24b5ebe1240f3c9619bc7129
MD5 253bfd891e74f98b1fd4b580066a362f
BLAKE2b-256 c7a07481fee713387fd5c632b05c1d95c32f5b2ea6e1e8f15c9cf1894e1895a8

See more details on using hashes here.

File details

Details for the file djangorestframework_datatables-0.7.2-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for djangorestframework_datatables-0.7.2-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 fd5747b1e3d0bfb84713a975394dd4d879b57ee8bc66cc0f97566fa67f4406f4
MD5 2fc6406f5792d892b0772a58df57bbe0
BLAKE2b-256 f32517cd01982c7299cbca9e20247e73c83bfa53a0ed9e8b7735c915c1bb6675

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