%META:TOPICINFO{author="TWikiContributor" date="1280119465" format="1.1" version="$Rev$"}%
---+!! !RenderTableDataPlugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/RenderTableDataPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/RenderTableDataPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
*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

<div class="twikiHelp">
The same principle illustrated with information about Vermeer's paintings:

<a href="%ATTACHURLPATH%/renderTableDataExample.png"><img style="border:1px solid ccc;" src="%ATTACHURLPATH%/renderTableDataExample_thumb.gif" alt="View edit and render example" width='198' height='203' /></a>

[[%ATTACHURLPATH%/renderTableDataExample.png][View large image]] | see Sandbox.RenderTableDataPluginExample
</div>

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

<verbatim>
%TABLEDATA{
   web="..."
   topic="..."
   id="..."
   format="..."
   separator="..."
   rows="..."
   cols="..."
   show="..."
   preservespaces="on"
   escapequotes="off"
   sortdirection="descending"
   sortcolumn="..."
   filter="random"
   beforetext="..."
   aftertext="..."
}%
</verbatim>
Any one of the parameters is optional.

---+++ Parameters

%TABLE{columnwidths="10%,50%,20%,20%"}%
| *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 =%<nop>TABLE{id="xxx"}%= parameter. | =none= (uses the first table in the topic) | =id="wines"= |
| =format=    | Format string to render the table row. Format parameters: %BR%%BR% \
*Get cell data* %BR% \
=$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=. %BR%%BR% \
*Limit characters* %BR% \
=$Cn(m)= limit rendered cell text to a maximum number of characters as indicated by number =m=. %BR% \
=$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. %BR%%BR% \
*Evaluate cell value* %BR% \
=$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 =\"=. %BR% \
=$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. %BR% 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. %BR% If sorting is used, sorting takes place before limiting the display by =show=. %BR% \
Start counting from the end by using a negative number: =show="-5.."= will start 5 positions from the end counting up to the end. %BR% \
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. %BR% 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. %BR% 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 %SYSTEMWEB%.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]]

%IF{"context RenderTablePluginEnabled" then="" else="!RenderTablePlugin is not installed. To see the examples below follow the installation instructions."}%

---+++ Data from a table in this topic

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

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

Results in:

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

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

---+++ Data from another topic
<verbatim>
%TABLEDATA{
topic="%SYSTEMWEB%.TWikiMetaData"
rows="2.."
format="   * *$C1*
      * _$C2_"
separator="$n()"      
sortcolumn="1"
beforetext="---+++!! TOPICINFO $n()"
aftertext="From [[%SYSTEMWEB%.TWikiMetaData#META_TOPICINFO][TWikiMetaData]]"
}%
</verbatim>

Results in:

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

<noautolink>
%EDITTABLE{format="| date,9 | text,30 | text,30 | text,30 |" quietsave="off"}%
%TABLE{id="dates"}%
| *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 |
</noautolink>

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

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

#PluginTest
---++ Plugin Test

   * This plugin is %IF{"context RenderTableDataPluginEnabled" then='%GREEN%enabled%ENDCOLOR%' else ='%RED%not enabled%ENDCOLOR%'}%.

---++ 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 ==%TOPIC%.zip== in your ($TWIKI_ROOT) directory.
      
---++ Plugin Info

|  Authors: | TWiki:Main.ArthurClemens |
|  Copyright: | &copy; 2007-2008 Arthur Clemens, %BR% &copy; 2007-2010 TWiki:TWiki.TWikiContributor |
|  License: | [[http://www.gnu.org/copyleft/gpl.html][GPL]] |
|  Dependencies: | None |
|  Plugin Version: | 19252 (2010-07-25) |
|  History: | <!-- specify latest version first -->&nbsp; |
|  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/%TOPIC% |
| Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
| Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

%META:FILEATTACHMENT{name="renderTableDataExample.png" attachment="renderTableDataExample.png" attr="" comment="Edit and render example" date="1173012452" path="renderTableDataExample.png" size="217811" stream="renderTableDataExample.png" user="Main.TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="renderTableDataExample_thumb.gif" attachment="renderTableDataExample_thumb.gif" attr="h" comment="Thumbnail to example image" date="1173012479" path="renderTableDataExample_thumb.gif" size="18396" stream="renderTableDataExample_thumb.gif" user="Main.TWikiContributor" version="1"}%
