none
[openafs-wiki.git] / 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