Tags:
component1Add my vote for this tag forms3Add my vote for this tag productivity1Add my vote for this tag rendering2Add my vote for this tag create new tag
view all tags

RenderFormPlugin

Create new topics with simple forms like TWikiForms.

Introduction

The RenderFormPlugin handles the variable %RENDERFORM{...}%. The variable will be replaced by a form that is defined and looks like TWikiForms. It helps you to create a new topic with 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 TWikiForms data from any other topic.

Features:

  • easy to use: 1. define a form, 2. put the %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 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_<attribute>)
  • define your own (mode dependent) form layout (layout option)

Example (image):

Example

Syntax Rules

  • Usage: %RENDERFORM{attr1="val1" attr2="val2" ...}%
  • Example: %RENDERFORM{"TWikiFormDefinition"}% (=%RENDERFORM{form="TWikiFormDefinition"}%)

Quick Start Guide

  1. Create a new topic (e.g. TestForm) for your TWikiForms definition and put the following to the new topic (ALERT! EditTablePlugin required):
    %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* |
         
  2. Add some new rows to your TWikiForms definition by editing the definition table.
  3. Create a new topic (e.g. MyTestTopic) and put the following to this new topic:
    %RENDERFORM{"MyTestForm")%
    
    %SEARCH{search="MyTestTopic\d+" scope="topic" type="regex"}%
         
  4. Have fun by creating new topics with forms (e.g. topic names: MyTestTopic0, MyTestTopic1, ...). smile

Usage Examples

Simple Help Desk

  • SimpleHelpDeskForm topic:
    | *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 | | |
         
  • SimpleHelpDesk topic:
    %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% 
         

Nice Help Desk

  • NiceHelpDeskForm topic:
    | *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 | | |
         
  • NiceHelpDeskTemplate:
    %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"}%
    
         
  • NiceHelpDesk topic:
    %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%
         

Parameters

Parameter Description Default / Example
dateformat overwrites the JSCALENDARDATEFORMAT preference for date fields dateformat="%d %b %Y"
donotnotify disables notifications undefined / donotnotify="on"
form (required attribute) a name of a topic with a TWikiForms definition undefined / form="MyTestForm"
hidden a comma separated list of form field names to hide in all modes undefined / hidden="Field1,Field2"
hideheader if set, disables the form header hideheader="no"
layout a topic with a layout (see Form Layout section); syntax: layout="<topic>#<layout name>"; if layout name is omitted a default layout will be taken undefined / layout="TestFormLayout#test1"
mode render mode of the form, allowed values: create (default), edit, view (default if topic exists) mode="create"
onlynewtopic disables overwrite of existing topics onlynewtopic="on"
onlywikiname disallows the usage of non-TWiki.WikiWords for topic names onlywikiname="on"
order changes the display order of form fields; order value is a comma separated list of field names; if the order list is incomplete all missing and unhidden form fields will be added; there are special values for order: [:alpha:], [:dalpha:], [:num:] and [:dnum:], e.g. order="[:alpha:]" to sort all fields alphanumerical undefined / order="Field1, Field2"
script changes the behavior of edit/create modes; allowed values: save - saves the form data; edit - edit the resulting topic script="save"
template a template name for predefined attributes undefined / template="helpdesk"
templatetopic a template topic; useful for the create mode undefined / templatetopic="MyHelpDeskTopicTemplate"
text the topic text; text will be ignored if a templatetopic is defined undefined / text="my small topic text"
topic an existing topic for edit and view mode or a topic template name for a new topic (create mode) (e.g. TestFormDataXXXXXXXXXX) topic="%TOPIC%XXXXXXXXXX" / topic="TestFormData%SERVERTIME{$epoch}%"
topicparent a topic parent; useful for the create mode; if undefined the form topic will be used topicparent="%WEB%.%TOPIC%" / topicparent="MyHelpDesk"

Form Layout

Usage: %RENDERFORM{"<form definition>" ... layout="<layout topic>"}%
-or- %RENDERFORM{"<form definition>" ... layout="<layout topic>#<layout name>"}%

  • a form layout is surrounded with the variables %STARTRENDERFORMLAYOUT% and %STOPRENDERFORMLAYOUT%, e.g:
       -- 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%=
         
  • 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 %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 @< form field  name >@, e.g. @Question@

Following tags are reserved and replaced by ...
Tag Replaced by
@FORMTOPIC@ the form topic name
@OPTION(<attribute name>)@ 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 <verbatim>...</verbatim> tags to make the definition visible in the topic view.

Form Layout Example:
<verbatim>

%STARTRENDERFORMLAYOUT% 
|  *@TOPIC@@SWITCH@ / @FORM@*||
|  Question%RED%*%ENDCOLOR% | @Question@ |
|  Details | @Details@ |
|  %RED%*%ENDCOLOR% indicates mandatory fields||
@SUBMIT@ 
%STOPRENDERFORMLAYOUT% 
</verbatim>

Examples

Name Type Size Values Tooltip message Attributes
Label label 0 an example label tooltip
Text text 10   text tooltip M
Textarea textarea 10x2   textarea tooltip  
Select select 1 ,1,2 select tooltip  
Select+Multi select+multi 5 1,2,3,4,5 select+multi tooltip  
Checkbox checkbox 2 1,2,3,4,5 checkbox tooltip  
Checkbox+Buttons checkbox+buttons 3 1,2,3,4,5 checkbox+buttons tooltip  
Radio radio 4 1,2,3,4,5,6,7,8,9 radio tooltip  
Date date 20   date tooltip  

%RENDERFORM{"TWiki.RenderFormPluginExampleForm" topic="Sandbox.RenderFormPluginXXXXXXXXXX"}%

Topic Date

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<ATTRIBUTENAME>% to your TWikiPreferences topic, i.e. %RENDERFORM_SHORTDESCRIPTION%

You can also use template based preferences, just write RENDERFORM_TEMPLATE_<templatename>_<ATTRIBUTENAME>.

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Create new topics with simple forms like 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.

ALERT! 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 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 RenderFormPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/RenderFormPlugin.txt Plugin topic
      data/TWiki/RenderFormPluginExampleForm.txt Example form topic
      data/TWiki/VarRENDERFORM.txt Plugin Variables topic
      pub/TWiki/RenderFormPlugin/example.gif Example image
      lib/TWiki/Plugins/RenderFormPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/RenderFormPlugin/Core.pm Plugin Perl module
    • Set the ownership of the extracted directories and files to the webserver user.

  • Plugin configuration and testing:
    • Run the 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: © 2008-2010 TWiki:Main.DanielRohde
© 2008-2012 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2012-12-12
Change History:
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
Benchmarks: GoodStyle 95%, FormattedSearch 98%, RenderFormPlugin 91%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/RenderFormPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/RenderFormPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/RenderFormPluginAppraisal

Related Topics: VarRENDERFORM, TWikiPlugins

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 RenderFormPlugin.md5 r8 r7 r6 r5 r4 manage 0.2 K 2012-12-13 - 08:13 PeterThoeny  
Compressed Zip archivetgz RenderFormPlugin.tgz r9 r8 r7 r6 r5 manage 32.6 K 2012-12-13 - 08:13 PeterThoeny  
Compressed Zip archivezip RenderFormPlugin.zip r9 r8 r7 r6 r5 manage 35.4 K 2012-12-13 - 08:13 PeterThoeny  
Unknown file formatext RenderFormPlugin_installer r3 r2 r1 manage 3.6 K 2012-12-13 - 08:13 PeterThoeny  
Edit | Attach | Watch | Print version | History: r14 < r13 < r12 < r11 < r10 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r14 - 2018-07-17 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.