django-generic-filters

django-generic-filters copied to clipboard

###################### django-generic-filters ######################

django-generic-filters is a toolkit to filter results of Django's ListView, using forms.

Main use cases are obviously search forms and filtered lists.

As a developer, given you have a ListView, in order to let the user filter the results:

• use a form to easily render the filters as HTML;
• the user typically sends the filters via GET;
• validate the user's input using a Django form;
• filter the Django view's queryset using form's cleaned data.

.. image:: https://secure.travis-ci.org/peopledoc/django-generic-filters.png?branch=master :alt: Build Status :target: https://secure.travis-ci.org/peopledoc/django-generic-filters

Example

views.py

.. code-block:: python

from django_genericfilters.views import FilteredListView


class UserListView(FilteredListView):
    # ListView options. FilteredListView inherits from ListView.
    model = User
    template_name = 'user/user_list.html'
    paginate_by = 10
    context_object_name = 'users'

    # FormMixin options. FilteredListView inherits from FormMixin.
    form_class = UserListForm

    # FilteredListView options.
    search_fields = ['first_name', 'last_name', 'username', 'email']
    filter_fields = ['is_active', 'is_staff', 'is_superuser']
    default_order = 'last_name'

    def form_valid(self, form):
        """Return the queryset when form has been submitted."""
        queryset = super(UserListView, self).form_valid(form)

        # Handle specific fields of the custom ListForm
        # Others are automatically handled by FilteredListView.

        if form.cleaned_data['is_active'] == 'yes':
            queryset = queryset.filter(is_active=True)
        elif form.cleaned_data['is_active'] == 'no':
            queryset = queryset.filter(is_active=False)

        if form.cleaned_data['is_staff'] == 'yes':
            queryset = queryset.filter(is_staff=True)
        elif form.cleaned_data['is_staff'] == 'no':
            queryset = queryset.filter(is_staff=False)

        if form.cleaned_data['is_superuser'] == 'yes':
            queryset = queryset.filter(is_superuser=True)
        elif form.cleaned_data['is_superuser'] == 'no':
            queryset = queryset.filter(is_superuser=False)

        return queryset

forms.py

.. code-block:: python

from django import forms
from django.utils.translation import gettext_lazy as _
from django_genericfilters import forms as gf


class UserListForm(gf.QueryFormMixin, gf.OrderFormMixin, gf.FilteredForm):
    is_active = gf.ChoiceField(label=_('Status'),
                               choices=(('yes', _('Active')),
                                        ('no', _('Unactive'))))

    is_staff = gf.ChoiceField(label=_('Staff'))

    is_superuser = gf.ChoiceField(label=_('Superuser'))

    def get_order_by_choices(self):
        return [('date_joined', _(u'date joined')),
                ('last_login', _(u'last login')),
                ('last_name', _(u'Name'))]

Forms

Several form mixins are provided to cover frequent use cases:

• OrderFormMixin with order_by and order_reverse fields.
• QueryFormMixin for little full-text search using icontains.

See "mixin" documentation for details.

Ressources

• Documentation: https://django-generic-filters.readthedocs.io
• PyPI page: http://pypi.python.org/pypi/django-generic-filters
• Code repository: https://github.com/peopledoc/django-generic-filters
• Bugtracker: https://github.com/peopledoc/django-generic-filters/issues