djangorestframework-tabulator 0.1.1

Why this exists

Tabulator, in remote mode (pagination: "remote", filterMode: "remote", sortMode: "remote"), sends pagination/filtering/sorting using its own query string convention, and expects the response back in its own shape — neither matches what DRF ships out of the box (PageNumberPagination responds with {count, next, previous, results}; its filter_backends don’t understand nested bracketed keys). This package translates both sides. jQuery DataTables already has a mature DRF adapter (djangorestframework-datatables); no equivalent exists for Tabulator.

Usage

from rest_framework.generics import ListAPIView
from rest_framework_tabulator import TabulatorFilterBackend, TabulatorPagination

class DocumentListView(ListAPIView):
    queryset = Document.objects.all()
    serializer_class = DocumentSerializer
    pagination_class = TabulatorPagination
    filter_backends = [TabulatorFilterBackend]
    filterset_fields = ['number', 'status', 'issued_at']
    ordering_fields = ['issued_at', 'number', 'total']

Tabulator’s contract (confirmed against the source code of tabulator-tables/tabulator itself, not third-party documentation):

• Request: page/size (pagination), sort[i][field]/ sort[i][dir] (sorting), filter[i][field]/filter[i][type]/ filter[i][value] (filtering) — an array value (the in type) is sent as filter[i][value][0], filter[i][value][1], etc.

• Expected response: {"data": [...], "last_page": N}.

filterset_fields/ordering_fields on the view are allowlists of fields (same attribute names django-filter/rest_framework.filters .OrderingFilter already use, so they look familiar) — any field not declared there is silently ignored, on both the filter and the sort side. Leaving either one undeclared denies filtering/sorting entirely rather than allowing every field by default.

A computed or renamed serializer field (a SerializerMethodField, a source= field, anything without a same-named model field) needs a dict instead of a plain list, mapping the client-facing name to the real ORM lookup path(s):

filterset_fields = {
    'status': 'state',                        # renamed field
    'customer': ['customer__name', 'customer__id'],  # search both at once
}
ordering_fields = {
    'customer': ['customer__name', 'customer__id'],  # tie-break, in order
}

A list of paths is combined with OR when filtering (e.g. one customer column that matches on either a name or an id), and chained as tie-breakers, in that order, when sorting.

Supported filter types

Every filter type Tabulator ships is supported (confirmed against Filter/defaults/filters.js in the Tabulator source for the exact set of built-in types):

keywords note: Tabulator’s client-side keywords filter also supports a custom word separator and an “all words must match” toggle (headerFilterFuncParams), but neither is sent to the server in remote mode — the ajax payload only ever carries {field, type, value}. It is approximated here as a plain substring match, same as like.

smart/smarter are a faithful port of Tabulator’s own filter functions, not a Django-specific addition: . matches any non-empty value, ! matches empty/null, a leading comparison operator does a numeric comparison, a leading = does an exact match, multiple whitespace-separated words become an AND of a substring match per word, AND/OR combine sub-expressions left to right (no operator precedence, same as the original), and anything else falls back to a substring match.

A value that doesn’t fit the field’s type (e.g. a non-numeric string against an integer field, or an invalid date) raises a DRF ValidationError — a clean 400 naming the offending field — instead of an unhandled 500. Django validates most field types eagerly, right when the filter is applied, so this is caught there rather than only when the queryset is evaluated.

License

MIT — see LICENSE.

Development

pip install -e '.[dev]'
pytest