README more appealing (has feature list), added RequestConfig, added ability to speci...

[django-tables2.git] / docs / index.rst

diff --git a/docs/index.rst b/docs/index.rst
index 865ca60fa498b85293e4361eba5cb0368d94cdd8..86c3bc72b5953a0c548fcfe6e382cf4dec6241b0 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -205,7 +205,7 @@ By passing in a value for ``order_by`` into the ``Table`` constructor, the
 
 This approach allows column sorting to be enabled for use with the ``{%
 render_table %}`` template tag. The template tag converts column headers into
-hyperlinks that add the querystring parameter ``sort`` to the current URL. This
+hyperlinks that add the querystring field ``sort`` to the current URL. This
 means your view will need to look something like:
 
 .. code-block:: python
@@ -216,6 +216,8 @@ means your view will need to look something like:
         return render_to_response('home.html', {'table': table},
                                   context_instance=RequestContext(request))
 
+See :ref:`query-string-fields` for more details.
+
 The final approach allows both of the previous approaches to be overridden. The
 instance property ``order_by`` can be
 
@@ -321,6 +323,115 @@ an accessor is used to cross relationships. To get around this be careful to
 define a ``verbose_name`` on such columns.
 
 
+.. _query-string-fields:
+
+Querystring fields
+==================
+
+The table from ``{% render_table %}`` supports sortable columns, and
+pagination. These options are passed via the querystring, and must be passed to
+the table in order for them to have an effect, e.g.
+
+.. code-block:: python
+
+    def people_listing(request):
+        table = PeopleTable(Person.objects.all())
+        table.paginate(page=request.GET.get("page", 1))
+        table.order_by = request.GET.get("sort")
+        return render_to_response("people_listing.html", {"table": table},
+                                  context_instance=RequestContext(request))
+
+This works well unless you have more than one table on a page. In that
+scenarios, all the tables will try to use the same ``sort`` and ``page``
+querystring fields.
+
+In following ``django.forms`` the solution, a prefix can be specified for each
+table:
+
+.. code-block:: python
+
+    def people_listing(request):
+        table1 = PeopleTable(Person.objects.all(), prefix="1-")  # prefix specified
+        table1.paginate(page=request.GET.get("1-page", 1))
+        table1.order_by = request.GET.get("1-sort")
+
+        table2 = PeopleTable(Person.objects.all(), prefix="2-")  # prefix specified
+        table2.paginate(page=request.GET.get("2-page", 1))
+        table2.order_by = request.GET.get("2-sort")
+
+        return render_to_response("people_listing.html",
+                                  {"table1": table1, "table2": table2},
+                                  context_instance=RequestContext(request))
+
+Taking this one step further, rather than just specifying a prefix, it's
+possible to specify the base name for each option. Suppose you don't like the
+name ``sort`` for the ordering option -- you could change it to ``ob``
+(initialism of *order by*). Such options are configured via the ``FOO_field``
+properties:
+
+- ``order_by_field``
+- ``page_field``
+- ``per_page_field`` -- **note:** this field currently isn't used by
+  ``{% render_table %}``
+
+Example:
+
+.. code-block:: python
+
+    def people_listing(request):
+        table = PeopleTable(Person.objects.all(), order_by_field="ob",
+                            page_field="p")
+        table.paginate(page=request.GET.get("p", 1))
+        table.order_by = request.GET.get("ob")
+        return render_to_response("people_listing.html", {"table": table},
+                                  context_instance=RequestContext(request))
+
+In following django-tables2 conventions, these options can be configured in
+different places:
+
+- ``Meta`` class in the table definition.
+- Table constructor.
+- Table instance property.
+
+For convenience there is a set of ``prefixed_FOO_field`` properties that exist
+on each table instance and return the final querystring field names (i.e.
+combines the prefix with the base name). This allows the above view to be
+re-written:
+
+.. code-block:: python
+
+    def people_listing(request):
+        table = PeopleTable(Person.objects.all(), order_by_field="ob",
+                            page_field="p")
+        table.paginate(page=request.GET.get(table.prefixed_page_field, 1))
+        table.order_by = request.GET.get(table.prefixed_order_by_field)
+        return render_to_response("people_listing.html", {"table": table},
+                                  context_instance=RequestContext(request))
+
+
+Config objects
+==============
+
+Config objects make it easier to configure a table. At the moment there's just
+one -- ``RequestConfig``. It takes a ``HttpRequest`` and is able to configure a
+table's sorting and pagination by extracting querystring data.
+
+The view from the previous section can be rewritten without the boilerplate:
+
+.. code-block:: python
+
+    from django_tables2 import RequestConfig
+
+    def people_listing(request):
+        table = PeopleTable(Person.objects.all(), order_by_field="ob",
+                            page_field="p")
+        RequestConfig(request).configure(table)
+        return render_to_response("people_listing.html", {"table": table},
+                                  context_instance=RequestContext(request))
+
+See :class:`.RequestConfig` for details.
+
+
 .. _pagination:
 
 Pagination
@@ -823,7 +934,12 @@ API Reference
 --------------------------
 
 .. autoclass:: django_tables2.utils.Accessor
-    :members:
+
+
+:class:`RequestConfig` Objects:
+-------------------------------
+
+.. autoclass:: django_tables2.config.RequestConfig
 
 
 :class:`Table` Objects: