Added documentation for the new "render_COLUMN" methods.

miracle2k · miracle2k · commit 6eaeb579a9b3 · 2010-06-01T18:18:23.000+02:00
diff --git a/docs/columns.rst b/docs/columns.rst
@@ -50,8 +50,6 @@ The overwritten ``book_name`` field/column will now be exposed as the
 cleaner ``name``, and the new ``author`` column retrieves it's values from
 ``Book.info.author.name``.
 
-Note: ``data`` may also be a callable which will be passed a row object.
-
 Apart from their internal name, you can define a string that will be used
 when for display via ``verbose_name``:
 
diff --git a/docs/templates.rst b/docs/templates.rst
@@ -1,7 +1,6 @@
-================================
-Rendering the table in templates
-================================
-
+===================
+Rendering the table
+===================
 
 A table instance bound to data has two attributes ``columns`` and ``rows``,
 which can be iterate over:
@@ -27,11 +26,55 @@ For the attributes available on a bound column, see :doc:`features/index`,
 depending on what you want to accomplish.
 
 
+Custom render methods
+---------------------
+
+Often, displaying a raw value of a table cell is not good enough. For
+example, if your table has a ``rating`` column, you might want to show
+an image showing the given number of **stars**, rather than the plain
+numeric value.
+
+While you can always write your templates so that the column in question
+is treated separately, either by conditionally checking for a column name,
+or by explicitely rendering each column manually (as opposed to simply
+looping over the ``rows`` and ``columns`` attributes), this is often
+tedious to do.
+
+Instead, you can opt to move certain formatting responsibilites into
+your Python code:
+
+.. code-block:: django
+
+    class BookTable(tables.ModelTable):
+        name = tables.Column()
+        rating_int = tables.Column(name="rating")
+
+        def render_rating(self, instance):
+            if instance.rating_count == 0:
+                return '<img ="no-rating.png">'
+            else:
+                return '<img ="rating-%s.png">' % instance.rating_int
+
+When accessing ``table.rows[i].rating``, the ``render_rating`` method
+will be called. Note the following:
+
+   - What is passed is underlying raw data object, in this case, the
+     model instance. This gives you access to data values that may not
+     have been defined as a column.
+   - For the method name, the public name of the column must be used, not
+     the internal field name. That is, it's ``render_rating``, not
+     ``render_rating_int``.
+   - The method is called whenever the cell value is retrieved by you,
+     whether from Python code or within templates. However, operations by
+     ``django-tables``, like sorting, always work with the raw data.
+
+
 The table.columns container
 ---------------------------
 
-While you can iterate through ``columns`` and get all the currently visible
-columns, it further provides features that go beyond a simple iterator.
+While you can iterate through the ``columns`` attribute and get all the
+currently visible columns, it further provides features that go beyond
+a simple iterator.
 
 You can access all columns, regardless of their visibility, through
 ``columns.all``.
