TIP RenderTableDataPlugin is not installed on Foswiki.org.

RenderTableDataPlugin

RenderTableData Logo

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

The same principle illustrated with information about Vermeer's paintings:

View edit and render example

View large image | see RenderTableDataPluginExample

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: Sandbox.RenderTableDataPluginExample

RenderTableDataPlugin is not installed. To see the examples below follow the installation instructions.

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

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

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:

%TABLEDATA{ topic="System.MetaData" rows="2.." format=" * $C1
    • _$C2_"
separator="$n()" sortcolumn="1" beforetext="*TOPICINFO* $n()" aftertext="From MetaData" }%

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
edit
June 2008
Apeldoorn, the Netherlands
International Triennal Apeldoorn 2008
edit

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

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

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:
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:
Development:
Support::
Topic attachments
I Attachment Action Size Date Who Comment
RenderTableDataPlugin.md5md5 RenderTableDataPlugin.md5 manage 186 bytes 23 Feb 2010 - 01:30 GeorgeClark  
RenderTableDataPlugin.sha1sha1 RenderTableDataPlugin.sha1 manage 210 bytes 23 Feb 2010 - 01:30 GeorgeClark  
RenderTableDataPlugin.tgztgz RenderTableDataPlugin.tgz manage 251 K 23 Feb 2010 - 01:30 GeorgeClark  
RenderTableDataPlugin.zipzip RenderTableDataPlugin.zip manage 254 K 23 Feb 2010 - 01:29 GeorgeClark  
RenderTableDataPlugin_installerEXT RenderTableDataPlugin_installer manage 4 K 23 Feb 2010 - 01:30 GeorgeClark  
renderTableDataExample.pngpng renderTableDataExample.png manage 212 K 23 Feb 2010 - 01:29 GeorgeClark Edit and render example
Topic revision: r1 - 23 Feb 2010, GeorgeClark - This page was cached on 29 May 2016 - 23:12.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License