TWiki/EditTablePlugin.mdwn

   1 # <a name="Edit Table Plugin"></a><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 are editable, but only one at a time can be edited.
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Per Table Settings"> Per Table Settings</a></li>
   8     <li><a href="#Table Buttons"> Table Buttons</a></li>
   9     <li><a href="#Examples"> Examples</a><ul>
  10         <li><a href="#Date Field Type"> Date Field Type</a></li>
  11       </ul>
  12     </li>
  13     <li><a href="#Plugin Settings"> Plugin Settings</a></li>
  14     <li><a href="#Limitations and Known Issues"> Limitations and Known Issues</a></li>
  15     <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
  16     <li><a href="#License"> License</a></li>
  17     <li><a href="#Plugin Info"> Plugin Info</a></li>
  18   </ul>
  19 </div>
  20
  21 ## <a name="Per Table Settings"></a> Per Table Settings
  22
  23 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:
  24
  25 <table border="1" cellpadding="0" cellspacing="0">
  26   <tr>
  27     <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
  28     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
  29     <th bgcolor="#99CCCC"><strong> Default </strong></th>
  30   </tr>
  31   <tr>
  32     <td><code>header</code></td>
  33     <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>
  34     <td> (no header) </td>
  35   </tr>
  36   <tr>
  37     <td><code>format</code></td>
  38     <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:%BR% - Text input field (1 line):%BR%   <code>| text, &lt;size&gt;, &lt;initial value&gt; |</code> %BR% - Textarea input field:%BR%   <code>| textarea, &lt;rows&gt;x&lt;columns&gt;, &lt;initial value&gt; |</code> %BR% - Drop down box: %BR%   <code>| select, &lt;size&gt;, &lt;option 1&gt;, &lt;option 2&gt;, etc |</code> %BR% - Fixed label: %BR%   <code>| label, 0, &lt;label text&gt; |</code> %BR% - Row number: %BR%   <code>| row, &lt;offset&gt; |</code> %BR% - Date: %BR%   <code>| date, &lt;size&gt;, &lt;initial value&gt;, &lt;DHTML date format&gt; |</code></td>
  39     <td><code>"text, 16"</code> %BR% for all cells </td>
  40   </tr>
  41   <tr>
  42     <td><code>changerows</code></td>
  43     <td> Rows can be added and removed if <code>"on"</code>;<br /> Rows can be added but not removed if <code>"add"</code></td>
  44     <td><code>CHANGEROWS</code> %BR% Plugin setting </td>
  45   </tr>
  46   <tr>
  47     <td><code>include</code></td>
  48     <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>
  49     <td> (none) </td>
  50   </tr>
  51   <tr>
  52     <td><code>helptopic</code></td>
  53     <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>
  54     <td> (no help text) </td>
  55   </tr>
  56 </table>
  57
  58 **_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:
  59
  60 <table border="1" cellpadding="0" cellspacing="0">
  61   <tr>
  62     <th bgcolor="#99CCCC"><strong> Text: </strong></th>
  63     <th bgcolor="#99CCCC"><strong> To Escape: </strong></th>
  64   </tr>
  65   <tr>
  66     <td><code>$quot</code></td>
  67     <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
  68   </tr>
  69   <tr>
  70     <td><code>$percnt</code></td>
  71     <td> Percent sign (<code>%</code>) </td>
  72   </tr>
  73   <tr>
  74     <td><code>$dollar</code></td>
  75     <td> Dollar sign (<code>$</code>) </td>
  76   </tr>
  77   <tr>
  78     <td><code>$nop</code> or <code>$nop()</code></td>
  79     <td> Is a "no operation" </td>
  80   </tr>
  81 </table>
  82
  83 ## <a name="Table Buttons"></a> Table Buttons
  84
  85 <form>
  86   <ul>
  87     <li> In page view mode: <ul>
  88         <li><input name="et" onclick="return(false);" type="submit" value="Edit table" /> - turn the table into edit mode </li>
  89       </ul>
  90     </li>
  91     <li> In edit mode: <ul>
  92         <li><input name="etsave" onclick="return(false);" type="submit" value="Save table" /> - save your changes </li>
  93         <li><input name="etqsave" onclick="return(false);" type="submit" value="Quiet save" /> - save your changes without alerting subscribed [[Main/WebNotify]] users </li>
  94         <li><input name="etaddrow" onclick="return(false);" type="submit" value="Add row" /> - add row to the table (if enabled) </li>
  95         <li><input name="etdelrow" onclick="return(false);" type="submit" value="Delete last row" /> - remove last row from the table (if enabled) </li>
  96         <li><input name="etcancel" onclick="return(false);" type="submit" value="Cancel" /> - cancel without saving and release edit lock </li>
  97       </ul>
  98     </li>
  99   </ul>
 100 </form>
 101
 102 ## <a name="Examples"></a> Examples
 103
 104 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>
 105
 106 <div>
 107   <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">
 108       <tr>
 109         <th bgcolor="#99CCCC"><strong> Nr </strong></th>
 110         <th bgcolor="#99CCCC"><strong> Text field sandbox </strong></th>
 111         <th bgcolor="#99CCCC"><strong> Drop down sandbox </strong></th>
 112         <th bgcolor="#99CCCC"><strong> Timestamp </strong></th>
 113       </tr>
 114       <tr>
 115         <td> 1 </td>
 116         <td> hello table </td>
 117         <td> one </td>
 118         <td> 26 Jun 2002 12:30 </td>
 119       </tr>
 120       <tr>
 121         <td> 2 </td>
 122         <td>   </td>
 123         <td> two </td>
 124         <td> 27 Jun 2002 12:40 </td>
 125       </tr>
 126     </table><input name="etrows" type="hidden" value="3" /> <input type="submit" value="Edit table" /></form>
 127 </div>
 128
 129 If this plugin is installed you will see an **[ Edit table ]** button above; when you click on it you get this form:
 130
 131 <form>
 132   <table border="1" cellpadding="0" cellspacing="1">
 133     <tr>
 134       <th bgcolor="#99CCCC"> Nr </th>
 135       <th bgcolor="#99CCCC"> Text field sandbox </th>
 136       <th bgcolor="#99CCCC"> Drop down sandbox </th>
 137       <th bgcolor="#99CCCC"> Timestamp </th>
 138     </tr>
 139     <tr>
 140       <td bgcolor="#FFFFFF"> 1<input name="etcell2x1" type="hidden" value="1" /></td>
 141       <td bgcolor="#FFFFFF"><input name="etcell2x2" size="20" type="text" value="hello table" /></td>
 142       <td bgcolor="#FFFFFF"><select name="etcell2x3" size="1"><option selected>one</option>
 143           <option>two</option>
 144           <option>three</option>
 145           <option>four</option></select></td>
 146       <td bgcolor="#FFFFFF"> 26 Jun 2002 12:30<input name="etcell2x4" type="hidden" value="26 Jun 2002 12:30" /></td>
 147     </tr>
 148     <tr>
 149       <td bgcolor="#FFFF99"> 2<input name="etcell3x1" type="hidden" value="2" /></td>
 150       <td bgcolor="#FFFF99"><input name="etcell3x2" size="20" type="text" value="" /></td>
 151       <td bgcolor="#FFFF99"><select name="etcell3x3" size="1"><option>one</option>
 152           <option selected>two</option>
 153           <option>three</option>
 154           <option>four</option></select></td>
 155       <td bgcolor="#FFFF99"> 27 Jun 2002 12:40<input name="etcell3x4" type="hidden" value="27 Jun 2002 12:40" /></td>
 156     </tr>
 157   </table><input name="etsave" onclick="return(false);" type="submit" value="Save table" /> <input name="etqsave" onclick="return(false);" type="submit" value="Quiet save" /> <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>
 158
 159 ### <a name="Date Field Type"></a> Date Field Type
 160
 161 <img src="http://www.dementia.org/twiki//view/EditTablePluginCalendarExample.gif" width="549" height="210" alt="Edit Table Calendar Example" /> The `date` field type allows one to choose a date with a popup calendar. Popup calendar works for Netscape 6.0 or better, all other Gecko-based browsers, Internet Explorer 5.0 or better for Windows, Opera 7 and Konqueror 3.1.2. The `...` button is inactive if the browser cannot support the popup calendar. It uses the nice [Mishoo DHTML calendar](http://dynarch.com/mishoo/calendar.epl), see also TWiki:Codev/JavaScriptDatePickerForForm <br />
 162
 163 ## <a name="Plugin Settings"></a> Plugin Settings
 164
 165 Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%&lt;plugin&gt;\_&lt;setting&gt;%**</code>, for example, <code>**%EDITTABLEPLUGIN\_SHORTDESCRIPTION%**</code>
 166
 167 - One line description, shown in the [[TextFormattingRules]] topic:
 168   - Set SHORTDESCRIPTION = Edit TWiki tables using edit fields and drop down boxes
 169
 170 - Set DEBUG to 1 to get debug messages in `data/debug.txt`. Default: `0`
 171   - Set DEBUG = 0
 172
 173 - Default for change rows flag: `on`, `off`, `add`
 174   - Set CHANGEROWS = on
 175
 176 - Date format of [Mishoo DHTML calendar](http://dynarch.com/mishoo/calendar.epl):
 177   - Set JSCALENDARDATEFORMAT = %Y/%m/%d
 178
 179 - Language of DHTML calendar, pointing to attached `calendar-<code>.js` language file: `en`, `af`, `br`, `ca`, `cs-win`, `da`, `de`, `du`, `el`, `es`, `fr`, `hr`, `hr-utf8`, `hu`, `it`, `jp`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sk`, `sp`, `sv`, `tr`, `zh`
 180   - Set JSCALENDARLANGUAGE = en
 181
 182 - Additional options of DHTML calendar:
 183   - Set JSCALENDAROPTIONS =
 184
 185 **_Note:_** The Plugin looks for the `JSCALENDAR*` settings first in the TWiki Preferences, then in above Plugin settings
 186
 187 ## <a name="Limitations and Known Issues"></a> Limitations and Known Issues
 188
 189 - This Plugin does not support TWiki table formatting like Multi-span cells (e.g. `| ... ||`) and cell justification (e.g. `|  centered  |   right |`).
 190 - There is a performance issue when editing a large table, say, with more then 50 rows.
 191 - 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
 192 - Variables like `%ATTACHURL%` get expanded unless they are in a label.
 193 - %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.
 194 - You cannot put two %EDITTABLE% statements on the same line in the source.
 195 - 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%`
 196
 197 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
 198
 199 **_Note:_** You do not need to install anything on the browser to use this Plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
 200
 201 - Download the ZIP file from the Plugin web (see below)
 202 - Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
 203   <tr>
 204     <th bgcolor="#99CCCC"><strong> File: </strong></th>
 205     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
 206   </tr>
 207   <tr>
 208     <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
 209     <td> Plugin topic </td>
 210   </tr>
 211   <tr>
 212     <td><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
 213     <td> Plugin topic repository </td>
 214   </tr>
 215   <tr>
 216     <td><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
 217     <td> Plugin Perl module </td>
 218   </tr>
 219 </table>
 220 - 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.
 221 - The Mishoo DHTML calendar 0.9.5 is preinstalled and should work without any configuration. If you wish to use another language, specify the in the Plugin settings, or create a new language files, attach it to the Plugin topic, and change the Plugin settings
 222 - Test if the Plugin is correctly installed:
 223   - Check above example if there is an **[ Edit table ]** button below the table in above example
 224   - Click on **[ Edit table ]**, make changes and save the table
 225
 226 ## <a name="License"></a> License
 227
 228 - The Edit Table Plugin is released under the [GPL](http://www.gnu.org/licenses/gpl.html)
 229 - The [Mishoo DHTML calendar](http://dynarch.com/mishoo/calendar.epl) bundled with this Plugin was created by Mihai Bazon and is released under the [LGPL](http://www.gnu.org/licenses/lgpl.html) -- thanks Mihai for the great tool :-)
 230
 231 ## <a name="Plugin Info"></a> Plugin Info
 232
 233 <table border="1" cellpadding="0" cellspacing="0">
 234   <tr>
 235     <td align="right"> Plugin Author: </td>
 236     <td> TWiki:Main/PeterThoeny </td>
 237   </tr>
 238   <tr>
 239     <td align="right"> Plugin Version: </td>
 240     <td> 20 Dec 2003 </td>
 241   </tr>
 242   <tr>
 243     <td align="right"> Change History: </td>
 244     <td>  </td>
 245   </tr>
 246   <tr>
 247     <td align="right"> 20 Dec 2003: </td>
 248     <td> Fixed bug where calendar did not work after adding a row (TWiki:Main/PaulineCheung); added all language files of Mishoo DHTML calendar 0.9.5 </td>
 249   </tr>
 250   <tr>
 251     <td align="right"> 13 Dec 2003: </td>
 252     <td> Added CHANGEROWS, JSCALENDARDATEFORMAT, JSCALENDARLANGUAGE, JSCALENDAROPTIONS settings </td>
 253   </tr>
 254   <tr>
 255     <td align="right"> 16 Oct 2003: </td>
 256     <td> small typo fixed (garbled if ---+ header on top) </td>
 257   </tr>
 258   <tr>
 259     <td align="right"> 15 Oct 2003: </td>
 260     <td> new date field type with javascript calendar - CN </td>
 261   </tr>
 262   <tr>
 263     <td align="right"> 14 Oct 2003: </td>
 264     <td> docfix: the documentation page was an old one - CN </td>
 265   </tr>
 266   <tr>
 267     <td align="right"> 13 Oct 2003: </td>
 268     <td> bugfix: %-vars in select were resetted to first on add/del row - CN </td>
 269   </tr>
 270   <tr>
 271     <td align="right"> 18 Sep 2003: </td>
 272     <td> incompatibility: changed default of <code>changerows</code> to <code>on</code>; support for %-vars, Quiet save for saving without notification; all other fixes in Dev topic integrated - CN </td>
 273   </tr>
 274   <tr>
 275     <td align="right"> 08 Nov 2002: </td>
 276     <td> Prevent variable expansion in label text; added escape characters </td>
 277   </tr>
 278   <tr>
 279     <td align="right"> 27 Jun 2002: </td>
 280     <td> New <code>helptopic</code> parameter </td>
 281   </tr>
 282   <tr>
 283     <td align="right"> 26 Jun 2002: </td>
 284     <td> Support for variables in included EDITTABLE parameters; fixed problem with HTML in cells </td>
 285   </tr>
 286   <tr>
 287     <td align="right"> 21 May 2002: </td>
 288     <td> Added fixed label format; new <code>changerows="add"</code> parameter </td>
 289   </tr>
 290   <tr>
 291     <td align="right"> 27 Apr 2002: </td>
 292     <td> Fixed bug where text after a double quote in a cell disappeared </td>
 293   </tr>
 294   <tr>
 295     <td align="right"> 18 Apr 2002: </td>
 296     <td> Fixed bug where table was breaking when pasting multiple lines into an edit field using Netscape on Unix </td>
 297   </tr>
 298   <tr>
 299     <td align="right"> 08 Apr 2002: </td>
 300     <td> Check for change permission and edit lock of topic </td>
 301   </tr>
 302   <tr>
 303     <td align="right"> 05 Apr 2002: </td>
 304     <td> Initial version </td>
 305   </tr>
 306   <tr>
 307     <td align="right"> CPAN Dependencies: </td>
 308     <td> none </td>
 309   </tr>
 310   <tr>
 311     <td align="right"> Other Dependencies: </td>
 312     <td><a href="http://dynarch.com/mishoo/calendar.epl" target="_top">Mishoo DHTML calendar</a> (version 0.9.5 preinstalled) </td>
 313   </tr>
 314   <tr>
 315     <td align="right"> Perl Version: </td>
 316     <td> 5.0 </td>
 317   </tr>
 318   <tr>
 319     <td align="right"> Plugin Home: </td>
 320     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
 321   </tr>
 322   <tr>
 323     <td align="right"> Feedback: </td>
 324     <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>
 325   </tr>
 326 </table>
 327
 328 **_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
 329
 330 -- TWiki:Main/PeterThoeny - 20 Dec 2003