TWiki Forms

Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web & topic

Overview

By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.

Defining a Form Template

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

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 freeform TEXTAREA) that categorizes the content (replaces category table)
  • Within a form-enabled web, individual topics can have a form or no form
• 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 in One Topic

1. Create a new topic with your form name: YourForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
2. Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, and Tooltip message (see sample below).
3. For each field, fill in a new line; for the type of field, select from the list.
4. Save the topic (you can later choose to enable/disable individual forms).

Example: WebForm

| *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... |

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

Defining a Form with Multiple Topics

Forms can also be defined by using form templates that retrieve field values from one or more separate topics:

• A FormTemplate topic defines the Form, ex: YourFormTemplate.
• For each field that has a value list - select, radio, checkbox - can use separate topic to define the available values.

Example: WebFormTemplate

• Know.WebFormTemplate main definition:
   

  Name	Type	Size	Values	Tooltip message
  TopicClassification	select	1		blah blah...
  OperatingSystem	checkbox	3		blah blah...
  OsVersion	text	16		blah blah...

  
  Leave the Values field blank.

• Know.TopicClassification field value definition:
   

  Name	Type	Tooltip message
  NoDisclosure	option	blah blah...
  PublicSupported	option	blah blah...
  PublicFAQ	option	blah blah...

• Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.
  • Topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists.
  • [[...]] links can be used to force a link (at present, the [[...][...]] format is not supported).
  • The Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip In edit.
  • The first item in the list is the default item. Alternative initial values can be set in a topic template, like WebTopicEditTemplate, with field=value, or, for checkboxes, field=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:

• Set WEBFORMS = BugForm, FeatureForm, 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.

Including Forms in New Topics

• 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.

• Additionally 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:
  • other than checkboxes: name, ex: ?BugPriority=1
  • checkbox: namevalue=1, ex: ?ColourRed=1.
    Boxes with a tick must be specified.

Setting Up Multiple Form Options

• The optional WEBFORMS variable defines alternative forms that can be selected by pressing Change in edit mode.

• A topic template can use any form.

• New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form.

Form Data Storage

The form topic name, fields and values are stored as TWikiMetaData - the order of the field/value pairs is the same as in the template.

Using Form Data