-Declarative way to define filters on fields on a django model form.
+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.
+Declarative way to define filters on fields on a django model form::
from people.models import Person
- 'units': models.Q(is_active=True)
+ 'units': models.Q(is_active=True),
+ 'colours__in': ['red','blue','green']
-There is also a version for FormSet.
+``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),
+ 'units': 'company.units.active'
+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.
+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.
+Allow for a callable in the value of an ``instance_filter``.
+Allow for a dict in the value of a ``filter``.