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.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-datatablesConfiguration
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:8000Testing
Install development requirements.
$ pip install -r requirements-dev.txtRun the tests.
$ python example/manage.py testYou 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:
$ toxIf you want to check the coverage, use:
$ coverage run ./example/manage.py test
$ coverage report -mDocumentation
The documentation is available online on Read the Docs.
To build the documentation, you’ll need to install sphinx.
$ pip install -r requirements-docs.txtTo build the documentation:
$ cd docs
$ make clean && make htmlChangelog
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.
