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

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