django-refinery 0.1

Django-refinery is a reusable Django application for allowing users to filter queryset dynamically.

Allows users to filter down a queryset based on a model’s fields, similar to the Django admin’s list_filter interface. A FilterTool helper class is provided, which will (by default) map filters to model fields and create a form for queryset manipulation. The helper class supports an interface which will feel familiar to anyone who’s used a Django ModelForm.

Author:

Jacob Radford

Licence:

BSD

Example usage

Given a Product model you could create a FilterTool for it with:

import refinery

class ProductFilterTool(refinery.FilterTool):
    class Meta:
        model = Product
        fields = ['name', 'price']

And then in your view you could do:

def product_list(request):
    filtertool = ProductFilterTool(request.GET or None)
    return render_to_response('product/product_list.html',
        {'filtertool': filtertool})

And then in your template:

<form action="" method="get">
    {{ filtertool.form.as_p }}
    <input type="submit" />
</form>
<h2>Products</h2>
<ul>
  {% for obj in filtertool %}
      <li>{{ obj.name }} - ${{ obj.price }}</li>
  {% endfor %}
</ul>

For more complex usage or custom needs, refer to the project documentation.

Requirements

• Python 2.5+

• Django 1.3+

Installation

• pip install -U django-refinery

• Add refinery to your INSTALLED_APPS

To install the in-development version of django-refinery, run pip install django-refinery==dev.

Documentation

See the docs folder or read it on readthedocs for expanded information on:

• Usage examples

• Contributing

• Integration with other apps

• Project background

• Low-level API

• Creating custom filters

Bugs

If you want to help out with the development of django-refinery, by posting detailed bug reports, proposing new features, or suggesting documentation improvements, use the issue tracker. If you want to fix it yourself, thank you! Fork the project, make changes and send a pull request. Please do create an issue to discuss your plans.

Background

Django-refinery is based on django-filter, an application created by Alex Gaynor. For a complete project history and list of contributors, see the project documentation.

Roadmap

• Overhaul and expand documentation

• Overhaul and expand test suite

• Refactor generic class view (look into pagination of ListView)

• Allow integration of django-floppyforms

• Allow integration of django-crispy-forms

• Allow filters on non-required fields with choices to provide option of filtering the records that are unset. (i.e. FK is null)

• Allow abstraction of ordering values used to avoid passing internal information in GET params (i.e. user__username)

• Look into adapting LinkWidget and overall behavior to support filtering like django-easyfilters or maybe drop the widget?

Resources

• Documentation

• Bug Tracker

• Code

• Continuous Integration