TWiki/EditTablePlugin.mdwn

   1 # <a name="Edit Table Plugin"></a> Edit Table Plugin
   2
   3 This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an **[ Edit table ]** button if preceeded by an `%EDITTABLE{...}%` variable. Each column can be a text field, a drop down box or a row number. Multiple tables per topic can be editable, but only one at a time canbe edited.
   4
   5 ## <a name="%TOPIC% Global Settings"></a> %TOPIC% Global Settings
   6
   7 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>
   8
   9 - One line description, shown in the [[TextFormattingRules]] topic:
  10   - Set SHORTDESCRIPTION = Edit TWiki tables using edit fields and drop down boxes.
  11
  12 - Set DEBUG to 1 to get debug messages in `data/debug.txt`. Default: `0`
  13   - Set DEBUG = 0
  14
  15 ## <a name="Per Table Settings"></a> Per Table Settings
  16
  17 Add a `%EDITTABLE{...}%` variable just before an existing table to make it editable, or add the variable anywhere in a topic to start a new table. Parameters:
  18
  19 <table border="1" cellpadding="0" cellspacing="0">
  20   <tr>
  21     <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
  22     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
  23     <th bgcolor="#99CCCC"><strong> Default </strong></th>
  24   </tr>
  25   <tr>
  26     <td><code>header</code></td>
  27     <td> Enable static header if <code>"on"</code>, e.g. disable editing of the first row;<br /> Else specify the header format of a new table like <code>"|*Food*|*Drink*|"</code>. </td>
  28     <td> (no header) </td>
  29   </tr>
  30   <tr>
  31     <td><code>format</code></td>
  32     <td> The format of one row when editing the table. A cell can be a text input field, a drop down box, a fixed label, or a row number. Cell definitions: <table cellpadding="0" cellspacing="0">
  33         <tr>
  34           <td valign="top">-Text input field (1 line): </td>
  35           <td><code>| text, &lt;size&gt;, &lt;initial value&gt; |</code></td>
  36         </tr>
  37         <tr>
  38           <td valign="top">-Textarea input field: </td>
  39           <td><code>| textarea, &lt;rows&gt;x&lt;columns&gt;, &lt;initial value&gt; |</code></td>
  40         </tr>
  41         <tr>
  42           <td valign="top">- Drop down box: </td>
  43           <td><code>| select, &lt;size&gt;, &lt;option 1&gt;, &lt;option 2&gt;, etc |</code></td>
  44         </tr>
  45         <tr>
  46           <td valign="top">- Fixed label: </td>
  47           <td><code>| label, 0, &lt;label text&gt; |</code></td>
  48         </tr>
  49         <tr>
  50           <td valign="top">- Row number: </td>
  51           <td><code>| row, &lt;offset&gt; |</code></td>
  52         </tr>
  53         <tr>
  54           <td valign="top">- Date: </td>
  55           <td><code>| date, &lt;sizet&gt; |</code></td>
  56         </tr>
  57       </table>
  58     </td>
  59     <td><code>"text, 16"</code> for all cells </td>
  60   </tr>
  61   <tr>
  62     <td><code>changerows</code></td>
  63     <td> Rows can be added and removed if <code>"on"</code>;<br /> Rows can be added but not removed if <code>"add"</code></td>
  64     <td><code>"on"</code></td>
  65   </tr>
  66   <tr>
  67     <td><code>include</code></td>
  68     <td> Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. </td>
  69     <td> (none) </td>
  70   </tr>
  71   <tr>
  72     <td><code>helptopic</code></td>
  73     <td> Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% variables can be used in the topic to specify what is shown. </td>
  74     <td> (no help text) </td>
  75   </tr>
  76 </table>
  77
  78 **_Note:_** By default, variables in `<initial value>` (of text input field) and `<label text>` (of fixed label) get expanded when a new row is added. This can be used for example to add a timestamp to a label. You can escape characters if you do not want that:
  79
  80 <table border="1" cellpadding="0" cellspacing="0">
  81   <tr>
  82     <th bgcolor="#99CCCC"><strong> Text: </strong></th>
  83     <th bgcolor="#99CCCC"><strong> To Escape: </strong></th>
  84   </tr>
  85   <tr>
  86     <td><code>$quot</code></td>
  87     <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
  88   </tr>
  89   <tr>
  90     <td><code>$percnt</code></td>
  91     <td> Percent sign (<code>%</code>) </td>
  92   </tr>
  93   <tr>
  94     <td><code>$dollar</code></td>
  95     <td> Dollar sign (<code>$</code>) </td>
  96   </tr>
  97   <tr>
  98     <td><code>$nop</code> or <code>$nop()</code></td>
  99     <td> Is a "no operation" </td>
 100   </tr>
 101 </table>
 102
 103 ## <a name="Examples"></a> Examples
 104
 105 Line before table: `%EDITTABLE{ header="|*Nr*|*Text field sandbox*|*Drop down sandbox*|*Timestamp*|" format="| row, -1 | text, 20, init | select, 1, one, two, three, four | label, 0, %SERVERTIME{"$day $mon $year $hour:$min"}% |" changerows="on" }%` <a name="edittable1"></a>
 106
 107 <div>
 108   <form action="http://www.dementia.org/twiki/viewauth#edittable1" method="post" name="edittable1"><input name="ettablenr" type="hidden" value="1" /> <input name="etedit" type="hidden" value="on" /><table border="1" cellpadding="0" cellspacing="0">
 109       <tr>
 110         <th bgcolor="#99CCCC"><strong> Nr </strong></th>
 111         <th bgcolor="#99CCCC"><strong> Text field sandbox </strong></th>
 112         <th bgcolor="#99CCCC"><strong> Drop down sandbox </strong></th>
 113         <th bgcolor="#99CCCC"><strong> Timestamp </strong></th>
 114       </tr>
 115       <tr>
 116         <td> 1 </td>
 117         <td> hello table </td>
 118         <td> one </td>
 119         <td> 26 Jun 2002 12:30 </td>
 120       </tr>
 121       <tr>
 122         <td> 2 </td>
 123         <td>   </td>
 124         <td> two </td>
 125         <td> 27 Jun 2002 12:40 </td>
 126       </tr>
 127     </table><input name="etrows" type="hidden" value="3" /> <input type="submit" value="Edit table" /></form>
 128 </div>
 129
 130 If this plugin is installed you will see an **[ Edit table ]** button above; when you click on it you get this form:
 131
 132 <form>
 133   <table border="1" cellpadding="0" cellspacing="1">
 134     <tr>
 135       <th bgcolor="#99CCCC"> Nr </th>
 136       <th bgcolor="#99CCCC"> Text field sandbox </th>
 137       <th bgcolor="#99CCCC"> Drop down sandbox </th>
 138       <th bgcolor="#99CCCC"> Timestamp </th>
 139     </tr>
 140     <tr>
 141       <td bgcolor="#FFFFFF"> 1<input name="etcell2x1" type="hidden" value="1" /></td>
 142       <td bgcolor="#FFFFFF"><input name="etcell2x2" size="20" type="text" value="hello table" /></td>
 143       <td bgcolor="#FFFFFF"><select name="etcell2x3" size="1"><option selected>one</option>
 144           <option>two</option>
 145           <option>three</option>
 146           <option>four</option></select></td>
 147       <td bgcolor="#FFFFFF"> 26 Jun 2002 12:30<input name="etcell2x4" type="hidden" value="26 Jun 2002 12:30" /></td>
 148     </tr>
 149     <tr>
 150       <td bgcolor="#FFFF99"> 2<input name="etcell3x1" type="hidden" value="2" /></td>
 151       <td bgcolor="#FFFF99"><input name="etcell3x2" size="20" type="text" value="" /></td>
 152       <td bgcolor="#FFFF99"><select name="etcell3x3" size="1"><option>one</option>
 153           <option selected>two</option>
 154           <option>three</option>
 155           <option>four</option></select></td>
 156       <td bgcolor="#FFFF99"> 27 Jun 2002 12:40<input name="etcell3x4" type="hidden" value="27 Jun 2002 12:40" /></td>
 157     </tr>
 158   </table><input name="etsave" onclick="return(false);" type="submit" value="Save table" /> <input name="etqsave" onclick="return(false);" type="submit" value="Quietsave" /> <input name="etaddrow" onclick="return(false);" type="submit" value="Add row" /> <input name="etdelrow" onclick="return(false);" type="submit" value="Delete last row" /> <input name="etcancel" onclick="return(false);" type="submit" value="Cancel" /> (demo only, these buttons do not work) </form>
 159
 160 ## <a name="Limitations and Known Issues"></a> Limitations and Known Issues
 161
 162 - This Plugin does not support TWiki table formatting like Multi-span cells (e.g. `| ... ||`) and cell justification (e.g. `|  centered  |   right |`).
 163 - There is a performance issue when editing a large table, say, with more then 50 rows.
 164 - The Plugin fails if the table is at the very end of the topic (without a new line) Always ensure there is a newline after the table
 165 - Variables like `%ATTACHURL%` get expanded unless they are in a label.
 166 - %RED% **Warning:** %ENDCOLOR% This plugin uses undocumented functions to read, save and lock a topic. The plugin will likely break in a future TWiki release.
 167 - You cannot put two %EDITTABLE% statements on the same line in the source.
 168 - You can include %-vars now in select values, by quoting them with &lt;nop&gt;, as in %&lt;nop&gt;X% for %X%, say for instance: <br />`select,1,%<nop>X%,%<nop>Y%`
 169 - `date` field type for the `format` parameter adds a button popping a javascript calendar to choose the date on browsers supporting it. It uses the nice **Mishoo DHTML calendar** at <http://dynarch.com/mishoo/calendar.epl>, that should be included in Cairo release, or see TWiki:Codev/JavaScriptDatePickerForForm for installing it on Beijing Release
 170
 171 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
 172
 173 - Download the ZIP file from the Plugin web (see below)
 174 - Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
 175   <tr>
 176     <th bgcolor="#99CCCC"><strong> File: </strong></th>
 177     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
 178   </tr>
 179   <tr>
 180     <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
 181     <td> Plugin topic </td>
 182   </tr>
 183   <tr>
 184     <td><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
 185     <td> Plugin topic repository </td>
 186   </tr>
 187   <tr>
 188     <td><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
 189     <td> Plugin Perl module </td>
 190   </tr>
 191 </table>
 192 - The plugin depends on the `viewauth` script to authenticate the user. As described in [[TWikiAccessControl]], copy the `view` script to `viewauth` (or better, create a symbolic link) and add `viewauth` to the list of authenticated scripts in the `.htaccess` file.
 193 - Test if the plugin is correctly installed:
 194   - Check above example if there is an **[ Edit table ]** button below the table in above example
 195   - Click on **[ Edit table ]**, make changes and save the table
 196
 197 ## <a name="Plugin Info"></a> Plugin Info
 198
 199 <table border="1" cellpadding="0" cellspacing="0">
 200   <tr>
 201     <td align="right"> Plugin Author: </td>
 202     <td>[[TWiki/PeterThoeny]]</td>
 203   </tr>
 204   <tr>
 205     <td align="right"> Plugin Version: </td>
 206     <td> 16 Oct 2003 </td>
 207   </tr>
 208   <tr>
 209     <td align="right"> Change History: </td>
 210     <td>  </td>
 211   </tr>
 212   <tr>
 213     <td align="right"> 16 Oct 2003: </td>
 214     <td> small typo fixed (garbled if ---+ header on top) </td>
 215   </tr>
 216   <tr>
 217     <td align="right"> 15 Oct 2003: </td>
 218     <td> new date field type with javascript calendar - CN </td>
 219   </tr>
 220   <tr>
 221     <td align="right"> 14 Oct 2003: </td>
 222     <td> docfix: the documentation page was an old one - CN </td>
 223   </tr>
 224   <tr>
 225     <td align="right"> 13 Oct 2003: </td>
 226     <td> bugfix: %-vars in select were resetted to first on add/del row - CN </td>
 227   </tr>
 228   <tr>
 229     <td align="right"> 18 Sep 2003: </td>
 230     <td><strong>incompatibility:</strong> changed default of <code>changerows</code> to =on=<br /> support for %-vars, Quietsave for saving without notification, all other fixes in Dev topic integrated - CN </td>
 231   </tr>
 232   <tr>
 233     <td align="right"> 08 Nov 2002: </td>
 234     <td> Prevent variable expansion in label text; added escape characters </td>
 235   </tr>
 236   <tr>
 237     <td align="right"> 27 Jun 2002: </td>
 238     <td> New <code>helptopic</code> parameter </td>
 239   </tr>
 240   <tr>
 241     <td align="right"> 26 Jun 2002: </td>
 242     <td> Support for variables in included EDITTABLE parameters; fixed problem with HTML in cells </td>
 243   </tr>
 244   <tr>
 245     <td align="right"> 21 May 2002: </td>
 246     <td> Added fixed label format; new <code>changerows="add"</code> parameter </td>
 247   </tr>
 248   <tr>
 249     <td align="right"> 27 Apr 2002: </td>
 250     <td> Fixed bug where text after a double quote in a cell disappeared </td>
 251   </tr>
 252   <tr>
 253     <td align="right"> 18 Apr 2002: </td>
 254     <td> Fixed bug where table was breaking when pasting multiple lines into an edit field using Netscape on Unix </td>
 255   </tr>
 256   <tr>
 257     <td align="right"> 08 Apr 2002: </td>
 258     <td> Check for change permission and edit lock of topic </td>
 259   </tr>
 260   <tr>
 261     <td align="right"> 05 Apr 2002: </td>
 262     <td> Initial version </td>
 263   </tr>
 264   <tr>
 265     <td align="right"> CPAN Dependencies: </td>
 266     <td> none </td>
 267   </tr>
 268   <tr>
 269     <td align="right"> Other Dependencies: </td>
 270     <td> none </td>
 271   </tr>
 272   <tr>
 273     <td align="right"> Perl Version: </td>
 274     <td> 5.0 </td>
 275   </tr>
 276   <tr>
 277     <td align="right"> Plugin Home: </td>
 278     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
 279   </tr>
 280   <tr>
 281     <td align="right"> Feedback: </td>
 282     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
 283   </tr>
 284 </table>
 285
 286 **_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
 287
 288 -- [[PeterThoeny]] - 08 Nov 2002