From: Michael Elsdoerfer <michael@elsdoerfer.info>
Date: Tue, 16 Sep 2008 18:18:36 +0000 (+0200)
Subject: added some musings about the potential future filter functionality to the readme
X-Git-Tag: 0.2~40
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=06426b045db478a0bb9acee44cb2da423bacc373;p=django-tables2.git

added some musings about the potential future filter functionality to the readme
---

diff --git a/README b/README
index 6445f20..2f1ae27 100644
--- a/README
+++ b/README
@@ -530,4 +530,66 @@ TODO
       the template engine handle it
     - tests could use some refactoring, they are currently all over the place
     - what happens if duplicate column names are used? we currently don't
-      check for that at all
\ No newline at end of file
+      check for that at all
+
+Filters
+~~~~~~~
+
+Filtering is already easy (just use the normal queryset methods), but
+filter support in django-tables would want to hide the Django ORM syntax
+from the user.
+
+    * For example, say a ``models.DateTimeField`` should be filtered
+      by year: the user would only see ``date=2008`` rather than maybe
+      ``published_at__year=2008``.
+
+    * Say you want to filter out ``UserProfile`` rows that do not have
+      an avatar image set. The user would only see ```no_avatar``, which
+      in Django ORM syntax might map to
+      ``Q(avatar__isnull=True) | Q(avatar='')``.
+
+Filters would probably always belong to a column, and be defined along
+side one.
+
+    class BookTable(tables.ModelTable):
+        date = tables.Column(filter='published_at__year')
+
+If a filter is needed that does not belong to a single colunn, a column
+would have to be defined for just that filter. A ``tables.Filter`` object
+could be provided that would basically be a column, but with default
+properties set so that the column functionality is disabled as far as
+possible (i.e. ``visible=False`` etc):
+
+    class BookTable(tables.ModelTable):
+        date = tables.Column(filter='published_at__year')
+        has_cover = tables.Filter('cover__isnull', value=True)
+
+Or, if Filter() gets a lot of additional functionality like ``value``,
+we could generally make it available to all filters like so:
+
+    class BookTable(tables.ModelTable):
+        date = tables.Column(filter=tables.Filter('published_at__year', default=2008))
+        has_cover = tables.Filter('cover__isnull', value=True)
+
+More complex filters should be supported to (e.g. combine multiple Q
+objects, support ``exclude`` as well as ``filter``). Allowing the user
+to somehow specify a callable probably is the easiest way to enable this.
+
+The filter querystring syntax, as exposed to the user, could look like this:
+
+    /view/?filter=name:value
+    /view/?filter=name
+
+It would also be cool if filters could be combined. However, in that case
+it would also make sense to make it possible to choose individual filters
+which cannot be combined with any others, or maybe even allow the user
+to specify complex dependencies. That may be pushing it though, and anyway
+won't make it into the first version.
+
+    /view/?filter=name:value,foo:bar
+
+We need to think about how we make the functionality available to
+templates.
+
+Another feature that would be important is the ability to limit the valid
+values for a filter, e.g. in the date example only years from 2000 to 2008.
\ No newline at end of file