From 6eaeb579a9b30a2fff75979c7cd846170aecfa24 Mon Sep 17 00:00:00 2001 From: Michael Elsdoerfer Date: Tue, 1 Jun 2010 18:09:21 +0200 Subject: [PATCH] Added documentation for the new "render_COLUMN" methods. --- docs/columns.rst | 2 -- docs/templates.rst | 55 +++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 49 insertions(+), 8 deletions(-) diff --git a/docs/columns.rst b/docs/columns.rst index d064918..e9c7a1a 100644 --- 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 index 36a2acc..c3ee8bb 100644 --- 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 '' + else: + return '' % 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``. -- 2.26.2