diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index d13866ea3..2771e6196 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -95,9 +95,9 @@ You can also set the filter backends on a per-view, or per-viewset basis, using the `GenericAPIView` class based views. from django.contrib.auth.models import User - from myapp.serializers import UserSerializer + from myapp.serializers import UserSerializer from rest_framework import filters - from rest_framework import generics + from rest_framework import generics class UserListView(generics.ListAPIView): queryset = User.objects.all() @@ -141,6 +141,13 @@ To use REST framework's `DjangoFilterBackend`, first install `django-filter`. pip install django-filter +If you are using the browsable API or admin API you may also want to install `crispy-forms`, which will enhance the presentation of the filter forms in HTML views, by allowing them to render Bootstrap 3 HTML. + + pip install django-crispy-forms + +With crispy forms installed, the browsable API will present a filtering control for `DjangoFilterBackend`, like so: + +![Django Filter](../../docs/img/django-filter.png) #### Specifying filter fields @@ -237,6 +244,10 @@ For more details on using filter sets see the [django-filter documentation][djan The `SearchFilter` class supports simple single query parameter based searching, and is based on the [Django admin's search functionality][search-django-admin]. +When in use, the browsable API will include a `SearchFilter` control: + +![Search Filter](../../docs/img/search-filter.png) + The `SearchFilter` class will only be applied if the view has a `search_fields` attribute set. The `search_fields` attribute should be a list of names of text type fields on the model, such as `CharField` or `TextField`. class UserListView(generics.ListAPIView): @@ -274,7 +285,11 @@ For more details, see the [Django documentation][search-django-admin]. ## OrderingFilter -The `OrderingFilter` class supports simple query parameter controlled ordering of results. By default, the query parameter is named `'ordering'`, but this may by overridden with the `ORDERING_PARAM` setting. +The `OrderingFilter` class supports simple query parameter controlled ordering of results. + +![Ordering Filter](../../docs/img/ordering-filter.png) + +By default, the query parameter is named `'ordering'`, but this may by overridden with the `ORDERING_PARAM` setting. For example, to order users by username: @@ -395,6 +410,8 @@ Generic filters may also present an interface in the browsable API. To do so you `to_html(self, request, queryset, view)` +The method should return a rendered HTML string. + # Third party packages The following third party packages provide additional filter implementations. diff --git a/docs/img/django-filter.png b/docs/img/django-filter.png new file mode 100644 index 000000000..5baef32f7 Binary files /dev/null and b/docs/img/django-filter.png differ diff --git a/docs/img/ordering-filter.png b/docs/img/ordering-filter.png new file mode 100644 index 000000000..25bc4ec7a Binary files /dev/null and b/docs/img/ordering-filter.png differ diff --git a/docs/img/search-filter.png b/docs/img/search-filter.png new file mode 100644 index 000000000..d36f2b968 Binary files /dev/null and b/docs/img/search-filter.png differ diff --git a/rest_framework/renderers.py b/rest_framework/renderers.py index d06b4bd21..25d82def1 100644 --- a/rest_framework/renderers.py +++ b/rest_framework/renderers.py @@ -591,7 +591,9 @@ class BrowsableAPIRenderer(BaseRenderer): # Infer if this is a list view or not. paginator = getattr(view, 'paginator', None) - if (paginator is not None and data is not None): + if isinstance(data, list): + pass + elif (paginator is not None and data is not None): try: paginator.get_results(data) except (TypeError, KeyError):