django-rest-framework-datatables
================================
|build-status-image| |codecov-image| |documentation-status-image| |pypi-version| |py-versions|
Overview
--------
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>`_.
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``:
.. 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 build
.. _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: http://travis-ci.com/izimobil/django-rest-framework-datatables?branch=master
: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.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.
Raw data
{
"_id": null,
"home_page": "https://github.com/izimobil/django-rest-framework-datatables",
"name": "djangorestframework-datatables",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "David Jean Louis",
"author_email": "izimobil@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/86/c0/7e9e5aed6c2fe20553b0ed998e260697edcd2b31bb92c8468b9f189b509d/djangorestframework-datatables-0.7.0.tar.gz",
"platform": "",
"description": "django-rest-framework-datatables\n================================\n\n|build-status-image| |codecov-image| |documentation-status-image| |pypi-version| |py-versions|\n\nOverview\n--------\n\nThis package provides seamless integration between `Django REST framework <https://www.django-rest-framework.org>`_ and `Datatables <https://datatables.net>`_.\n\nInstall 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.\nIt handles searching, filtering, ordering and most usecases you can imagine with Datatables.\n\nThe 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.\n\nFull documentation is available on `Read the Docs <http://django-rest-framework-datatables.readthedocs.io/en/latest/>`_ !\n\nYou can play with a demo of the example app on `Python Anywhere <https://izimobil.pythonanywhere.com>`_.\n\nRequirements\n------------\n\n- Python (3.7, 3.8, 3.9)\n- Django (2.0, 2.1, 2.2, 3.0, 3.1, 3.2, 4.0)\n- Django REST Framework (3.7, 3.8, 3.9, 3.10, 3.11, 3.12)\n\nPlease note:\n\n- Django 3.X branch is only supported with Django REST Framework 3.11 or superior and DRF-datatables version 0.5.1 or superior.\n- Django 4.X branch is only supported with Django REST Framework 3.12 or superior and DRF-datatables version 0.7.0 or superior.\n\n\nQuickstart\n----------\n\nInstallation\n~~~~~~~~~~~~\n\nJust use ``pip``:\n\n.. code:: bash\n\n $ pip install djangorestframework-datatables\n\nConfiguration\n~~~~~~~~~~~~~\n\nTo enable Datatables support in your project, add ``'rest_framework_datatables'`` to your ``INSTALLED_APPS``, and modify your ``REST_FRAMEWORK`` settings like this:\n\n.. code:: python\n\n REST_FRAMEWORK = {\n 'DEFAULT_RENDERER_CLASSES': (\n 'rest_framework.renderers.JSONRenderer',\n 'rest_framework.renderers.BrowsableAPIRenderer',\n 'rest_framework_datatables.renderers.DatatablesRenderer',\n ),\n 'DEFAULT_FILTER_BACKENDS': (\n 'rest_framework_datatables.filters.DatatablesFilterBackend',\n ),\n 'DEFAULT_PAGINATION_CLASS': 'rest_framework_datatables.pagination.DatatablesPageNumberPagination',\n 'PAGE_SIZE': 50,\n }\n\nAnd that's it !\n~~~~~~~~~~~~~~~\n\nYour API is now fully compatible with Datatables and will provide searching, filtering, ordering and pagination without any modification of your API code !\n\nAlways Serialize Specific Fields\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nSometimes 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:\n\n.. code:: python\n\n class ArtistSerializer(serializers.ModelSerializer):\n id = serializers.IntegerField(read_only=True)\n \n class Meta:\n model = Artist\n fields = (\n 'id', 'name',\n )\n datatables_always_serialize = ('id',)\n\nAn example of Datatable\n~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: html\n\n <!doctype html>\n <html lang=\"en\">\n <head>\n <meta charset=\"utf-8\">\n <title>Rolling Stone Top 500 albums of all time</title>\n <link rel=\"stylesheet\" href=\"//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.0.0/css/bootstrap.css\">\n <link rel=\"stylesheet\" href=\"//cdn.datatables.net/1.10.16/css/dataTables.bootstrap4.min.css\">\n </head>\n \n <body>\n <div class=\"container\">\n <div class=\"row\">\n <div class=\"col-sm-12\">\n <table id=\"albums\" class=\"table table-striped table-bordered\" style=\"width:100%\">\n <thead>\n <tr>\n <th>Rank</th>\n <th>Artist</th>\n <th>Album name</th>\n <th>Year</th>\n <th>Genres</th>\n </tr>\n </thead>\n </table>\n </div>\n </div>\n </div>\n <script src=\"//code.jquery.com/jquery-1.12.4.js\"></script>\n <script src=\"//cdn.datatables.net/1.10.16/js/jquery.dataTables.min.js\"></script>\n <script src=\"//cdn.datatables.net/1.10.16/js/dataTables.bootstrap4.min.js\"></script>\n <script>\n $(document).ready(function() {\n var table = $('#albums').DataTable({\n \"serverSide\": true,\n \"ajax\": \"/api/albums/?format=datatables\",\n \"columns\": [\n {\"data\": \"rank\", \"searchable\": false},\n {\"data\": \"artist_name\", \"name\": \"artist.name\"},\n {\"data\": \"name\"},\n {\"data\": \"year\"},\n {\"data\": \"genres\", \"name\": \"genres.name\", \"sortable\": false},\n ]\n });\n });\n </script>\n </body>\n </html>\n\nExample project\n---------------\n\nTo play with the example project, just clone the repository and run the dev server.\n\n.. code:: bash\n\n $ git clone https://github.com/izimobil/django-rest-framework-datatables.git\n $ cd django-rest-framework-datatables\n $ pip install -r requirements-dev.txt\n $ python example/manage.py runserver\n $ firefox http://127.0.0.1:8000\n\nTesting\n-------\n\nInstall development requirements.\n\n.. code:: bash\n\n $ pip install -r requirements-dev.txt\n\nRun the tests.\n\n.. code:: bash\n\n $ python example/manage.py test\n\nYou can also use the excellent `tox`_ testing tool to run the tests\nagainst all supported versions of Python and Django. Install tox\nglobally, and then simply run:\n\n.. code:: bash\n\n $ tox\n\nIf you want to check the coverage, use:\n\n.. code:: bash\n\n $ coverage run ./example/manage.py test\n $ coverage report -m\n\nDocumentation\n-------------\n\nThe documentation is available online on `Read the Docs <http://django-rest-framework-datatables.readthedocs.io/en/latest/>`_.\n\nTo build the documentation, you\u2019ll need to install ``sphinx``.\n\n.. code:: bash\n\n $ pip install -r requirements-docs.txt\n\nTo build the documentation:\n\n.. code:: bash\n\n $ cd docs\n $ make clean && make build\n\n\n.. _tox: http://tox.readthedocs.org/en/latest/\n\n.. |build-status-image| image:: https://api.travis-ci.com/izimobil/django-rest-framework-datatables.svg?branch=master\n :target: http://travis-ci.com/izimobil/django-rest-framework-datatables?branch=master\n :alt: Travis build\n\n.. |codecov-image| image:: https://codecov.io/gh/izimobil/django-rest-framework-datatables/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/izimobil/django-rest-framework-datatables\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/djangorestframework-datatables.svg\n :target: https://pypi.python.org/pypi/djangorestframework-datatables\n :alt: Pypi version\n\n.. |documentation-status-image| image:: https://readthedocs.org/projects/django-rest-framework-datatables/badge/?version=latest\n :target: http://django-rest-framework-datatables.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. |py-versions| image:: https://img.shields.io/pypi/pyversions/djangorestframework-datatables.svg\n :target: https://img.shields.io/pypi/pyversions/djangorestframework-datatables.svg\n :alt: Python versions\n\n.. |dj-versions| image:: https://img.shields.io/pypi/djversions/djangorestframework-datatables.svg\n :target: https://img.shields.io/pypi/djversions/djangorestframework-datatables.svg\n :alt: Django versions\n\n\nChangelog\n=========\n\nVersion 0.7.0 (2021-12-09):\n---------------------------\n\n- Django 4.0 compatibility\n- Added global search support to YADCFModelMultipleChoiceFilter\n- Various fixes on filters\n- Various fixes on pagination\n- Fixed / improved documentation and examples\n\nMany thanks to all the contributors on this release !\n\nVersion 0.6.0 (2021-02-09):\n---------------------------\n\n- Integration with django-filter\n- Example of using yadcf and django-filter to create a multi-select column\n- Fixed support for POST requests from datatables\n- Some fixes on pagination\n\nMany thanks to all the contributors on this release !\n\nVersion 0.5.2 (2020-04-10):\n---------------------------\n\n- Added support for POST requests from datatables\n- Avoid extra count queries\n- Handle dummy columns gracefully\n\nVersion 0.5.1 (2020-01-13):\n---------------------------\n\n- Added support for Django 3.0\n- Added support for disabling pagination when the client requests it with length=-1 parameter\n- Added optional column sorting to handle ties\n- Minor code fixes\n\nVersion 0.5.0 (2019-03-31):\n---------------------------\n\n- Fixed total number of rows when view is using multiple filter back-ends\n- New meta option ``datatables_extra_json`` on view for adding key/value pairs to rendered JSON\n- Minor docs fixes\n\nVersion 0.4.1 (2018-11-16):\n---------------------------\n\n- Added support for Django 2.1 and DRF 3.9\n- Updated README\n\nVersion 0.4.0 (2018-06-22):\n---------------------------\n\n- Added top level filtering for nested serializers\n- Added multiple field filtering\n- Added a ?keep= parameter that allows to bypass the filtering of unused fields\n- Better detection of the requested format\n- Fixed typo in Queryset.count() method name\n\n\nVersion 0.3.0 (2018-05-11):\n---------------------------\n\n- 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\n- Optimize filters\n- Use AND operator for column filtering instead of OR, to be consistant with the client-side behavior of Datatables\n\nVersion 0.2.1 (2018-04-11):\n---------------------------\n\n- This version replaces the 0.2.0 who was broken (bad setup.py)\n\nVersion 0.2.0 (2018-04-11):\n---------------------------\n\n- Added full documentation\n- Removed serializers, they are no longer necessary, filtering of columns is made by the renderer\n\nVersion 0.1.0 (2018-04-10):\n---------------------------\n\nInitial release.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Seamless integration between Django REST framework and Datatables (https://datatables.net)",
"version": "0.7.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8350fd25badceee51a454f8175e74979e2f5d3958c463b13f1e04e484deecc5",
"md5": "7863ba1400b252bee5f90bf1b84e4115",
"sha256": "1be615b811a5625546e93f4c331b868743925776b6c7ad6c77d22e1af6f49819"
},
"downloads": -1,
"filename": "djangorestframework_datatables-0.7.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "7863ba1400b252bee5f90bf1b84e4115",
"packagetype": "bdist_wheel",
"python_version": "3.8",
"requires_python": null,
"size": 15079,
"upload_time": "2021-12-09T11:45:54",
"upload_time_iso_8601": "2021-12-09T11:45:54.644693Z",
"url": "https://files.pythonhosted.org/packages/e8/35/0fd25badceee51a454f8175e74979e2f5d3958c463b13f1e04e484deecc5/djangorestframework_datatables-0.7.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "86c07e9e5aed6c2fe20553b0ed998e260697edcd2b31bb92c8468b9f189b509d",
"md5": "333f53a325926e7b27deb3ac2203e284",
"sha256": "64ccae255cbe03ae14793c55b900ce58894eb856816d6f9e16acea4a2197a6d9"
},
"downloads": -1,
"filename": "djangorestframework-datatables-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "333f53a325926e7b27deb3ac2203e284",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13850,
"upload_time": "2021-12-09T11:45:52",
"upload_time_iso_8601": "2021-12-09T11:45:52.563848Z",
"url": "https://files.pythonhosted.org/packages/86/c0/7e9e5aed6c2fe20553b0ed998e260697edcd2b31bb92c8468b9f189b509d/djangorestframework-datatables-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-12-09 11:45:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "izimobil",
"github_project": "django-rest-framework-datatables",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "djangorestframework-datatables"
}
JSON
