djangorestframework-datatables


Namedjangorestframework-datatables JSON
Version 0.7.2 PyPI version JSON
download
home_pagehttps://github.com/izimobil/django-rest-framework-datatables
SummarySeamless integration between Django REST framework and Datatables (https://datatables.net)
upload_time2024-06-14 17:11:41
maintainerNone
docs_urlNone
authorDavid Jean Louis
requires_pythonNone
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI
coveralls test coverage
            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.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``:

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

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/izimobil/django-rest-framework-datatables",
    "name": "djangorestframework-datatables",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": null,
    "author": "David Jean Louis",
    "author_email": "izimobil@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/c7/a0/7481fee713387fd5c632b05c1d95c32f5b2ea6e1e8f15c9cf1894e1895a8/djangorestframework_datatables-0.7.2.tar.gz",
    "platform": null,
    "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.8, 3.9, 3.10, 3.11, 3.12)\n- Django (3.2, 4.1, 4.2)\n- Django REST Framework (3.14)\n\nWe highly recommend and only officially support the latest patch release of each Python, Django and Django Rest Framework series.\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 html\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: https://app.travis-ci.com/github/izimobil/django-rest-framework-datatables\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.2 (2024-06-14):\n---------------------------\n\n- Django 5.0 and 5.1 support\n- Allow overriding queryset.count() with two additional methods\n\nMany thanks to all the contributors on this release !\n\nVersion 0.7.1 (2024-03-06):\n---------------------------\n\n- Django 4.2 support\n- Dependencies versions updates\n- Fixed deprecation warnings on tests\n\nMany thanks to all the contributors on this release !\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.2",
    "project_urls": {
        "Homepage": "https://github.com/izimobil/django-rest-framework-datatables"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f32517cd01982c7299cbca9e20247e73c83bfa53a0ed9e8b7735c915c1bb6675",
                "md5": "2fc6406f5792d892b0772a58df57bbe0",
                "sha256": "fd5747b1e3d0bfb84713a975394dd4d879b57ee8bc66cc0f97566fa67f4406f4"
            },
            "downloads": -1,
            "filename": "djangorestframework_datatables-0.7.2-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2fc6406f5792d892b0772a58df57bbe0",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 15303,
            "upload_time": "2024-06-14T17:11:39",
            "upload_time_iso_8601": "2024-06-14T17:11:39.658544Z",
            "url": "https://files.pythonhosted.org/packages/f3/25/17cd01982c7299cbca9e20247e73c83bfa53a0ed9e8b7735c915c1bb6675/djangorestframework_datatables-0.7.2-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "c7a07481fee713387fd5c632b05c1d95c32f5b2ea6e1e8f15c9cf1894e1895a8",
                "md5": "253bfd891e74f98b1fd4b580066a362f",
                "sha256": "d7953968088ceb14968621a0c0a83d2f39ec1cda24b5ebe1240f3c9619bc7129"
            },
            "downloads": -1,
            "filename": "djangorestframework_datatables-0.7.2.tar.gz",
            "has_sig": false,
            "md5_digest": "253bfd891e74f98b1fd4b580066a362f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 19647,
            "upload_time": "2024-06-14T17:11:41",
            "upload_time_iso_8601": "2024-06-14T17:11:41.742530Z",
            "url": "https://files.pythonhosted.org/packages/c7/a0/7481fee713387fd5c632b05c1d95c32f5b2ea6e1e8f15c9cf1894e1895a8/djangorestframework_datatables-0.7.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-06-14 17:11:41",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "izimobil",
    "github_project": "django-rest-framework-datatables",
    "travis_ci": true,
    "coveralls": true,
    "github_actions": false,
    "requirements": [],
    "tox": true,
    "lcname": "djangorestframework-datatables"
}
        
Elapsed time: 0.81574s