TWiki/TablePlugin.mdwn

   1 # <a name="Table Plugin"></a> Table Plugin
   2
   3 Gives extra control of table display:
   4
   5 - Allows sorting
   6 - Changing table properties like border width, cell spacing and cell padding
   7 - Changing background color for header cells
   8 - Changing background color for data cells - colors can _alternate_
   9 - Behaviour can be specified for a specific table using %TABLE\{...\}% or with global preferences
  10
  11 ## <a name="%TOPIC% Global Settings"></a> %TOPIC% Global Settings
  12
  13 Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%&lt;plugin&gt;\_&lt;setting&gt;%**</code>, for example, <code>**%INTERWIKIPLUGIN\_SHORTDESCRIPTION%**</code>
  14
  15 - One line description, shown in the [[TextFormattingRules]] topic:
  16   - Set SHORTDESCRIPTION = Control attributes of tables and sorting of table columns
  17
  18 - Set DEBUG to 1 to get debug messages in `data/debug.txt`. Default: `0`
  19   - Set DEBUG = 0
  20
  21 - Table border width. Default: 1
  22   - Set TABLEBORDER = 1
  23
  24 - Table cell padding. Default: 0
  25   - Set CELLPADDING = 0
  26
  27 - Table cell spacing. Default: 1
  28   - Set CELLSPACING = 1
  29
  30 - Vertical alignment of cells. Set to: `top`, `middle`, `bottom` or `baseline`; default: (empty)
  31   - Set VALIGN =
  32
  33 - Table header cell alignment. Set to: `left`, `center`, `right` or `justify`; default: (empty)
  34   - Set HEADERALIGN =
  35
  36 - Table data cell alignment. Set to: `left`, `center`, `right` or `justify`; default: (empty)
  37   - Set DATAALIGN =
  38
  39 - Color for header cells ('\*'s around text). Default: <span>\#99CCCC</span>
  40   - #Set HEADER\_BG = red
  41
  42 - Background color for table rows, two alternate colors. Default: <span>\#FFFFCC</span>,<span>\#FFFFFF</span>
  43   - Set DATA\_BG = #FFFFCC,#FFFFFF
  44
  45 - Make sortable:
  46   - #Set SORT = attachments
  47   - Set SORT = all
  48   - #Set SORT = none
  49
  50 ## <a name="Sorting"></a> Sorting
  51
  52 Click on column heading text to sort by a column. Initial column will be sorted in descending order, click again to get ascending order. The type of data in the cell is determined automatically:
  53
  54 - date if format is:
  55   - dd MMM YYY - hh:mm
  56   - dd-MMM-YY or dd-MM-YYYY (can be / or space in place of -)
  57   - MMM is Jan, Feb, etc
  58 - number is digits, with optional decimal point
  59 - otherwise treated as text
  60
  61 ## <a name="Per Table Settings"></a> Per Table Settings
  62
  63 On line before the table use `%TABLE{...}%`:
  64
  65 <table border="1" cellpadding="0" cellspacing="0" style="border-width: 1px">
  66   <tr>
  67     <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=0;table=1;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Argument</font></a></th>
  68     <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=1;table=1;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Comment</font></a></th>
  69     <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=2;table=1;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Example</font></a></th>
  70   </tr>
  71   <tr>
  72     <td bgcolor="#ecf2f8" style=""><code>sort</code></td>
  73     <td bgcolor="#ecf2f8" style=""> Set table sorting <code>on</code> or <code>off</code></td>
  74     <td bgcolor="#ecf2f8" style=""><code>sort="on"</code></td>
  75   </tr>
  76   <tr>
  77     <td bgcolor="#ffffff" style=""><code>headerbg</code></td>
  78     <td bgcolor="#ffffff" style=""> Header cell background colour </td>
  79     <td bgcolor="#ffffff" style=""><code>headerbg="#99CCCC"</code></td>
  80   </tr>
  81   <tr>
  82     <td bgcolor="#ecf2f8" style=""><code>databg</code></td>
  83     <td bgcolor="#ecf2f8" style=""> Data cell background colour, a comma seperated list </td>
  84     <td bgcolor="#ecf2f8" style=""><code>databg="#C8CB8F,#DBDDB5"</code></td>
  85   </tr>
  86   <tr>
  87     <td bgcolor="#ffffff" style=""><code>tableborder</code></td>
  88     <td bgcolor="#ffffff" style=""> Table border width (pixels) </td>
  89     <td bgcolor="#ffffff" style=""><code>tableborder="2"</code></td>
  90   </tr>
  91   <tr>
  92     <td bgcolor="#ecf2f8" style=""><code>cellpadding</code></td>
  93     <td bgcolor="#ecf2f8" style=""> Cell padding (pixels) </td>
  94     <td bgcolor="#ecf2f8" style=""><code>cellpadding="0"</code></td>
  95   </tr>
  96   <tr>
  97     <td bgcolor="#ffffff" style=""><code>cellspacing</code></td>
  98     <td bgcolor="#ffffff" style=""> Cell spacing (pixels) </td>
  99     <td bgcolor="#ffffff" style=""><code>cellspacing="3"</code></td>
 100   </tr>
 101   <tr>
 102     <td bgcolor="#ecf2f8" style=""><code>valign</code></td>
 103     <td bgcolor="#ecf2f8" style=""> Vertical alignment of cells, set to <code>top</code>, <code>middle</code>, <code>bottom</code> or <code>baseline</code></td>
 104     <td bgcolor="#ecf2f8" style=""><code>valign="top"</code></td>
 105   </tr>
 106   <tr>
 107     <td bgcolor="#ffffff" style=""><code>headeralign</code></td>
 108     <td bgcolor="#ffffff" style=""> Header cell alignment, set to <code>left</code>, <code>center</code>, <code>right</code> or <code>justify</code>. Overrides individual cell settings </td>
 109     <td bgcolor="#ffffff" style=""><code>headeralign="left"</code></td>
 110   </tr>
 111   <tr>
 112     <td bgcolor="#ecf2f8" style=""><code>dataalign</code></td>
 113     <td bgcolor="#ecf2f8" style=""> Data cell alignment, set to <code>left</code>, <code>center</code>, <code>right</code> or <code>justify</code>. Overrides individual cell settings </td>
 114     <td bgcolor="#ecf2f8" style=""><code>dataalign="center"</code></td>
 115   </tr>
 116 </table>
 117
 118 All default to the global setting
 119
 120 ## <a name="Examples"></a> Examples
 121
 122 Line before table: `%TABLE{sort="on" tableborder="0" cellpadding="1" cellspacing="3" headerbg="#99CCCC" databg="#C8CB8F,#DBDDB5"}%`
 123
 124 <table border="0" cellpadding="1" cellspacing="3" style="border-width: 0px">
 125   <tr>
 126     <th bgcolor="#99CCCC" maxcols="0" style=""><a href="http://localhost?sortcol=0;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Num</font></a></th>
 127     <th bgcolor="#99CCCC" maxcols="0" style=""><a href="http://localhost?sortcol=1;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Status</font></a></th>
 128     <th bgcolor="#99CCCC" maxcols="0" style=""><a href="http://localhost?sortcol=2;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Action</font></a></th>
 129     <th bgcolor="#99CCCC" maxcols="0" style=""><a href="http://localhost?sortcol=3;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Who</font></a></th>
 130     <th bgcolor="#99CCCC" maxcols="0" style=""><a href="http://localhost?sortcol=4;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">When</font></a></th>
 131     <th bgcolor="#99CCCC" maxcols="0" style=""><a href="http://localhost?sortcol=5;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Progress</font></a></th>
 132   </tr>
 133   <tr>
 134     <td bgcolor="#C8CB8F" style=""> 1 </td>
 135     <td bgcolor="#C8CB8F" style=""> C </td>
 136     <td bgcolor="#C8CB8F" style=""> Chose new colours </td>
 137     <td bgcolor="#C8CB8F" style=""> John </td>
 138     <td bgcolor="#C8CB8F" style=""> 1-Dec-02 </td>
 139     <td bgcolor="#C8CB8F" style="">   </td>
 140   </tr>
 141   <tr>
 142     <td bgcolor="#DBDDB5" style=""> 2 </td>
 143     <td bgcolor="#DBDDB5" style=""> X </td>
 144     <td bgcolor="#DBDDB5" style=""> Release </td>
 145     <td bgcolor="#DBDDB5" style=""> John </td>
 146     <td bgcolor="#DBDDB5" style=""> 1-Apr-02 </td>
 147     <td bgcolor="#DBDDB5" style="">   </td>
 148   </tr>
 149   <tr>
 150     <td bgcolor="#C8CB8F" style=""> 3 </td>
 151     <td bgcolor="#C8CB8F" style="">   </td>
 152     <td bgcolor="#C8CB8F" style=""> Get feedback </td>
 153     <td bgcolor="#C8CB8F" style=""> Anne </td>
 154     <td bgcolor="#C8CB8F" style=""> 1-Feb-02 </td>
 155     <td bgcolor="#C8CB8F" style="">   </td>
 156   </tr>
 157   <tr>
 158     <td bgcolor="#DBDDB5" style=""> 12 </td>
 159     <td bgcolor="#DBDDB5" style=""> C </td>
 160     <td bgcolor="#DBDDB5" style=""> Spec error handling </td>
 161     <td bgcolor="#DBDDB5" style=""> Jack </td>
 162     <td bgcolor="#DBDDB5" style=""> 1-Dec-02 </td>
 163     <td bgcolor="#DBDDB5" style="">   </td>
 164   </tr>
 165   <tr>
 166     <td bgcolor="#C8CB8F" style=""> 5 </td>
 167     <td bgcolor="#C8CB8F" style="">   </td>
 168     <td bgcolor="#C8CB8F" style=""> Abc </td>
 169     <td bgcolor="#C8CB8F" style=""> John </td>
 170     <td bgcolor="#C8CB8F" style="">   </td>
 171     <td bgcolor="#C8CB8F" style="">   </td>
 172   </tr>
 173 </table>
 174
 175 ### <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
 176
 177 - Download the ZIP file from the Plugin web (see below)
 178 - Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0" style="border-width: 1px">
 179   <tr>
 180     <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=0;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">File:</font></a></th>
 181     <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=1;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Description:</font></a></th>
 182   </tr>
 183   <tr>
 184     <td bgcolor="#ecf2f8" style=""><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
 185     <td bgcolor="#ecf2f8" style=""> Plugin topic </td>
 186   </tr>
 187   <tr>
 188     <td bgcolor="#ffffff" style=""><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
 189     <td bgcolor="#ffffff" style=""> Plugin topic repository </td>
 190   </tr>
 191   <tr>
 192     <td bgcolor="#ecf2f8" style=""><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
 193     <td bgcolor="#ecf2f8" style=""> Plugin Perl module </td>
 194   </tr>
 195   <tr>
 196     <td bgcolor="#ffffff" style=""><code><b>pub/TWiki/%TOPIC%/diamond.gif</b></code></td>
 197     <td bgcolor="#ffffff" style=""> Diamond symbol </td>
 198   </tr>
 199   <tr>
 200     <td bgcolor="#ecf2f8" style=""><code><b>pub/TWiki/%TOPIC%/down.gif</b></code></td>
 201     <td bgcolor="#ecf2f8" style=""> Down arrow </td>
 202   </tr>
 203   <tr>
 204     <td bgcolor="#ffffff" style=""><code><b>pub/TWiki/%TOPIC%/up.gif</b></code></td>
 205     <td bgcolor="#ffffff" style=""> Up arrow </td>
 206   </tr>
 207 </table>
 208 - Test if the plugin is correctly installed:
 209   - Check above example if the table renders as expected
 210   - Try click on heading to sort. Other tables should also be sortable
 211
 212 ### <a name="Plugin Info"></a> Plugin Info
 213
 214 <table border="1" cellpadding="0" cellspacing="0" style="border-width: 1px">
 215   <tr>
 216     <td align="right" bgcolor="#ecf2f8" style=""> Plugin Author: </td>
 217     <td bgcolor="#ecf2f8" style="">[[TWiki/JohnTalintyre]]</td>
 218   </tr>
 219   <tr>
 220     <td align="right" bgcolor="#ffffff" style=""> Plugin Version: </td>
 221     <td bgcolor="#ffffff" style=""> 07 Mar 2002 </td>
 222   </tr>
 223   <tr>
 224     <td align="right" bgcolor="#ecf2f8" style=""> Change History: </td>
 225     <td bgcolor="#ecf2f8" style=""> 07 Mar 2002 PTh: Added valign, headeralign and dataalign; fixed swapped cellpadding/cellspacing bug <br /> 05 Jan 2002 PTh: Fixed sorting bug of cells with leading white space <br /> 06 Dec 2001 PTh: Fixed date sorting bug <br /> 03 Dec 2001 PTh: Fixed sort="off" bug and more <br /> 29 Nov 2001: PTh fixed Perl warnings <br /> 16 Nov 2001: PTh added table border, cell spacing, cell padding, gif files <br /> 07 Oct 2001: Initial version </td>
 226   </tr>
 227   <tr>
 228     <td align="right" bgcolor="#ffffff" style=""> CPAN Dependencies: </td>
 229     <td bgcolor="#ffffff" style=""> none </td>
 230   </tr>
 231   <tr>
 232     <td align="right" bgcolor="#ecf2f8" style=""> Other Dependencies: </td>
 233     <td bgcolor="#ecf2f8" style=""> none </td>
 234   </tr>
 235   <tr>
 236     <td align="right" bgcolor="#ffffff" style=""> Perl Version: </td>
 237     <td bgcolor="#ffffff" style=""> 5.0 </td>
 238   </tr>
 239   <tr>
 240     <td align="right" bgcolor="#ecf2f8" style=""> Plugin Home: </td>
 241     <td bgcolor="#ecf2f8" style=""><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
 242   </tr>
 243   <tr>
 244     <td align="right" bgcolor="#ffffff" style=""> Feedback: </td>
 245     <td bgcolor="#ffffff" style=""><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
 246   </tr>
 247 </table>
 248
 249 **_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
 250
 251 -- [[JohnTalintyre]] - 07 Oct 2001 <br /> -- [[PeterThoeny]] - 07 Mar 2002 <br />