Seamless integration between Django REST framework and Datatables (https://datatables.net)
Project description
django-rest-framework-datatables
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.7, 3.8, 3.9)
- Django (2.0, 2.1, 2.2, 3.0, 3.1, 3.2, 4.0)
- Django REST Framework (3.7, 3.8, 3.9, 3.10, 3.11, 3.12)
Please note:
- Django 3.X branch is only supported with Django REST Framework 3.11 or superior and DRF-datatables version 0.5.1 or superior.
- Django 4.X branch is only supported with Django REST Framework 3.12 or superior and DRF-datatables version 0.7.0 or superior.
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 build
Changelog
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for djangorestframework-datatables-0.7.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 64ccae255cbe03ae14793c55b900ce58894eb856816d6f9e16acea4a2197a6d9 |
|
MD5 | 333f53a325926e7b27deb3ac2203e284 |
|
BLAKE2-256 | 86c07e9e5aed6c2fe20553b0ed998e260697edcd2b31bb92c8468b9f189b509d |
Hashes for djangorestframework_datatables-0.7.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1be615b811a5625546e93f4c331b868743925776b6c7ad6c77d22e1af6f49819 |
|
MD5 | 7863ba1400b252bee5f90bf1b84e4115 |
|
BLAKE2-256 | e8350fd25badceee51a454f8175e74979e2f5d3958c463b13f1e04e484deecc5 |