Metadata-Version: 2.1
Name: django-generic-filters
Version: 2.1.1
Summary: Easy filters for your Generic ListView with Django.
Home-page: https://github.com/peopledoc/django-generic-filters
Author: PeopleDoc
Author-email: peopleask@novapost.fr
License: BSD
Project-URL: GitHub, https://github.com/peopledoc/django-generic-filters
Project-URL: Changelog, https://github.com/peopledoc/django-generic-filters/releases
Project-URL: Issue tracker, https://github.com/peopledoc/django-generic-filters/issues
Project-URL: Documentation, https://django-generic-filters.readthedocs.io
Keywords: class-based view,generic view,filters
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Provides-Extra: dev
License-File: LICENSE
License-File: AUTHORS

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


