# Form Templates Include form-based input in topics, with unlimited, user-selectable forms per web; values stored as Meta Data ## Overview 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 [[TWikiMetaData|Main/TWikiDocumentation#TWiki_Meta_Data]]; all data is saved. Form Templates replace TWikiCategory Tables from the previous version of TWiki. ## 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 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_) ### Defining a Form Template 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. > **Example:** Form Template > > | *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 | ### Defining a 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...
### Defining a Form in Multiple Topics 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** > **Code from:** > > - WebFormTemplate of the TWiki.Know web: > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
Name: Type: Size: Values: Tooltip message:
[[Know/TopicClassification]] select 1   blah blah...
[[Know/OperatingSystem]] checkbox 3   blah blah...
[[Know/OsVersion]] text 16   blah blah...
> > - TopicClassification topic: > > > > > > > > > > > > > > > > > > > > >
Name: Type: Tooltip message:
[[Know/NoDisclosure]] option blah blah...
[[Know/PublicSupported]] option blah blah...
[[Know/PublicFAQ]] option blah blah...
#### Implementation Notes - - This format allows you to define field items with / without [[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]] - - [[...|/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 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. - 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. ## Creating New Topics with Forms 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. ## Setting Up Multiple Form Options - The optional **WEBFORMS** 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 `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 Template Data Storage The Form Template topic name, fields and values are stored as [[Meta Data|Main/TWikiDocumentation#TWikiMetaData]]. The order of field/value pairs in the Meta Data is the same as in the Template. -- [[JohnTalintyre]] - 16 Aug 2001