From 7ccf79aabf68d92360b40b561b1948d4da2d4caa Mon Sep 17 00:00:00 2001 From: Bradley Ayers Date: Wed, 23 Mar 2011 09:15:07 +1000 Subject: [PATCH] * Fixed bug in conf.py, where it was trying to use the old VERSION variable in django_tables. * Updated the documentation to clarify the use-cases for column formatters. --- docs/conf.py | 4 ++-- docs/index.rst | 35 +++++++++++++++++++++++++++-------- 2 files changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 9fcd66f..2ebada6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,9 +50,9 @@ project = u'django-tables' # built documents. # # The short X.Y version. -version = '.'.join(map(str, tables.VERSION[0:2])) +version = '0.4.0.alpha2.dev' # The full version, including alpha/beta/rc tags. -release = tables.get_version() +release = '0.4.0.alpha2.dev' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index e79be21..03d3b1f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -142,9 +142,12 @@ control you want, the less easy it is to use). Column formatter ---------------- -If all you want to do is change the way a column is formatted, you can simply -provide the :attr:`~Column.formatter` argument to a :class:`Column` when you -define the :class:`Table`: +Using a formatter is a quick way to adjust the way values are displayed in a +column. A limitation of this approach is that you *only* have access to a +single attribute of the data source. + +To use a formatter, simply provide the :attr:`~Column.formatter` argument to a +:class:`Column` when you define the :class:`Table`: .. code-block:: python @@ -161,10 +164,17 @@ define the :class:`Table`: #10 31 years old -The limitation of this approach is that you're unable to incorporate any -run-time information of the table into the formatter. For example it would not -be possible to incorporate the row number into the cell's value. +As you can see, the only the value of the column is available to the formatter. +This means that **it's impossible create a formatter that incorporates other +values of the record**, e.g. a column with an ```` that uses +:func:`reverse` with the record's ``pk``. + +If formatters aren't powerful enough, you'll need to either :ref:`create a +Column subclass `, or to use the +:ref:`Table.render_FOO method `. + +.. _table.render_foo: :meth:`Table.render_FOO` Method ------------------------------- @@ -177,8 +187,10 @@ DRY). The example below has a number of different techniques in use: * :meth:`Column.render` (accessible via :attr:`BoundColumn.column`) applies the - *formatter* function if it's been provided. This is evident in the order that - the square and angled brackets have been applied for the ``id`` column. + *formatter* if it's been provided. The effect of this behaviour can be seen + below in the output for the ``id`` column. Square brackets (from the + *formatter*) have been applied *after* the angled brackets (from the + :meth:`~Table.render_FOO`). * Completely abitrary values can be returned by :meth:`render_FOO` methods, as shown in :meth:`~SimpleTable.render_row_number` (a :attr:`_counter` attribute is added to the :class:`SimpleTable` object to keep track of the row number). @@ -213,6 +225,11 @@ The example below has a number of different techniques in use: <[10]> 31 years old +The :meth:`Column.render` method is what actually performs the lookup into a +record to retrieve the column value. In the example above, the +:meth:`render_row_number` never called :meth:`Column.render` and as a result +there was not attempt to access the data source to retrieve a value. + Custom Template --------------- @@ -244,6 +261,8 @@ ignore the built-in generation tools, and instead pass an instance of your +.. _subclassing-column: + Subclassing :class:`Column` --------------------------- -- 2.26.2