TWikiForms < TWiki

%TOC%
%STARTINCLUDE%
---# Form Templates

Include form-based input in topics, with unlimited, user-selectable forms per web;  values stored as Meta Data

---++ Overview

By adding form-based input to free-form content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, the form appears in edit mode, and the contents are rendered as a table when viewing the actual page. When editing, can switch forms, if more than one is defined, or remove forms entirely. Form input values are stored as [[TWikiDocumentation#TWiki_Meta_Data][TWikiMetaData]]; all data is saved. 

Form Templates replace <nop>TWikiCategory Tables from the previous version of TWiki.

---++ Form Template Elements

   * *form template* - a set of fields defining a form (replaces _category table definition_)
      * A web can use one or more form templates.
   * *form* - A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (replaces _category table_)
      * A topic has zero or one of the defined forms. So there are topics with a form or without.
   * *form field* - a named item in a form (replaces _category item name_)
   * *field type* - selects the INPUT type:
      * *select* - drop-down menu or scrollable box
      * *checkbox* - one or more checkboxes
      * *checkbox+buttons* - one or more checkboxes, plus *Set* and *Clear* buttons
      * *radio* - one or more radio buttons
      * *text* - a one-line text field
      * *textarea* - a text box; size is 40x10 (columns x rows)
   * *field value* - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces _category item value_)

---+++ Defining a Form Template

A Form Template is simply a page containing your form, defined in a table where each row is one form field.

   1. Create a new topic with your Form name: <nop>MyForm, <nop>ExpenseReport, <nop>InfoCategory, <nop>RecordReview, whatever you need.
   1. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (see sample below).
   1. For each field, fill in a new line; for the type of field, select from the list.
   1. Save the topic.

<blockquote style="background-color:#f0f0f0">
<span style="color:#0000ff"><b>Example:</b> Form Template  </span>
<verbatim>
| *Name:* | *Type:* | *Size:* | *Values:* | *Tooltip message:* |
| TopClass | select | 1 | Select one..., Private, Public | must fill |
| Target   | checkbox+buttons | 3 | 1, No.2, No.3 | Select OS |
| Version | text | 16 | | OS version |
</verbatim>
</blockquote>

---+++ Defining a Form in One Topic

Example: <nop>WebFormTemplate of the TWiki.Know web:

| *Name:* | *Type:* | *Size:* | *Values:* | *Tooltip message:* |
| Know.TopicClassification | select | 1 | Know.NoDisclosure, Know.PublicSupported, Know.PublicFAQ | blah blah... |
| Know.OperatingSystem | checkbox | 3 | Know.OsHPUX, Know.OsLinux, Know.OsSolaris, Know.OsWin | blah blah... |
| Know.OsVersion | text | 16 | | blah blah... |

---+++ Defining a Form in Multiple Topics

The form template can also be defined in an alternative way by using more then one topic:

   * A *form template topic* defines the form
   * Values of fields that have more then one value, e.g. of type radio, select and checkbox can be defined by *field value template topics*

</blockquote><blockquote style="background-color:#f0f0f0">
<span style="color:#0000ff"><b>Code from:</b>  </span>

   * <nop>WebFormTemplate of the TWiki.Know web:
     | *Name:* | *Type:* | *Size:* | *Values:*  | *Tooltip message:* |
     | Know.TopicClassification | select | 1 | | blah blah... |
     | Know.OperatingSystem | checkbox | 3 | | blah blah... |
     | Know.OsVersion | text | 16 | | blah blah... |

   * <nop>TopicClassification topic:
     | *Name:* | *Type:* | *Tooltip message:* |
     | Know.NoDisclosure | option | blah blah... |
     | Know.PublicSupported | option | blah blah... |
     | Know.PublicFAQ | option | blah blah... |
</blockquote>

---++++ Implementation Notes

      * This format allows you to define field items with / without TWiki.WikiNames, depending on your needs.
      
      * The topic can be protected in the usual manner so that not everybody can change the form template - see TWikiAccessControl
      
      * =[[...]]= can be used for force a link, at present =[[...][...]]= format is not supported.
      
      * The "Tooltip message:" column is used as a tool tip for the field name (only if field name is a TWiki.WikiName) - you only see the tooltip on edit.
      
      * The first item in the list is the default item.  Alternative initial values can be given in a topic template such as =WebTopicEditTemplate= or using field=value or for checkboxes field<checkbox name>=1.
      
      * The topic definition is not read when a topic is viewed.

---++ Enabling Forms by Web

Forms are enabled on a per web basis. The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible Form Templates. Example:
   * <nop>Set WEBFORMS = <nop>BugForm, <nop>FeatureForm, <nop>BookLoanForm

   * With =WEBFORMS= enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an *Add Form* button appears at the end of the topic. If a Form is present, a *Change* button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in =WEBFORMS=, or the *No form* option.

   * A default Form Template (new topics get this default form) can be provided by creating the =WebTopicEditTemplate= topic in a web and adding a form to it. Initial Form values can be set there.  

   * Addtionaly a new topic can be given a form using the =formtemplate= parameter in the URL.  Initial values can then be provided in the URLs or as form values.  Names being:
      * Not checkboxes - name e.g. ?BugPriority=1
      * Checkbox - namevalue=1 e.g. ?ColourRed=1.  Note that all boxes with a tick must be specified.

---++ Creating New Topics with Forms

When you create a new topic in a web that has the WEBFORMS Preferences variable set, an *Add Form* button appears at the bottom of the page. If the WebTopicEditTemplate topic has a form added, the form will appear with values set; press *Change* to remove the template or to switch to a different one.

A form embedded in a topic also appears in a new topic. This is done by specifying the =formtemplate= parameter in the URL.

---++ Setting Up Multiple Form Options

   * The optional ==WEBFORMS== variable defines alternative Form Templates that can be selected by pressing *Change* in edit mode.
   
   * A Template topic can use any Form Template.
   
   * New topics with a Form are created by simple HTML forms asking for a topic name. For example, you can have a =<nop>SubmitExpenseReport= topic where you can create new expense reports - a =<nop>SubmitVacationRequest= topic and so on. These can specify the required template topic with its associated Form.

---++ Form Template Data Storage

The Form Template topic name, fields and values are stored as [[TWikiDocumentation#TWikiMetaData][Meta Data]]. The order of field/value pairs in the Meta Data is the same as in the Template.

-- JohnTalintyre - 16 Aug 2001 <br>
This topic: TWiki > WebHome > TWikiForms
Topic revision: r7 - 2001-09-07 - MikeMannix
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiForms.