**YourForm**
, **ExpenseReportForm**
, **InfoCategoryForm**
, **RecordReviewForm**
, whatever you need.
2. Create a TWiki table, with each column 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:**
>
> %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 | >
---|
NoDisclosure | >
Public Supported | >
Public FAQ | >
**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.
- You have to list the available form topics explicitly. You cannot use a `SEARCH` to define `WEBFORMS`.
## Adding a form to a topic
- Edit the topic and follow the "Add form" button to add a Form. 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**
. **Name**
, **Type**
, **Size**
, **Values**
, **Tooltip message**
, and **Attributes**
.
The `Name`, `Type` and `Size` columns are required. Other columns are optional. The form **must** have a header row (e.g. `| *Name* | *Type* | *Size* |`).
**Name**
is the name of the form field.
The **Type**
, **Size**
and **Value**
fields describe the legal values for this field, and how to display them.
- **Type**
`checkbox` specifies one or more checkboxes. The `Size` field specifies how many checkboxes will be displayed on each line. The `Value` field should be a comma-separated list of item labels.
- **Type**
`checkbox+buttons` will add **Set** and **Clear** buttons to the basic `checkbox` type.
- **Type**
`radio` is like `checkbox` except that radio buttons are mutually exclusive; only one can be selected.
- **Type**
`label` specifies read-only label text, The `Value` field should contian the text of the label.
- **Type**
`select` specifies a select box. The `Value` field should contain a comma-separated list of options for the box. The `Size` field can specify a fixed size for the box (e.g. `1`, or a range e.g. `3..10`. If you specify a range, then the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options.
- There are two modifiers that can be applied to the `select` type:
- `select+multi` turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
- `select+values` allows the definition of values that are different to the displayed text. For example: | Field 9 | select+values | 5 | One, Two=2, Three=III, Four | Various values formats | shows
but the values or options `Two` and `Three` are `2` and `III` respectively.**Type**
`text` specifies a one-line text field. `Size` specifies the text box width in number of characters. `Value` is the initial (default) content when a new topic is created with this form template.
- **Type**
`textarea` specifies a multi-line text box. The `Size` field should specify columns x rows, e.g. `80x6`; default size is 40x5. As for `text`, the `Value` field specifies the initial text
- **Type**
`date` specifies a single-line text box and a button next to it; clicking on the button will bring up a calendar from which the user can select a date. The date can also be typed into the text box. `Size` specifies the text box width in characters. As for `text`, the `Value` field specifies the initial text
**Tooltip message**
is a message that will be displayed when the cursor is hovered over the field in `edit` view.
**Attributes**
specifies special attributes for the field. Multiple attributes can be entered, separated by spaces.
- 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.
For example, a simple form just supporting entry of a name and a date would look as follows:
| *Name* | *Type* | *Size* |
| Name | text | 80 |
| Date | date | 30 |
**Field Name Notes:**
- Field names have to be unique.
- A very few field names are reserved. If you try to use one of these names, TWiki will automatically append an underscore to the name when the form is used.
- You can space out the title of the field, and it will still find the topic e.g. `Aeroplane Manufacturers` is equivalent to `AeroplaneManufacturers`.
- If a `label` field has no name, it will **not** be shown when the form is **viewed**, only when it is **edited**.
- Field names can in theory include any text, but you should stick to alphanumeric characters. If you want to use a non-wikiname for a `select`, `checkbox` or `radio` field, and want to get the values from another topic, you can use **\[[...]]**
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.
- Leading and trailing spaces are _not_ significant.
**Field Value Notes:**
- The field value will be used to initialize a field when a form is created, unless specific values are given by the topic template or query parameters. The first item in the list for a select or radio type is the default item. For `label`, `text`, and `textarea` fields the value may also contain commas. `checkbox` fields cannot be initialized through the form template.
- Leading and trailing spaces are _not_ significant.
- Field values can also be generated through a [[FormattedSearch]], which must yield a suitable table as the result.
- Variables in the initial values of a form definition get expanded when form values are initialized from the form definition. The escape words `$quot` ("), `$percnt` (%), `$dollar` ($), `$n` (newline), and `$nop` can be used to prevent expansion.
**General Notes:**
- The topic definition is not read when a topic is viewed.
- 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.
### Values in Other Topics
As described above, you can also retrieve possible values for select, checkbox or radio types from other topics. For example, if you have a rows defined like this:
| *Name* | *Type* | *Size* |
| AeroplaneManufacturers | select | |
the TWiki will look for the topic AeroplaneManufacturers to get the possible values for the `select`.
The AeroplaneManufacturers topic must contain a table, where each row of the table describes a possible value. The table only requires one column, **Name**
. Other columns may be present, but are ignored.
For example:
| *Name* |
| Routan |
| Focke-Wulf |
| De Havilland |
**Notes:**
- The **Values**
column **must be empty** in the referring form definition.
## Extending the range of form data types
You can extend the range of data types accepted by forms by using [[TWikiPlugins]]. All such extended data types are single-valued (can only have one value) with the following exceptions:
- any type name starting with `checkbox`
- any type name with `+multi` anywhere in the name
Types with names like this can both take multiple values.
## Hints and Tips
### Build an HTML form to create new Form-based topics
- 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. [[Template topics|Main/TWikiTemplates#TemplateTopics]] has more.
A Form Template specifies the fields in a form. A Form Template is simply a page containing a TWiki table, where each row of the table specifies one form field.
### Searching for Form Data
TWiki Forms accept user-input data, stored as [[TWikiMetaData]]. Meta data also contains program-generated info about changes, attachments, etc. To find, format and display form and other meta data, see [[TWikiMetaData]], **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" nosearch="on" nototal="on" order="modified" reverse="on"
> format="|[[$web.$topic][$topic]] |