{ "info": { "author": "Nikolay Zakharov", "author_email": "nikolay@desh.su", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Framework :: Django", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python" ], "description": ".. image:: https://secure.travis-ci.org/freevoid/django-datafilters.png?branch=master\n :target: http://travis-ci.org/freevoid/django-datafilters\n\nAbstract\n========\n\nLibrary to implement reusable queryset filtering for django-powered websites.\n\nThis library provides a way to declaratively define filter specifications in a\ndjango-forms manner. Such forms can be used as ordinary django forms and they\nalso provides a method ``filter`` to perform filtering of arbitrary querysets.\n\nThis approach is somewhat differs from one in django-admin, but it looks more\nintuitive and straightforward for the author.\n\nMain features:\n\n* forms-based declaration and usage;\n* simple API;\n* easy to implement and reuse abstract filter specs of any complexity (from\n standard lookups to ``QuerySet.extra`` calls);\n* runtime-aware filtering;\n* a number of builtin specs for simple cases.\n\nUsage\n=====\n\nFor concrete usage example, see ``sample_proj/polls/views.py``.\n\nTo perform filtering one must define a subclass of\n``datafilters.filterform.FilterForm`` (base class for filter forms).\nThe typical declaration consists of class attributes declaring filter\nspecifications, subclasses of ``datafilters.filterspec.FilterSpec``.\nThis tandem is very much like the ``Form`` and ``Field`` pair.\n``FilterSpec`` subclass defines a corresponding form field that will be\nused to render and validate a django form and it also defines a method\nto get lookup conditions based on user input (``to_lookup``). There is\na bunch of builtin specs so typicaly it is not necessary to implement\nyour own filter specs for simple filtering.\n\nFor example purposes we will use models from django tutorial:\n``Choice`` and ``Question``.\n\nThe typical filter form looks like that::\n\n from datafilters.filterform import FilterForm\n from datafilters.specs import ContainsFilterSpec, \\\n SelectBoolFilterSpec\n\n class ChoicesFilterForm(FilterForm):\n choice_text = ContainsFilterSpec('choice',\n label='Choice contains text')\n question_text = ContainsFilterSpec('poll__question',\n label='Question contains text')\n has_votes = GreaterThanZeroFilterSpec('votes')\n\nDirect usage of filter form\n---------------------------\n\nDefined form can be used directly::\n\n from django.shortcuts import render_to_response\n from polls.models import Choice\n\n def choice_list(request):\n choices = Choice.objects.all()\n filterform = ChoicesFilterForm(request.GET)\n if filterform.is_valid():\n choices = filterform.filter(choices)\n\n return render_to_response('polls/choice_list.html',\n {\n 'choices': choices,\n 'filterform': filterform,\n })\n\n``filter_powered`` decorator\n----------------------------\n\nThere is a decorator to remove bottlenecks when using filtering extensively::\n\n from django.template.response import TemplateResponse\n from datafilters.decorators import filter_powered\n\n @filter_powered(ChoicesFilterForm, queryset_name='choices')\n def choice_list(request):\n choices = Choice.objects.all()\n return TemplateResponse('polls/choice_list.html',\n {'choices': choices})\n\nView mixin\n----------\n\nIf you are using django class-based views there is another option to take: a\nview mixin ``FilterFormMixin``. Example::\n\n from django.views.generic import ListView\n\n class ChoiceListView(FilterFormMixin, ListView):\n model = Choice\n filter_form_cls = ChoicesFilterForm\n\n choice_list = ChoiceListView.as_view()\n\nUsage in templates\n------------------\n\nIn our template we can use new context variable ``filterform`` as an ordinary\ndjango form::\n\n
\n\nRequirements\n============\n\n* Django >= 1.3;\n* `django-forms-extras