djangorestframework-datatables
Advanced tools
Seamless integration between Django REST framework and Datatables (https://datatables.net)
|build-status-image| |codecov-image| |documentation-status-image| |pypi-version| |py-versions|
This package provides seamless integration between Django REST framework <https://www.django-rest-framework.org>_ and Datatables <https://datatables.net>_.
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 <http://django-rest-framework-datatables.readthedocs.io/en/latest/>_ !
You can play with a demo of the example app on Python Anywhere <https://izimobil.pythonanywhere.com>_.
We highly recommend and only officially support the latest patch release of each Python, Django and Django Rest Framework series.
Installation
Just use ``pip``:
.. code:: bash
$ 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:
.. code:: python
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:
.. code:: python
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
.. code:: html
<!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.
.. code:: bash
$ 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.
.. code:: bash
$ pip install -r requirements-dev.txt
Run the tests.
.. code:: bash
$ 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:
.. code:: bash
$ tox
If you want to check the coverage, use:
.. code:: bash
$ coverage run ./example/manage.py test
$ coverage report -m
Documentation
-------------
The documentation is available online on `Read the Docs <http://django-rest-framework-datatables.readthedocs.io/en/latest/>`_.
To build the documentation, you’ll need to install ``sphinx``.
.. code:: bash
$ pip install -r requirements-docs.txt
To build the documentation:
.. code:: bash
$ cd docs
$ make clean && make html
.. _tox: http://tox.readthedocs.org/en/latest/
.. |build-status-image| image:: https://api.travis-ci.com/izimobil/django-rest-framework-datatables.svg?branch=master
:target: https://app.travis-ci.com/github/izimobil/django-rest-framework-datatables
:alt: Travis build
.. |codecov-image| image:: https://codecov.io/gh/izimobil/django-rest-framework-datatables/branch/master/graph/badge.svg
:target: https://codecov.io/gh/izimobil/django-rest-framework-datatables
.. |pypi-version| image:: https://img.shields.io/pypi/v/djangorestframework-datatables.svg
:target: https://pypi.python.org/pypi/djangorestframework-datatables
:alt: Pypi version
.. |documentation-status-image| image:: https://readthedocs.org/projects/django-rest-framework-datatables/badge/?version=latest
:target: http://django-rest-framework-datatables.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |py-versions| image:: https://img.shields.io/pypi/pyversions/djangorestframework-datatables.svg
:target: https://img.shields.io/pypi/pyversions/djangorestframework-datatables.svg
:alt: Python versions
.. |dj-versions| image:: https://img.shields.io/pypi/djversions/djangorestframework-datatables.svg
:target: https://img.shields.io/pypi/djversions/djangorestframework-datatables.svg
:alt: Django versions
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.
FAQs
Seamless integration between Django REST framework and Datatables (https://datatables.net)
We found that djangorestframework-datatables demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.