Skip to main content

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

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 !

Requirements

  • Python (2.7, 3.4, 3.5, 3.6)
  • Django (1.9, 1.10, 1.11, 2.0)
  • Django REST Framework (3.5, 3.6, 3.7, 3.8)

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 !

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 requirements.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

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 build

Changelog

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


Release history Release notifications

This version
History Node

0.4.0

History Node

0.3.0

History Node

0.2.1

History Node

0.2.0

History Node

0.1.0

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
djangorestframework_datatables-0.4.0-py2.py3-none-any.whl (8.2 kB) Copy SHA256 hash SHA256 Wheel 3.6 Jun 22, 2018
djangorestframework-datatables-0.4.0.tar.gz (9.0 kB) Copy SHA256 hash SHA256 Source None Jun 22, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page