%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="10"}%


---+!! Edit Table Plugin

This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an *[&nbsp;Edit&nbsp;table&nbsp;]* button if preceeded by an =%<nop>EDITTABLE{...}%= variable. Each column can be a text field, a drop down box, a date field, etc. Multiple tables per topic are editable, but only one at a time can be edited.

%TOC%

---++ Per Table Settings

Add a =%<nop>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:

| *Parameter* | *Comment* | *Default* |
| =header= | Specify the header format of a new table like ="&#124;*Food*&#124;*Drink*&#124;"=. Useful to start a table with only a button | (no header) |
| =format= | The format of one column when editing the table. A cell can be a text input field, or any of these edit field types:%BR% - Text input field (1 line):%BR% &nbsp; =&#124; text, &lt;size&gt;, &lt;initial value&gt; &#124;= %BR% - Textarea input field:%BR% &nbsp; =&#124; textarea, &lt;rows&gt;x&lt;columns&gt;, &lt;initial value&gt; &#124;= %BR% - Drop down box: %BR% &nbsp; =&#124; select, &lt;size&gt;, &lt;option 1&gt;, &lt;option 2&gt;, etc &#124;= %BR% - Fixed label: %BR% &nbsp; =&#124; label, 0, &lt;label text&gt; &#124;= %BR% - Row number: %BR% &nbsp; =&#124; row, &lt;offset&gt; &#124;= %BR% - Date: %BR% &nbsp; =&#124; date, &lt;size&gt;, &lt;initial value&gt;, &lt;DHTML date format&gt; &#124;= | ="text, 16"= %BR% for all cells |
| =changerows= | Rows can be added and removed if ="on"=;<br /> Rows can be added but not removed if ="add"= | =CHANGEROWS= %BR% Plugin setting |
| =quietsave= | Quiet Save button is shown if ="on"=, hidden if ="off"= | =QUIETSAVE= %BR% Plugin setting |
| =include= | Other topic defining the EDITTABLE parameters. The first %<nop>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. | (none) |
| =helptopic= | Topic name containing help text shown below the table when editing a table. The %<nop>STARTINCLUDE% and %<nop>STOPINCLUDE% variables can be used in the topic to specify what is shown. | (no help text) |
| =headerislabel= | Table header cells are read-only (labels) if ="on"=; header cells can be edited if ="off"= or "0" | ="on"= |
| =editbutton= | Set edit button text, e.g. ="Edit this table"=; set button image with alt text, e.g. ="Edit table, %<nop>PUBURL%/%<nop>TWIKIWEB%/TWikiDocGraphics/edittopic.gif"=; hide edit button at the end of the table with ="hide"= (Note: Button is automatically hidden if an edit button is present in a cell) | =EDITBUTTON= %BR% Plugin setting |

---+++ Initial Values

By default, variables in =&lt;initial value&gt;= (of text input field) and =&lt;label text&gt;= (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:
| *Text:* | *To Escape:* |
| =$quot= | Double quote (="=). Alternatively write =\"= to escape it |
| =$percnt= | Percent sign (=%=) |
| =$dollar= | Dollar sign (=$=) |
| =$nop= or =$nop()= | Is a "no operation" |

---+++ Date Field Type

<img src="%ATTACHURLPATH%/EditTablePluginCalendarExample.gif" alt="Edit Table Calendar Example" width="549" height="210" align="left"  />
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 [[http://dynarch.com/mishoo/calendar.epl][Mishoo DHTML calendar]], see also TWiki:Codev/JavaScriptDatePickerForForm <br clear="all">


---++ Per Cell Settings

An individual edit field type can be defined for each table cell. Place an =%<nop>EDITCELL{ "type, ..." }%= variable at the end of the cell content. This is useful to override the per column =%<nop>EDITTABLE{ format="..." }%= settings, or to create tables with key/value rows. All edit field types of the =format="..."= parameter are supported. For example, to define a text field, type: =| cell content %<nop>EDITCELL{ "text, 20" }% |=

It is also possible to place the edit button inside a cell instead of default location below the table. Type =| %<nop>EDITCELL{ "editbutton, 1, Edit this table" }% |= to show a button, or =| %<nop>EDITCELL{ "editbutton, 1, Edit table, Image-URL" }% |= to show a button image with alternate text.

__Note:__ The =%<nop>EDITCELL{ }%=variable cannot be used by itself; place an =%<nop>EDITTABLE{ }%=variable at the beginning of a table where you want to use =%<nop>EDITCELL{ }%= variables.

---++ Table Buttons

<form>
	* In page view mode:
	* <input type="submit" name="et"	value="Edit table" onclick="return(false);" /> - turn the table into edit mode
	* In edit mode:
	* <input type="submit" name="etsave"	value="Save table"  onclick="return(false);" /> - save your changes
	* <input type="submit" name="etqsave"	value="Quiet save"  onclick="return(false);" /> - save your changes without alerting subscribed WebNotify users
	* <input type="submit" name="etaddrow" value="Add row" onclick="return(false);" /> - add row to the table (if enabled)
	* <input type="submit" name="etdelrow" value="Delete last row" onclick="return(false);" /> - remove last row from the table (if enabled)
	* <input type="submit" name="etcancel" value="Cancel" onclick="return(false);" /> - cancel without saving and release edit lock
</form>

---++ Examples

Line before table: =%<nop>EDITTABLE{ header="|*Nr*|*Text field sandbox*|*Drop down sandbox*|*Timestamp*|" format="| row, -1 | text, 20, init | select, 1, one, two, three, four | label, 0, %<nop>SERVERTIME{"$day $mon $year $hour:$min"}% |" changerows="on" }%=
%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" }%
|*Nr*|*Text field sandbox*|*Drop down sandbox*|*Timestamp*|
| 1 | hello table | one | 26 Jun 2002 12:30 |
| 2 |  | two | 27 Jun 2002 12:40 |

%RED% __Note:__ Please use TWiki:Sandbox.EditTablePluginTesting if you want to try out this Plugin %ENDCOLOR%

If this plugin is installed you will see an *[&nbsp;Edit&nbsp;table&nbsp;]* button above; if you were to click on it (please don't, use TWiki:Sandbox.EditTablePluginTesting for testing) you get this form:

<form>
<table border="1" cellspacing="1" cellpadding="0">
<tr><th bgcolor="#99CCCC"> Nr </th><th bgcolor="#99CCCC"> Text field sandbox </th><th bgcolor="#99CCCC"> Drop down sandbox </th><th bgcolor="#99CCCC"> Timestamp </th></tr>
<tr><td  bgcolor="#FFFFFF"> 1<input type="hidden" name="etcell2x1" value="1" />  </td><td  bgcolor="#FFFFFF"> <input type="text" name="etcell2x2" size="20" value="hello table" />  </td><td  bgcolor="#FFFFFF"> <select name="etcell2x3" size="1"> <option selected="selected">one</option> <option>two</option> <option>three</option> <option>four</option> </select>  </td><td  bgcolor="#FFFFFF"> 26 Jun 2002 12:30<input type="hidden" name="etcell2x4" value="26 Jun 2002 12:30" />  </td></tr>
<tr><td  bgcolor="#FFFF99"> 2<input type="hidden" name="etcell3x1" value="2" />  </td><td  bgcolor="#FFFF99"> <input type="text" name="etcell3x2" size="20" value="" />  </td><td  bgcolor="#FFFF99"> <select name="etcell3x3" size="1"> <option>one</option> <option selected="selected">two</option> <option>three</option> <option>four</option> </select>  </td><td  bgcolor="#FFFF99"> 27 Jun 2002 12:40<input type="hidden" name="etcell3x4" value="27 Jun 2002 12:40" />  </td></tr>
</table>
<input type="submit" name="etsave"	value="Save table" onclick="return(false);" />
<input type="submit" name="etqsave"	value="Quiet save"  onclick="return(false);" />
<input type="submit" name="etaddrow" value="Add row" onclick="return(false);" />
<input type="submit" name="etdelrow" value="Delete last row" onclick="return(false);" />
<input type="submit" name="etcancel" value="Cancel" onclick="return(false);" /> (demo only, these buttons do not work)
</form>

The following example shows a simple table with key/value rows. The default edit field type for the value column is a text field. This is overloaded by a selector for the Gender, and a date picker for the DOB. This is typically used by TWiki applications where new topics with tables are created based on a template topic.

<table><tr><td valign="top">
You type:
<pre>
%<nop>EDITTABLE{ format="| label | text, 40 |" }%
|*Key*|*Value*|
| Name: | John Smith |
| Gender: | M %<nop>EDITCELL{select, 1, , F, M}% |
| DOB: | 1999/12/31 %<nop>EDITCELL{date, 10}% |
| City: | New York |
</pre>
</td><td valign="top">
Screenshot:
<img src="%ATTACHURLPATH%/ScreenshotEditCell1.gif" alt="EDITCELL Example in view mode" width="149" height="141" />
</td><td valign="top">
Screenshot in edit mode:
<img src="%ATTACHURLPATH%/ScreenshotEditCell2.gif" alt="EDITCELL Example in edit mode" width="276" height="164" />
</td></tr></table>

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference
a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, for example, ==%<nop>EDITTABLEPLUGIN_SHORTDESCRIPTION%==

	* One line description, shown in the %TWIKIWEB%.TextFormattingRules topic:
	* Set SHORTDESCRIPTION = Edit TWiki tables using edit fields, date pickers and drop down boxes

	* Set DEBUG to 1 to get debug messages in =data/debug.txt=.  Default: =0=
	* Set DEBUG = 0

	* Default for change rows flag: =on=, =off=, =add=
	* Set CHANGEROWS = on

	* Default flag for quiet save option: =on= to show the Quiet Save button, =off= to hide
	* Set QUIETSAVE = on

	* Default edit button: Specify =button text=, or specify =alternate text, image URL=
	* #Set EDITBUTTON = Edit table
	* Set EDITBUTTON = Edit this table, %ATTACHURL%/edittable.gif

---++ Limitations and Known Issues

	* This Plugin does not support TWiki table formatting like Multi-span cells (e.g. =| ... ||=) and cell justification (e.g. =|  centered  |	right |=)
	* There is a performance issue when editing a large table, say, with more then 50 rows
	* Variables like =%<nop>ATTACHURL%= get expanded unless they are in a label
	* You cannot put two =%<nop>EDITTABLE{}%= statements on the same line in the source
	* You can include %-vars now in select values, by quoting them with &lt;nop&gt;, as in %&lt;nop&gt;X% for %<nop>X%, say for instance:
	  <br /> =select,1,%&lt;nop&gt;X%,%&lt;nop&gt;Y%=

---++ Plugin Installation Instructions
This plugin is pre-installed with your TWiki release. You should not need to install it unless you are upgrading to a new version.
	* Download the ZIP file from the Plugin web (see below)
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
	  | *File:* | *Description:* |
	  | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
	  | ==data/TWiki/%TOPIC%.txt,v== | Plugin topic repository |
	  | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
	  | ==lib/TWiki/Plugins/%TOPIC%/Core.pm== | Plugin Core Perl module |
	  | ==pub/TWiki/%TOPIC%/edittable.gif== | Edit table button image |
	  | ==pub/TWiki/%TOPIC%/*.gif== | Screenshots and  Mishoo DHTML calendar images |
	* (Dakar) Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section.
	* The Plugin depends on the =viewauth= script to authenticate the user. As described in %TWIKIWEB%.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. 
	* You need to install TWiki:Plugins/JSCalendarContrib
	* Test if the Plugin is correctly installed:
	* Check above example if there is an *[&nbsp;Edit&nbsp;table&nbsp;]* button below the table in above example
	* Click on *[&nbsp;Edit&nbsp;table&nbsp;]*, make changes and save the table

---++ Style sheet classes
This plugin uses the following CSS classes:
	* =editTable= - a div around the table
	* =editTableEdit= - (appended class) the div when in edit mode
	* =editTableInput= - input field
	* =editTableTextarea= - textarea
	* =editTableEditImageButton= - the image button labeled "Edit"
	* =editTableEditButton= - the button labeled "Edit"
	* =twikiButton= - each button at the bottom when in edit mode
	* =twikiSubmit= - the Save button at the bottom when in edit mode
	
---++ License
	* The Edit Table Plugin is released under the [[http://www.gnu.org/licenses/gpl.html][GPL]]

---++ Plugin Info

|  Plugin Author: | TWiki:Main/PeterThoeny |
|  Plugin Version: | 1.024 |
|  Change History: | <!-- specify latest version first -->&nbsp; |
|  10 Dec 2005: | Added css class names to enable custom styling; see for instance %TWIKIWEB%.PatternSkinCssCookbookEditTableStyle |
|  05 Mar 2005: | 1.024 Crawford Currie changed to use JSCalendarContrib and prepped for Dakar release |
|  01 Aug 2004: | Fixed bug where edittable did not work if at the end of a topic |
|  07 Apr 2004: | Fixed bug where two tables got updated when you edit and save a table included into a topic containing other edit tables |
|  02 Mar 2004: | Default for =%<nop>EDITCELL{editbutton}%= is EDITBUTTON preference |
|  27 Feb 2004: | Added QUIETSAVE setting and =quietsave= parameter; image for Edit button |
|  18 Feb 2004: | Doc fixes; allow edit button anywhere in a cell not just at the end of a cell |
|  17 Feb 2004: | Added per cell definition of edit field types with =%<nop>EDITCELL{}%= variable; added =headerislabel= and =editbutton= parameters |
|  20 Dec 2003: | 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 |
|  13 Dec 2003: | Added CHANGEROWS, JSCALENDARDATEFORMAT, JSCALENDARLANGUAGE, JSCALENDAROPTIONS settings |
|  16 Oct 2003: | small typo fixed (garbled if ---<nop>+ header on top) |
|  15 Oct 2003: | new date field type with javascript calendar - CN |
|  14 Oct 2003: | docfix: the documentation page was an old one - CN |
|  13 Oct 2003: | bugfix: %-vars in select were resetted to first on add/del row - CN |
|  18 Sep 2003: | incompatibility: changed default of =changerows= to =on=; support for %-vars, Quiet save for saving without notification; all other fixes in Dev topic integrated - CN |
|  08 Nov 2002: | Prevent variable expansion in label text; added escape characters |
|  27 Jun 2002: | New =helptopic= parameter |
|  26 Jun 2002: | Support for variables in included EDITTABLE parameters; fixed problem with HTML in cells |
|  21 May 2002: | Added fixed label format; new =changerows="add"= parameter |
|  27 Apr 2002: | Fixed bug where text after a double quote in a cell disappeared |
|  18 Apr 2002: | Fixed bug where table was breaking when pasting multiple lines into an edit field using Netscape on Unix |
|  08 Apr 2002: | Check for change permission and edit lock of topic |
|  05 Apr 2002: | Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | TWiki:Plugins/JSCalendarContrib; TWiki version 01 Feb 2003 or later |
|  Perl Version: | 5.0 |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle 98%, %TWIKIWEB%.FormattedSearch 98%, %TOPIC% 95% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins



%META:FILEATTACHMENT{name="EditTablePluginCalendarExample.gif" attr="h" comment="Screenshot" date="1078005196" path="C:\Data\Temp\EditTablePluginCalendarExample.gif" size="7823" user="TWikiContributor" version="1.1"}%
%META:FILEATTACHMENT{name="ScreenshotEditCell1.gif" attr="h" comment="Screenshot" date="1077169619" path="C:\Data\Temp\ScreenshotEditCell1.gif" size="2017" user="TWikiContributor" version="1.1"}%
%META:FILEATTACHMENT{name="ScreenshotEditCell2.gif" attr="h" comment="Screenshot" date="1077169561" path="C:\Data\Temp\ScreenshotEditCell2.gif" size="3199" user="TWikiContributor" version="1.1"}%
%META:FILEATTACHMENT{name="img.gif" attr="h" comment="Component of Mishoo DHTML calendar" date="1078005090" path="C:\Data\Temp\img.gif" size="145" user="TWikiContributor" version="1.1"}%
%META:FILEATTACHMENT{name="menuarrow.gif" attr="h" comment="Component of Mishoo DHTML calendar" date="1078005104" path="C:\Data\Temp\menuarrow.gif" size="68" user="TWikiContributor" version="1.1"}%
%META:FILEATTACHMENT{name="edittable.gif" attr="h" comment="Edit button image" date="1078004977" path="C:\Data\Temp\edittable.gif" size="298" user="TWikiContributor" version="1.1"}%
