1. Luke Plant
  2. django-easyfilters

Source

django-easyfilters / README.rst

Diff from to

File README.rst

-====================
- django-easyfilters
-====================
-
-ALPHA software! Starting to get useful, but APIs still not quite settled.
+==================
+django-easyfilters
+==================
 
 Overview
 ========
 
-An app that provides filters like list_filter and date_hierarchy in Django's
-admin, but for use outside the admin, with result counts for the choices,
-and with more intelligence and things 'just working'.
+This library provides filters similar in some ways to ``list_filter`` and
+``date_hierarchy`` in Django's admin, but for use outside the
+admin. Importantly, it also includes result counts for the choices. It is
+designed to be very easy to get started with.
 
-The UI of the filters is links i.e. just click on links to add/remove
-filters.  For fields where the values are more like a continuum, the aim is
-to use autogenerated, intelligent ranges.  Dates will use something like the
-Django admin's date_hierarchy feature.
+Docs
+====
+See the docs/ directory, especially docs/overview.rst
 
 
-Install
-=======
+Demo
+====
 
-Just install using pip/easy_install - this is a pure Python library that doesn't
-need to be in INSTALLED_APPS.
+A small demo app is included, see the instructions in docs/develop.rst
 
-Usage
-=====
+A (currently) live example can be seen at:
 
-Suppose your model.py looks something like this::
+http://www.christchurchbradford.org.uk/sermons/
 
-    class Book(models.Model):
-        name = models.CharField(max_length=100)
-        binding = models.CharField(max_length=2, choices=BINDING_CHOICES)
-        authors = models.ManyToManyField(Author)
-        genre = models.ForeignKey(Genre)
-        price = models.DecimalField(max_digits=6, decimal_places=2)
-        date_published = models.DateField()
+Status
+======
 
-(BINDING_CHOICES, Author and Genre omitted for brevity).
+The library is in a useful state, but not quite 'complete'. The main glaring
+feature omission in nice handling of Decimal fields (or other numeric fields that need
+to be treated as a continuum of values) to provide range-base selection.
 
-And you have a views.py something like this::
+The internal API of Filter and FilterSet are not firmed up, but are not far from
+being so. Test coverage is extensive.
 
-    from myapp.models import Book
-
-    def booklist(request):
-        books = Book.objects.all()
-        return render(request, "booklist.html", {'books': books})
-
-
-and a template like this::
-
-    {% for book in books %}
-       {# etc #}
-    {% endfor %}
-
-
-To add the filters, in views.py you do something like this::
-
-    from django_easyfilters import FilterSet
-    from myapp.models import Book
-
-    class BookFilterSet(FilterSet):
-        fields = [
-            'binding',
-            'authors',
-            'genre',
-            'price',
-            ]
-
-    def booklist(request):
-        books = Book.objects.all()
-        booksfilter = BookFilterSet(books, request.GET)
-        return render(request, "booklist.html", {'books': booksfilter.qs,
-                                                 'booksfilter': booksfilter})
-
-Then, in the template, just add ``{{ booksfilter }}`` above the list of
-books. You can also use pagination e.g. using django-pagination::
-
-    {% autopaginate books 20 %}
-
-    <h1>Filters:</h1>
-    {{ booksfilter }}
-
-    {% paginate %}
-
-    {% for book in books %}
-       {# etc #}
-    {% endfor %}
-
-Customisation of the filters can be done using a tuple containing (field_name,
-dict of options), instead of just field_name::
-
-    class BookFilterSet(FilterSet):
-        model = Book
-        fields = [
-            'binding',
-            ('genre', dict(order_by_count=True))
-        ]
-
-Done so far
-===========
-
-* Support for ForeignKey - ForeignKeyFilter
-* Support for anything with 'choices' defined - ChoicesFilter
-* Support for ManyToMany - ManyToManyFilter
-* Fallback support for CharField, IntegerField, everything else - ValuesFilter
-* Options:
-
-  * order_by_count
-
-* Very good test coverage
+Feedback regarding API or features is very welcome!
 
 TODO
 ====
 
-* DateField, DateTimeField
-* Automatic range-based filters - e.g. for prices
-* More options for customisation
-
-
-  * 'defaults' attribute for FilterSet
-
-* Docs for customisation
-
-  * Options provided by Filters
-  * API of Filter
-  * API of FilterSet for overriding rendering
-
-
-Development
-===========
-
-First, ensure the directory containing this README is on your Python path
-(virtualenv recommended). Django is a required dependency.
-
-Tests
------
-
-To run the test suite, do::
-
-   ./manage.py test django_easyfilters
-
-Editing test fixtures
----------------------
-
-To edit the test fixtures, you can edit the fixtures in
-django_easyfilters/tests/fixtures/, or you can do it via an admin interface:
-
-First create an empty db::
-
-   rm tests.db
-   ./manage.py syncdb
-
-Then load with current test fixture::
-
-   ./manage.py loaddata django_easyfilters_tests
-
-Then edit in admin at http://localhost:8000/admin/ ::
-
-   ./manage.py runserver
-
-Or from a Python shell.
-
-Then dump data::
-
-  ./manage.py dumpdata tests --format=json --indent=2 > django_easyfilters/tests/fixtures/django_easyfilters_tests.json
-
-
-Demo
-----
-
-Once the test fixtures have been loaded into the DB, and the devserver is
-running, as above, you can view a test page at http://localhost:8000/books/
+* Automatic range-based filters for DecimalFields - e.g. for prices
+* Ability to specify 'defaults' attribute for FilterSet
+* Allow the automatic 'page' resetting to be customized