**WEBFORMS**
variable in [[WebPreferences]] is optional and defines a list of possible form templates e.g.
- Set WEBFORMS = BugForm, FeatureForm, BookLoanForm
With this present 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 to the right of the form name. The buttons leads to a screen that enables _no form_ to be selected of one of those specified by `WEBFORMS`.
A default form template (i.e. 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 here.
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 checkboxs - nameFLD e.g. ?BugPriorityFLD=1
- Checkbox - nameFLDvalue=1 e.g. ?ColourFLDRed=1. Note that all boxes with a tick must be specified.
#### Defining a form template
Form templates are defined by topics, one topic per form template. A form template topic has descriptive text mixed with the form template definition in the form of a TWiki table.
### Examples
#### Defining form in one topic
Example: 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... |
Name: | Type: | Size: | Values: | Tooltip message: |
---|---|---|---|---|
[[Know/TopicClassification]] | select | 1 | blah blah... | |
[[Know/OperatingSystem]] | checkbox | 3 | blah blah... | |
[[Know/OsVersion]] | text | 16 | blah blah... |
Name: | Type: | Tooltip message: |
---|---|---|
[[Know/NoDisclosure]] | option | blah blah... |
[[Know/PublicSupported]] | option | blah blah... |
[[Know/PublicFAQ]] | option | blah blah... |
[[...|/WebHome]]
can be used for force a link, at present [[...|/WebHome]]
format is not supported
- The "Tooltip message:" column is used as a tool tip for the field name (only if field name is a [[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 fieldFLD=value or for checkboxes fieldFLDcheckbox=1 in URL
- The topic definition is not read when a topic is viewed
### Changes from category system
Main changes from [[TWikiCategoryTable]]:
- Name changed in the hope that form is more readily understandable than category
- The templates for category view/edit have been dropped
- Forms are defined by topics, categories were defined in a template file
- A Web can have multiple forms, only one category was possible
- Form data is saved in meta variables - see [[MetaDataDefinition]], and render to HTML on viewing. Category data was stored as HTML
- The UseCategory radio button has gone, the replacement being the _Change_ form and _Add Form_ buttons.
### Creating new topics with forms
When you create a new topic in a web that has the WEBFORMS preferences variable set you will get a _Add Form_ button at the bottom of the page. However, if the [[WebTopicEditTemplate]] topic has had a form added this will appear with values set; _Change_ in the form can be pressed to remove the template or switch to a different one.
A form embedded in a topic can also cause a form to be present in a new topic, this is done by specifying the `formtemplate` parameter in the URL.
### Topic meta data
See [[TWikiMetaDataDefinition]].
The form template topic name and all form fields/values are stored in the topic meta data. The form template topic name is needed for edit and save.
The order of form field/value items in the meta-data is the same as in the form template.
### UI for multiple form templates
- Optional **WEBFORMS**
variable defines possible form templates that can be selected after pressing "Change" (forms) button on edit page
- A template topic can use any form template
- Decided not to ask user to choose a template or form template when creating a topic as goes against the KISS of Wiki systems.
- New topics with a form get instantiated by simple HTML forms asking for a topic name, i.e. there is a SubmitExpenseReport topic were you can create new expense reports, a SubmitVacationRequest topic and so on. These can specify the required template topic and hence form.
### Migration of Category information
Principle: new system should work with old data with no special conversion.
Old data should be transparently upgraded to the new meta format when a topic is edit/previewed/saved.
On upgrading the administrator must produce a form template topic for each Web that using the old category system. `twikicatitems.tmpl` defines the categories and is used in the conversion. The form template must be put as first item in [[WebPreferences]] variable `=WEBFORM`. If it's not present `view` works, but `edit` results in an _oops_ dialog results. If things aren't working correctly there may be entries `data/warning.txt`.
### History
This is a more general replacement for the [[TWikiCategoryTable]] capability, in particular Forms are defined by special topics, where as categories were defineind using special templates.
-- [[JohnTalintyre]] - 16 Aug 2001