Feature Proposal: New EDITFORMFIELD Variable

Motivation

When creating TWiki apps it is desirable in some cases to create a custom "create new topic" page that has a form to fill out. On submit it creates a new topic based on a template that has a form, and form fields are filled in from the custom "create new topic" form. Instead of handcrafted HTML, it is desirable to use a TWiki variable to show input fields.

Description and Documentation

EDITFORMFIELD{"fieldname" form=""} -- render an input field specified in a form template topic

• Use this to create HTML forms that update TWikiForms, such as a custom "create new topic" form, or a topic header that allows users to change some form values at the top of the page. A valid form is composed of of a start form type, various form fields, a submit type, and an end form type.
• Syntax:
  • %EDITFORMFIELD{"fieldname" form="...Form"}% - create form field defined in a TWiki Form template
  • %EDITFORMFIELD{"fieldname" topic="..."}% - create form field based on a topic that has a TWiki Form & initialize its value
  • %EDITFORMFIELD{"fieldname" type="..."}% - create an HTML input field
• Supported parameters:

  Parameter:	Description:	Default:
  "fieldname"	The name of a TWiki form field or HTML form field.	Required
  form="..."	Name of form template topic, such as "BugForm". Specify topic name or Web.TopicName	Either form or topic is required unless type is specified
  topic="..."	Name of topic containing form, such as "Bug1234". Specify topic name or Web.TopicName
  format="..."	Format string. Supported variables: • $inputfield - rendered form input field. • $title - raw field name (includes space and other special characters). • $name - field name (sanitized title). • $size - size of field or selector. • $value - initial value, or select options. • $tooltip - tooltip message. • $attributes - type attributes, such as H for hidden, M for mandatory. • $extra - extra information, such as * for mandatory field. See details in TWikiForms. This parameter is ignored if type="..." is specified.	"$inputfield"
  value="..."	Initial value of input field. If omitted and if topic="..." is specified, the value is taken from the named form field.	""
  type="start"	Special case: Start an HTML form. Parameters: "form" type="start" action="save" topic="..." method="" • action: Specify a TWiki script (view, edit, save, ...), or a full action URL, default "view". • topic: Specify topic name or Web.TopicName, default current topic; ignored if full action URL is provided. • method: HTML form action method, default "post" for save action, else "get".	""
  type="end"	Special case: End an HTML form. Parameters: "form" type="end"	""
  type="..."	Special case: Create an input field regardless of the type defined in the TWikiForm. Used mainly for hidden fields and submit button. The nameless parameter is the field name. Supported types: • "fieldname" type="hidden" value="..." - hidden input field. • "fieldname" type="submit" value="..." - submit button, value is button label. • "fieldname" type="button" value="..." onclick="..." - regular button, value is button label. • "fieldname" type="text" value="..." size="80" - text input field. • "fieldname" type="checkbox" value="..." text="..." - checkbox, text is display text. • "fieldname" type="radio" value="..." text="..." - radio button, text is display text. • In addition, any valid XHML and HTML5 input type is supported, such as type="date", type="file", type="image". Additional type-specific parameters can be supplied, such as alt="", checked="checked", class="", max="", min="", src="", style="", width="". Consult HTML documentation.	""

• Example: %EDITFORMFIELD{ "ReleaseType" form="PackageForm" value="Beta-1" }%
• Example: Custom form in an included header to update some values of the base topic
  %EDITFORMFIELD{ "form" type="start" action="save" topic="%BASEWEB%.%BASETOPIC%" method="post" }%
| Priority: | %EDITFORMFIELD{ "Priority" topic="%BASETOPIC%" }% |
| Status:   | %EDITFORMFIELD{ "Status"   topic="%BASETOPIC%" }% |
|  | %EDITFORMFIELD{ "form" type="submit" value="Update" }% |
%EDITFORMFIELD{ "Updated" type="hidden" value="%SERVERTIME{$year-$mo-$day}%" }%
%EDITFORMFIELD{ "form" type="end" }%
• Category: DatabaseAndFormsVariables, DevelopmentVariables, EditingAndContentUpdateVariables
• Related: EDITTABLE, FORMFIELD, METASEARCH, SEARCH, FormattedSearch, QuerySearch, SearchHelp, TWikiForms, TWikiScripts

NOTE: The EDITFORMFIELD will understand new types as they become available, such as when installing a new FooPlugin that implements a TWiki::Form::Foo::renderForEdit() method.

Examples

Simply write this to get a combo-box input field of NewComboBoxTWikiFormFieldType, as well as a date field supplied by the DatePickerPlugin:

| Release Type: | %EDITFORMFIELD{ "ReleaseType" form="PackageForm" }% |
| Release Date: | %EDITFORMFIELD{ "ReleaseDate" topic="Pkg1234" }% |

Impact

Implementation

Simple: Similar to existing TWiki::Form::renderForEdit() code

-- Contributors: Peter Thoeny - 2013-03-28

Discussion

Which name is better for this variable: FORMEDITFIELD, FORMINPUTFIELD, EDITFORMFIELD, INPUTFORMFIELD?

I tend to favor:

• FORMINPUTFIELD - descriptive, easy to find because near FORMFIELD in sorted variable list, but name not as readable
• EDITFORMFIELD - easy ro read, understandable, but in sorted variable list not near FORMFIELD

-- Peter Thoeny - 2013-03-28

This feature is accepted by JerusalemReleaseMeeting2013x03x29, renamed from FORMINPUTFIELD to EDITFORMFIELD. This is in anticipation of a separate EDITFORM feature, which is out of scope of this proposal.

-- Peter Thoeny - 2013-03-29

I added support for type="...", including adding HTML form start & end tags.

-- Peter Thoeny - 2013-03-31