Tags:
component1Add my vote for this tag rendering2Add my vote for this tag tables2Add my vote for this tag user_interface2Add my vote for this tag create new tag
, view all tags

RenderTableDataPlugin

Separate data storage from display: render table data in any different way.

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 TWiki 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 TWiki 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 TWiki 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 TWiki 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

RenderTablePlugin 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%.TWikiMetaData"
rows="2.."
format="   * *$C1*
      * _$C2_"
separator="$n()"      
sortcolumn="1"
beforetext="---+++!! TOPICINFO $n()"
aftertext="From [[%SYSTEMWEB%.TWikiMetaData#META_TOPICINFO][TWikiMetaData]]"
}%

Results in:

%TABLEDATA{ topic="TWiki06x00.TWikiMetaData" rows="2.." format=" * $C1

    • _$C2_"
separator="$n()" sortcolumn="1" beforetext="*TOPICINFO* $n()" aftertext="From TWikiMetaData" }%

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: %TABLEDATA{ id="dates" rows="2.." sortcolumn="1" sortdirection="descending" format=" * $C1$C3(\"isempty\" then=\" $C4\" else=\" $C4\")
$C2$n()" }%

Plugin Test

  • This plugin is not enabled.

Settings

  • Set SHORTDESCRIPTION = Separate data storage from display: render table data in any different way
  • Set DEBUG = 0

Installation Instructions

  • Download the ZIP file from the Plugin web (see below)
  • Unzip RenderTableDataPlugin.zip in your ($TWIKI_ROOT) directory.

Plugin Info

Authors: TWiki:Main.ArthurClemens
Copyright: © 2007-2008 Arthur Clemens,
© 2007-2010 TWiki:TWiki.TWikiContributor
License: GPL
Dependencies: None
Plugin Version: 19252 (2010-07-25)
History:  
2010-07-25: TWikibug:Item6530 - doc fixes
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://TWiki.org/cgi-bin/view/Plugins/RenderTableDataPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/RenderTableDataPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/RenderTableDataPluginAppraisal
Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 RenderTableDataPlugin.md5 r17 r16 r15 r14 r13 manage 0.2 K 2010-07-26 - 05:00 PeterThoeny  
Compressed Zip archivetgz RenderTableDataPlugin.tgz r17 r16 r15 r14 r13 manage 251.5 K 2010-07-26 - 04:59 PeterThoeny  
Compressed Zip archivezip RenderTableDataPlugin.zip r17 r16 r15 r14 r13 manage 253.6 K 2010-07-26 - 04:59 PeterThoeny  
Unknown file formatEXT RenderTableDataPlugin_installer r5 r4 r3 r2 r1 manage 3.8 K 2010-07-26 - 05:00 PeterThoeny  
PNGpng renderTableDataExample.png r1 manage 212.7 K 2010-07-26 - 04:50 PeterThoeny Edit and render example
Edit | Attach | Watch | Print version | History: r23 < r22 < r21 < r20 < r19 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r23 - 2013-10-16 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.