Input type | Type field | Size field | Value field |
---|---|---|---|
One or more checkboxes | checkbox |
number of items per line | comma list of item labels |
One or more checkboxes, plus Set and Clear buttons | checkbox+buttons |
(same) | (same) |
One or more radio buttons (radio buttons are mutually exclusive; only one can be selected) | radio |
(same) | (same) |
Read-only label text | label |
ignored | text |
Drop-down menu or scrollable box | select |
1 for drop down, 2 and up for scrollable box |
comma-separated list of options |
A one-line text field | text |
text box width in number of characters | initial text, if a new topic is created with a form template |
A text box | textarea |
columns x rows, e.g. 80x6 ; default size is 40x5 |
initial text, if a new topic is created with a form template |
**YourForm**
, **ExpenseReportForm**
, **InfoCategoryForm**
, **RecordReviewForm**
, whatever you need.
2. Create a TWiki table, with each column head representing one element of an entry field: **Name**
, **Type**
, **Size**
, **Values**
, **Tooltip message**
, and **Attributes**
_(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|Main/WebHome#EnablingForms]] individual forms)_.
> **Example: WebForm**
>
> %BR%
>
> `| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |`
>
> %BR%
>
> `| TopicClassification | select | 1 | NoDisclosure, PublicSupported, PublicFAQ | blah blah... | |`
>
> %BR%
>
> `| OperatingSystem | checkbox | 3 | OsHPUX, OsLinux, OsSolaris, OsWin | blah blah... | |`
>
> %BR%
>
> `| OsVersion | text | 16 | | blah blah... | |`
>
> Name | >Type | >Size | >Values | >Tooltip message | >Attributes | >
---|---|---|---|---|---|
[[Sandbox/TopicClassification]] | >select | >1 | >[[Sandbox/NoDisclosure]], [[Sandbox/PublicSupported]], [[Sandbox/PublicFAQ]] | >blah blah... | >> |
[[Sandbox/OperatingSystem]] | >checkbox | >3 | >[[Sandbox/OsHPUX]], [[Sandbox/OsLinux]], [[Sandbox/OsSolaris]], [[Sandbox/OsWin]] | >blah blah... | >> |
[[Sandbox/OsVersion]] | >text | >16 | >> | blah blah... | >> |
Name | >Type | >Size | >Values | >Tooltip message | >Attributes | >
---|---|---|---|---|---|
TopicClassification | >select | >1 | >> | blah blah... | >> |
OperatingSystem | >checkbox | >3 | >> | blah blah... | >> |
OsVersion | >text | >16 | >> | blah blah... | >> |
**Values**
field **blank**.
>
> - Then in the TopicClassification topic, define the possible values: Name | >Type | >Tooltip message | >
---|---|---|
NoDisclosure | >option | >blah blah... | >
Public Supported | >option | >blah blah... | >
Public FAQ | >option | >blah blah... | >
**\[[...]]**
links. This notation can also be used when referencing another topic to obtain field values, but a name other than the topic name is required as the name of the field.
- Field names have to be unique. If the same name is necessary (as when the field values for several fields are obtained from the same topic), an alternative name must be assigned using the **\[[...]]**
notation.
- The topic defining field values can also be generated through a [[FormattedSearch]], which must yield a suitable table as the result.
- Form definition topics can be protected in the usual manner, using [[TWikiAccessControl]], to limit who can change the form template and/or individual value lists. Note that view access is required to be able to edit topics that use the form definition, though view access to the form definition is _not_ required to view a topic where the form has been used.
- 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 view.
- The **Attributes**
column is used to define special behavior for that form field (multiple attributes can be entered, with or without separators):
- An attribute `H` indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
- An attribute `M` indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an `oops` page. Mandatory fields are indicated by an asterisks next to the field name.
## Enabling Forms by Web
Forms have to be enabled for each individual web. The **WEBFORMS**
variable in [[WebPreferences]] is optional and defines a list of possible form templates.
> **Example:**
>
> - Set WEBFORMS = BugForm, FeatureForm, Books.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.
## Add a form to a topic
- Edit a topic and follow the "Add form" button to add a Form to the topic. This is typically done to a [[template topic|Main/TWikiTemplates#TemplateTopic]], either to the `WebTopicEditTemplate` topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.
- Additionally a new topic can be given a Form using the `formtemplate` parameter in the (edit or save) 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: **?ColorRed=1**
. **FORMFIELD**
, **SEARCH**
and **METASEARCH**
variables in [[TWikiVariables]], and [[TWiki Formatted Search|Main/FormattedSearch]].
> **Example**
>
> %BR% TWiki users often want to have an overview of topics they contributed to. With the
>
> **$formfield**
>
> parameter it is easy to display the value of a classification field next to the topic link:
>
> | *Topic* | *Classification* |
> %SEARCH{"%MAINWEB%.UserName" scope="text" regex="off" nosearch="on" nototal="on" order="modified" reverse="on"
> format="|[[$web.$topic][$topic]] |**twikicatitems.tmpl**
. The replacement Form Template must be set as the first item in the [[WebPreferences]] variable `WEBFORMS`. If missing, pages will display, but attempting to edit results in an error message.
The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.
%T% If things aren't working correctly, there may be useful entries in `data/warning.txt`.
**_Related Topics:_** [[UserDocumentationCategory]], [[TWikiTemplates]]