=====================
django-filtered-form
=====================


---------------
Installation
---------------

In your virtualenv, use ``pip install django-filteredform``.

You don't need to install it into your ``settings.INSTALLED_APPS``, as it 
does not provide any models or templates, only forms.

---------------
Usage
---------------

Declarative way to define filters on fields on a django model form::

    from django import forms
    from people.models import Person
    from filtered_form.forms import FilteringForm
    
    class PersonAdminForm(FilteringForm):
        class Meta:
            model = Person
        
        instance_filters = {
            'units': 'company.units'
        }
        filters = {
            'units': models.Q(is_active=True),
            'colours__in': ['red','blue','green']
        }

~~~~~~~~~~~~~~~~~~~~~
``instance_filters``
~~~~~~~~~~~~~~~~~~~~~
``instance_filters`` are things that allow for relational filters to be applied.

For instance, if you have a triple of models, ``Person``, ``Unit`` and ``Company``, 
and every person and unit have a foreign key to a company, you can
use an instance filter to easily select only the associated company's units for
a queryset when viewing a person.

Alternatively, you can supply a queryset method (that does not require arguments),
for more filtering::

    instance_filters = {
        'units': 'company.units.active'
    }

~~~~~~~~~~~~~~~~~~~~~
plain ``filters``
~~~~~~~~~~~~~~~~~~~~~

A more conventional filter structure, that allows you to supply a ``Q`` object, or
a dict of key-value pairs, which will be passed to ``.filter()`` on the queryset.

You can quite easily shoot yourself in the foot if your filter keys are not valid
arguments for a filter function on that queryset.

~~~~~~~~~~~~~~~~~~~~~
FormSets
~~~~~~~~~~~~~~~~~~~~~

You can either create a form using this method, and then pass that to your formset
class or factory. Or, you can have a formset class based on ``filtered_form.forms.FilteredFormSet``,
which will also set up the queryset values on the empty form correctly, which is very
useful if you are using dynamic forms.

---------------
Version History
---------------

~~~~~~~~
1.0.3
~~~~~~~~
Fix a bug where new objects could not be created in the django admin.

~~~~~~~~
1.0.1
~~~~~~~~
Improve documentation.

Allow for a callable in the value of an ``instance_filter``.

Allow for a dict in the value of a ``filter``.

~~~~~~~~
1.0
~~~~~~~~
Initial Release.