Skip to content

jacklinke/django-rest-framework-datatables

This branch is 1 commit ahead of, 20 commits behind izimobil/django-rest-framework-datatables:master.

Folders and files

NameName
Last commit message
Last commit date
Dec 10, 2021
Feb 4, 2023
Nov 21, 2022
Feb 4, 2023
Nov 19, 2022
Apr 11, 2018
May 11, 2018
Nov 21, 2022
Apr 10, 2018
Apr 10, 2018
Feb 4, 2023
Feb 4, 2023
Nov 21, 2022

Repository files navigation

django-rest-framework-datatables

Travis build codecov-image Documentation Status Pypi version Python versions

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, 3.10)
  • Django (3.2, 4.0, 4.1)
  • 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-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.

Install poetry if not already installed.

$ git clone https://github.com/izimobil/django-rest-framework-datatables.git
$ cd django-rest-framework-datatables
$ poetry install --with dev
$ python example/manage.py runserver
$ firefox http://127.0.0.1:8000

Testing

Install poetry if not already installed.

Install development requirements.

$ poetry install --with dev

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.

$ poetry install --with docs

To build the documentation:

$ cd docs
$ make clean && make html

Publish to PyPI

Build package and Publish to PyPI with two commands.

$ poetry build
$ poetry publish

About

Seamless integration between Django REST framework and Datatables.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 90.3%
  • HTML 7.1%
  • CSS 2.2%
  • Shell 0.4%