%META:TOPICINFO{author="TWikiContributor" date="1355386310" format="1.1" version="$Rev$"}%
---+!! <nop>%TOPIC%
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC%
</div></sticky>
%SHORTDESCRIPTION%

---++ Introduction

The !RenderFormPlugin handles the variable =%<nop>RENDERFORM{...}%=. The variable will be replaced by a form that is defined and looks like TWiki.TWikiForms. It helps you to create a new topic with TWiki.TWikiForms or to edit or view  existing topic form data. The form data can be changed without pushing the topic edit button. The variable can be used at any topic to show, edit or create TWiki.TWikiForms data from any other topic.

Features:
   * easy to use: 1. define a form, 2. put the =%<nop>RENDERFORM{...}%= variable on a topic (you do not need to register a form or edit a page to add the form to a topic)
   * supports all form field types of TWiki.TWikiForms (text, textarea, checkbox, checkbox+buttons , date, select, select+multi, radio, label) 
   * supports 3 modes (=mode= option): create (default), edit, view (default if a topic exists)
   * mode switching: edit to view and view to edit 
   * simple !JavaScript based form field validator for mandatory fields
   * hide some form fields (=hidden= option)
   * change display order of form fields (=order= option)
   * use URL parameters to overwrite options (query parameter names: =rfp_&lt;attribute&gt;=)
   * define your own (mode dependent) form layout (=layout= option)

*Example (image):*

<img src="%ATTACHURLPATH%/example.gif" alt="Example" title="Example"/>

%TOC%

---++ Syntax Rules
   * Usage: =%<nop>RENDERFORM{attr1="val1" attr2="val2" ...}%=
   * Example: =%<nop>RENDERFORM{"TWikiFormDefinition"}% (=%<nop>RENDERFORM{form="TWikiFormDefinition"}%=)

---++ Quick Start Guide

   1 Create a new topic (e.g. Sandbox.TestForm) for your TWiki.TWikiForms definition and put the following to the new topic (%X% TWiki.EditTablePlugin required):
     <verbatim>
%EDITTABLE{format="|text,20,|select,1,label,text,textarea,select,select+multi,checkbox,checkbox+buttons,radio,date|text,6,1|text,50|text,20|text,5,|"}%
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
     </verbatim>
   1 Add some new rows to your TWiki.TWikiForms definition by editing the definition table.
   1 Create a new topic (e.g. Sandbox.MyTestTopic) and put the following to this new topic:
     <verbatim>
%RENDERFORM{"MyTestForm")%

%SEARCH{search="MyTestTopic\d+" scope="topic" type="regex"}%
     </verbatim>
   1 Have fun by creating new topics with forms (e.g. topic names: Sandbox.MyTestTopic0, Sandbox.MyTestTopic1, ...). :-)
---++ Usage Examples
---+++ Simple Help Desk
   * Sandbox.SimpleHelpDeskForm topic:
     <verbatim>
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| Question | text | 80 | | | M |
| Details | textarea | 80x10 | | please fill in some details ... | |
| Answer | textarea | 80x10 | | Answer | |
| State | select | 1 | open,closed | | |
     </verbatim>
   * Sandbox.SimpleHelpDesk topic:
     <verbatim>
%RENDERFORM{"SimpleHelpDeskForm" hidden="Answer,State" createbutton="submit" hideheader="yes" text="Back to !SimpleHelpDesk"}%
  
| *Question* | *Date* | *State* |
%SEARCH{search="SimpleHelpDesk\d+" scope="topic" type="regex" nonoise="on" format="| <a href=\"SimpleHelpDesk?rfp_topic=$topic;rfp_hidden=;rfp_hideheader=off\">$formfield(Question)</a> | $date | $formfield(State) |"}% 

%TOPIC% 
     </verbatim>

---+++ Nice Help Desk
   * Sandbox.NiceHelpDeskForm topic:
     <verbatim>
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| Question | text | 80 | | | M |
| Details | textarea | 80x10 | | please fill in some details ... | |
| Answer | textarea | 80x10 | | Answer | |
| State | select | 1 | open,closed | | |
     </verbatim>
   * Sandbox.NiceHelpDeskTemplate:
     <verbatim>
%TOC%
---++ Question: %FORMFIELD{"Question"}% - State: %FORMFIELD{"State"}%

Details:

<pre>
%FORMFIELD{"Details" default="no details"}%
</pre>

---++ Answer
%FORMFIELD{"Answer" default="no answer yet"}%

---++ Comments
%COMMENT{type="threadmode"}%

     </verbatim>
   * Sandbox.NiceHelpDesk topic:
     <verbatim>
%RENDERFORM{"NiceHelpDeskForm" templatetopic="NiceHelpDeskTemplate" hidden="Answer,State" createbutton="submit" hideheader="yes"}%

| *Question* | *Date* | *State* | *Action* |
%SEARCH{search="NiceHelpDesk\d+" scope="topic" type="regex" nonoise="on" format="| [[$topic][$formfield(Question)]]| $date | $formfield(State) | <a href=\"NiceHelpDesk?rfp_topic=$topic;rfp_hidden=;rfp_hideheader=off\" title=\"View form data\">[V]</a>  <a href=\"NiceHelpDesk?rfp_topic=$topic;rfp_hidden=;rfp_hideheader=off;rfp_mode=edit\" title=\"edit form data\">[E]</a>  | "}%

%TOPIC%
     </verbatim>

---++ Parameters

%INCLUDE{ "VarRENDERFORM" section="parameters" }%

#RenderFormPluginFormLayout
---++ Form Layout

Usage: =%<nop>RENDERFORM{"&lt;form definition&gt;" ... layout="&lt;layout topic&gt;"}%= %BR% -or- =%<nop>RENDERFORM{"&lt;form definition&gt;" ... layout="&lt;layout topic&gt;#&lt;layout name&gt;"}%=

   * a form layout is surrounded with the variables =%<nop>STARTRENDERFORMLAYOUT%= and =%<nop>STOPRENDERFORMLAYOUT%=, e.g:
      <verbatim>
   -- a default layout --
%STARTRENDERFORMLAYOUT%
< your layout >
%STOPRENDERFORMLAYOUT%

   -- OR a named layout --
%STARTRENDERFORMLAYOUT{"< layout name >"}% 
< your layout >
%<nop>STOPRENDERFORMLAYOUT%=

   -- OR a named layout for view mode --
%STARTRENDERFORMLAYOUT{"< layout name >" mode="view"}% 
< your layout >
%<nop>STOPRENDERFORMLAYOUT%=
     </verbatim>
   * the layout names 'view', 'create' and 'edit' are reserved and should be used for mode specific layout definitions
   * if you use the =mode= option in =%<nop>STARTRENDERFORMLAYOUT%= this layout definition will be used only in the given mode (allowed modes: create,edit,view)
   * you can use form data values (view mode) or form fields (create/edit mode) by typing a tag like =@&lt; form field  name &gt;@=, e.g. =@Question@=

| *Following tags are reserved and replaced by ...* ||
| *Tag* | *Replaced by* |
| @FORMTOPIC@ |the form topic name |
| @OPTION(&lt;attribute&nbsp;name&gt;)@ | the attribute value, e.g. @OPTION(mode)@ |
| @SUBMIT@ | a submit button or empty string in view mode (hint: change the button text with the =createbutton= or =editbutton= attributes) |
| @SWITCH@ | a link to switch between edit and view mode |
| @TOPIC@ | the (target) topic name of the topic with a form |

*Hints:* 
   * The default field marker '@' can be changed with the =fieldmarker= attribute.
   * Put the complete layout definition between =&lt;verbatim&gt;...&lt;/verbatim&gt;= tags to make the definition visible in the topic view.

*Form Layout Example:* 
%BR% =&lt;verbatim&gt;=
<verbatim>
%STARTRENDERFORMLAYOUT% 
|  *@TOPIC@@SWITCH@ / @FORM@*||
|  Question%RED%*%ENDCOLOR% | @Question@ |
|  Details | @Details@ |
|  %RED%*%ENDCOLOR% indicates mandatory fields||
@SUBMIT@ 
%STOPRENDERFORMLAYOUT% 
</verbatim>
=&lt;/verbatim&gt;=

---++ Examples

%INCLUDE{"RenderFormPluginExampleForm"}%

#RenderFormExamples
%RENDERFORM{"TWiki.RenderFormPluginExampleForm" topic="Sandbox.%TOPIC%XXXXXXXXXX"}%

| *Topic* | *Date* |
%SEARCH{search="RenderFormPlugin\d+" web="Sandbox" type="regex" scope="topic" nonoise="on" format="| <a href=\"%TOPIC%?rfp_topic=$web.$topic#RenderFormExamples\">$topic</a> | $date |"}%

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference
a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;ATTRIBUTENAME&gt;%== to your Main.TWikiPreferences topic, i.e. ==%<nop>RENDERFORM_SHORTDESCRIPTION%==

You can also use template based preferences, just write ==RENDERFORM_TEMPLATE_&lt;templatename&gt;_&lt;ATTRIBUTENAME&gt;==.

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Create new topics with simple forms like TWiki.TWikiForms.
   * Debug plugin: (See output in =data/debug.txt=)
      * Set DEBUG = 0

---++ Plugin Installation Instructions

__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 TWiki server.

%X% __ATTENTION:__ This plugin version depends on the new TWiki:Plugins.DatePickerPlugin; the !JSCalendarContrib is no longer needed by this plugin and must be upgraded or uninstalled.

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/TWiki/%TOPIC%ExampleForm.txt== | Example form topic |
        | ==data/TWiki/VarRENDERFORM.txt== | Plugin Variables topic  |
        | ==pub/TWiki/%TOPIC%/example.gif== | Example image |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/%TOPIC%/Core.pm== | Plugin Perl module |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Test if the installation was successful: See Example section

---++ Plugin Info

|  Plugin Author: | TWiki:Main.DanielRohde |
|  Copyright: | &copy; 2008-2010 TWiki:Main.DanielRohde %BR% &copy; 2008-2012 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2012-12-12 |
|  Change History: | <!-- versions below in reverse order --> |
|  2012-12-12: | TWikibug:Item7077: Make !RenderFormPlugin dependent on DatePickerPlugin instead of deprecated !JSCalendarContrib -- TWiki:Main.PeterThoeny |
|  2012-12-03: | TWikibug:Item7020: Add category to VarRENDERFORM; doc improvements -- TWiki:Main.PeterThoeny |
|  V1.004 (19 Aug 2010) | TWiki:Main.DanielRohde: fixed TWiki 5.0 problems |
|  V1.003 (13 Feb 2009) | TWiki:Main.DanielRohde: fixed performance problem (see Benchmarks - Switch module removed) |
|  V1.002 (14 Oct 2008): | TWiki:Main.DanielRohde: added layout feature; fixed date field bug; added missing docs; |
|  V1.001 (05 Oct 2008): | TWiki:Main.DanielRohde: changed topicparent default; added and fixed docs; fixed date field bug; fixed non-word character in field names bug; |
|  V1.000 (04 Oct 2008): | TWiki:Main.DanielRohde: Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle 95%, %SYSTEMWEB%.FormattedSearch 98%, %TOPIC% 91% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ VarRENDERFORM, %SYSTEMWEB%.TWikiPlugins
