RenderTableDataPlugin

Extract and render table data in an alternate format

Main features:

• Pass a custom format to render the table data
• Choose a subsection of the table to be rendered: row and column ranges can be set
• Optionally render the data in a different topic the table is in
• Sort results on any table column

Motivation

Our intranet shows an introductory page with all new employees. Each person is listed with a picture and a personally written message. I wanted these 'person' blocks to be nicely formatted in HTML and CSS, while at the same time keeping the data very easy to update.

So data entry and data display are separated, leading to:

• less bugs caused by mistyping or messing up complex variable blocks - anyone not familiar with Foswiki can type some text in a table cell
• small display modules that can be moved around, for instance to the homepage

Limitations

The current implementation has the following caveats:

• Tables need to be uniform: merged cells (rowspans and colspans) are not supported
• Only tables created by Foswiki syntax are supported

Usage

%TABLEDATA{
   web="..."
   topic="..."
   id="..."
   format="..."
   separator="..."
   rows="..."
   cols="..."
   show="..."
   preservespaces="on"
   escapequotes="off"
   sortdirection="descending"
   sortcolumn="..."
   filter="random"
   beforetext="..."
   aftertext="..."
}%

Any one of the parameters is optional.

Parameters

Parameter	Description	Default value	Examples
topic	Topic the table is in.	none (the current topic)	topic="WebHome", topic="Main.WebHome"
web	Web the table topic is in.	none (the current Web)	web="Main"
id	Parses the table that has an id set as %TABLE{id="xxx"}% parameter.	none (uses the first table in the topic)	id="wines"
format	Format string to render the table row. Format parameters: Get cell data $Cn token for the cell data, indicated with column number n; for example $C1 or $C2. The first row is numbered 1. The column number always refers to the original table, even if cells are omitted with parameter rows or cols. Limit characters $Cn(m) limit rendered cell text to a maximum number of characters as indicated by number m. $Cn(m,placeholder) placeholder text to append after m characters; the text is not appended if the text has less characters than m. Warning: this may break TML syntax in the middle. Evaluate cell value $C1("='value'" then="true" else="false") returns "true" if cell $C1 is equal to "xxx" and "false" otherwise. When used inside format you must escape the quotes as \". $C2("isempty" then="empty" else="not empty") returns "empty" if cell $C2 is empty (this may differ if preservespaces is set to "on").	none (the bare table cell data)	format="Summary: $C1(200,...)$n()"
separator	Separates results with a separator string.	none (no separator)	separator="$n()"
rows	Either a row number or a range of rows to read. A range is defined as two numbers separated by ... The end row number can be omitted, for example: rows="2..". The first row is numbered 1. Use rows="2.." to skip the header row.	none (all rows)	rows="2", rows="2..6", rows="2.."
cols	Either a column number or a range of columns to read. A range is defined as two numbers separated by ... The end column number can be omitted, for example: cols="2..". The first column is numbered 1.	none (all columns)	cols="2", cols="1..4", cols="1.."
show	Show a limited set of results: either a row number or a range of rows. A range is defined as two numbers separated by ... The end result number can be omitted, for example: show="2..". The first result is numbered 1. If sorting is used, sorting takes place before limiting the display by show. Start counting from the end by using a negative number: show="-5.." will start 5 positions from the end counting up to the end. Likewise use show="..-5" to show results up to the fifth item from the end.	none (show all results)	show="2", show="2..6", show="2..", show="-5..", show="..-5"
preservespaces	By default leading and trailing spaces of table cells are trimmed. Use on to preserve spaces.	none (spaces are trimmed)	preservespaces="on"
preservevariables	By default Foswiki variables EDITCELL and CALC are removed. Use preservevariables="on" to keep these variables in the rendered text.	none (variables are removed)	preservevariables="on"
escapequotes	Will not escape double quotes and single quotes if set to off. By default quotes are escaped. If you are using the output text in html it is adviced to have quotes escaped. If you render out to xml set the parameter to off.	on	escapequotes="off"
sortdirection	The sort direction of the parsed data corresponding to the original table data. If no sortcolumn is passed and the direction is "descending", the results are simply reversed.	none (no sorting)	sortdirection="ascending" (default direction), sortdirection="descending"
sortcolumn	The table column data to sort upon. You may use a column with dates or sequential numbers to sort the results without showing that order data in the results. The first column is numbered 1. The column number always refers to the original table, even if cells are omitted with parameter rows or cols.	none (no sorting)	sortcolumn="1"
filter	Defines what will be displayed. At this time only filter paramater random is implemented.	none (no filter)	filter="random"
beforetext	Text to display before the rendered data.	none	beforetext="The list:$n()"
aftertext	Text to display after the rendered data.	none	aftertext="For more information see..."

Format tokens

If you use Foswiki variables inside TABLEDATA parameters chances are it will mess up the variable, or the rendered html. Use format tokens to 'delay' rendering of these variables until the TABLEDATA parameters are parsed.

The format tokens are the same as with FormattedSearch:

Escape:	Expands To:
$n or $n()	New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar
$nop or $nop()	Is a "no operation".
$quot	Double quote (")
$percnt	Percent sign (%)
$dollar	Dollar sign ($)

Examples

See also: RenderTableDataPluginExample

Data from a table in this topic

%TABLE{id="thetable"}%
| ABC | DEF |
| GHI | JKL |

%TABLEDATA{
id="thetable"
format="   * $C2"
separator="$n()"
}%

Results in:

ABC	DEF
GHI	JKL

• DEF
• JKL

Data from another topic

%TABLEDATA{
topic="%SYSTEMWEB%.MetaData"
rows="2.."
format="   * *$C1*
      * _$C2_"
separator="$n()"      
sortcolumn="1"
beforetext="---+++!! TOPICINFO $n()"
aftertext="From [[%SYSTEMWEB%.MetaData#META_TOPICINFO][MetaData]]"
}%

Results in:

Evaluating values

In this example links with a link label are created if a URL exists in the table row, otherwise only the title is displayed.

Date	Location	URL	Title
12 May 2008	Netherlands		National Windmill Day
June 2008	Apeldoorn, the Netherlands	http://www.triennale.nl/foreword.htm	International Triennal Apeldoorn 2008

%TABLEDATA{
id="dates"
rows="2.."
sortcolumn="1"
sortdirection="descending"
format="   * $C1$C3(\"isempty\" then=\" $C4\" else=\" [[$C3][$C4]]\") %BR%   $C2$n()"
}%

Results in:

• June 2008 International Triennal Apeldoorn 2008
  Apeldoorn, the Netherlands
• 12 May 2008 National Windmill Day
  Netherlands

Plugin Test

• This plugin is <span class=.

Settings

Settings are not read from this topic. To enable debug, copy the following setting to your SitePreferences or to the topic being debugged.

• Set RENDERTABLEDATAPLUGIN_DEBUG = 0

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Authors:	Foswiki:Main.ArthurClemens
Copyright ©:	2007-2008 Arthur Clemens
License:	GPL
Version:	6481 (2010-02-23)
Release:	2.0
14 Feb 2010	Foswikitask:Item8526 - Convert to Foswiki
24 Mar 2008	Arthur Clemens: 1.2.1 Added parameter preservevariables
27 Feb 2008	Arthur Clemens: 1.2 Added cell value evaluation. Added unit tests.
25 Jan 2008	Arthur Clemens: 1.1 Adds parameters id, separator and escapequotes.
24 Nov 2007	Arthur Clemens: 1.0.6 Use standard TWiki function for format tokens. Change: instead of $n use $n().
07 Apr 2007	Arthur Clemens: 1.0.5 Added the option to use negative numbers for show, for instance show="-n.." to start n positions from the end. Deprecated condition="random"; from now on use filter="random".
12 Mar 2007	Arthur Clemens: 1.0.4 Added limit parameter syntax to format.
11 Mar 2007	Arthur Clemens: 1.0.3 Added $nop token.
08 Mar 2007	Arthur Clemens: 1.0.2 Fixed sorting bug. Added params beforetext, aftertext, show and condition="random".
07 Mar 2007	Arthur Clemens: 1.0.1 Fixed CSS bug in Win Explorer 6 in example.
04 Mar 2007	Arthur Clemens: 1.0 First release.
Home:	http://foswiki.org/Extensions/RenderTableDataPlugin
Development:	http://foswiki.org/Development/RenderTableDataPlugin
Support::	http://foswiki.org/Support/RenderTableDataPlugin