%TOC% %STARTINCLUDE%

# <a name="Form_Templates"> Form Templates </a>

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

## <a name="Overview"> Overview </a>

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]]; all data is saved.

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

## <a name="Form_Template_Elements"> Form Template Elements </a>

* **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_)

### <a name="Defining_a_Form_Template"> Defining a Form Template </a>

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: MyForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
2. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (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.

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

### <a name="Defining_a_Form_in_One_Topic"> Defining a Form in One Topic </a>

Example: WebFormTemplate of the TWiki.Know web:

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Name:</strong></th>
    <th bgcolor="#99CCCC"><strong>Type:</strong></th>
    <th bgcolor="#99CCCC"><strong>Size:</strong></th>
    <th bgcolor="#99CCCC"><strong>Values:</strong></th>
    <th bgcolor="#99CCCC"><strong>Tooltip message:</strong></th>
  </tr>
  <tr>
    <td><span style="background:"><font color="">Topic Classification</font></span><a href="http://LOCATIONKnow/TopicClassification">?</a></td>
    <td> select </td>
    <td> 1 </td>
    <td><span style="background:"><font color="">No Disclosure</font></span><a href="http://LOCATIONKnow/NoDisclosure">?</a>, <span style="background:"><font color="">Public Supported</font></span><a href="http://LOCATIONKnow/PublicSupported">?</a>, <span style="background:"><font color="">Public FAQ</font></span><a href="http://LOCATIONKnow/PublicFAQ">?</a></td>
    <td> blah blah... </td>
  </tr>
  <tr>
    <td><span style="background:"><font color="">Operating System</font></span><a href="http://LOCATIONKnow/OperatingSystem">?</a></td>
    <td> checkbox </td>
    <td> 3 </td>
    <td><span style="background:"><font color="">Os HPUX</font></span><a href="http://LOCATIONKnow/OsHPUX">?</a>, <span style="background:"><font color="">Os Linux</font></span><a href="http://LOCATIONKnow/OsLinux">?</a>, <span style="background:"><font color="">Os Solaris</font></span><a href="http://LOCATIONKnow/OsSolaris">?</a>, <span style="background:"><font color="">Os Win</font></span><a href="http://LOCATIONKnow/OsWin">?</a></td>
    <td> blah blah... </td>
  </tr>
  <tr>
    <td><span style="background:"><font color="">Os Version</font></span><a href="http://LOCATIONKnow/OsVersion">?</a></td>
    <td> text </td>
    <td> 16 </td>
    <td>   </td>
    <td> blah blah... </td>
  </tr>
</table>

### <a name="Defining_a_Form_in_Multiple_Topi"> Defining a Form in Multiple Topics </a>

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

> 
>
> * WebFormTemplate of the TWiki.Know web: <table border="1" cellpadding="1" cellspacing="0">
>   <tr>
>     <th bgcolor="#99CCCC"><strong>Name:</strong></th>
>     <th bgcolor="#99CCCC"><strong>Type:</strong></th>
>     <th bgcolor="#99CCCC"><strong>Size:</strong></th>
>     <th bgcolor="#99CCCC"><strong>Values:</strong></th>
>     <th bgcolor="#99CCCC"><strong>Tooltip message:</strong></th>
>   </tr>
>   <tr>
>     <td><span style="background:"><font color="">Topic Classification</font></span><a href="http://LOCATIONKnow/TopicClassification">?</a></td>
>     <td> select </td>
>     <td> 1 </td>
>     <td>   </td>
>     <td> blah blah... </td>
>   </tr>
>   <tr>
>     <td><span style="background:"><font color="">Operating System</font></span><a href="http://LOCATIONKnow/OperatingSystem">?</a></td>
>     <td> checkbox </td>
>     <td> 3 </td>
>     <td>   </td>
>     <td> blah blah... </td>
>   </tr>
>   <tr>
>     <td><span style="background:"><font color="">Os Version</font></span><a href="http://LOCATIONKnow/OsVersion">?</a></td>
>     <td> text </td>
>     <td> 16 </td>
>     <td>   </td>
>     <td> blah blah... </td>
>   </tr>
> </table>
>
> * TopicClassification topic: <table border="1" cellpadding="1" cellspacing="0">
>   <tr>
>     <th bgcolor="#99CCCC"><strong>Name:</strong></th>
>     <th bgcolor="#99CCCC"><strong>Type:</strong></th>
>     <th bgcolor="#99CCCC"><strong>Tooltip message:</strong></th>
>   </tr>
>   <tr>
>     <td><span style="background:"><font color="">No Disclosure</font></span><a href="http://LOCATIONKnow/NoDisclosure">?</a></td>
>     <td> option </td>
>     <td> blah blah... </td>
>   </tr>
>   <tr>
>     <td><span style="background:"><font color="">Public Supported</font></span><a href="http://LOCATIONKnow/PublicSupported">?</a></td>
>     <td> option </td>
>     <td> blah blah... </td>
>   </tr>
>   <tr>
>     <td><span style="background:"><font color="">Public FAQ</font></span><a href="http://LOCATIONKnow/PublicFAQ">?</a></td>
>     <td> option </td>
>     <td> blah blah... </td>
>   </tr>
> </table>

#### <a name="Implementation_Notes"> Implementation Notes </a>

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

* * The topic definition is not read when a topic is viewed.

## <a name="Enabling_Forms_by_Web"> Enabling Forms by Web </a>

Forms are enabled on a per web basis. The <code>**WEBFORMS**</code> 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.

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

## <a name="Creating_New_Topics_with_Forms"> Creating New Topics with Forms </a>

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.

## <a name="Setting_Up_Multiple_Form_Options"> Setting Up Multiple Form Options </a>

* The optional <code>**WEBFORMS**</code> 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 <code>SubmitExpenseReport</code> topic where you can create new expense reports - a <code>SubmitVacationRequest</code> topic and so on. These can specify the required template topic with its associated Form.

## <a name="Form_Template_Data_Storage"> Form Template Data Storage </a>

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

-- [[JohnTalintyre]] - 16 Aug 2001 <br />