data/TWiki/TWikiForms.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
head	1.24;
colas@0
     2
access;
colas@0
     3
symbols;
colas@0
     4
locks; strict;
colas@0
     5
comment	@# @;
colas@0
     6
colas@0
     7
colas@0
     8
1.24
colas@0
     9
date	2008.01.22.03.21.30;	author TWikiContributor;	state Exp;
colas@0
    10
branches;
colas@0
    11
next	1.23;
colas@0
    12
colas@0
    13
1.23
colas@0
    14
date	2007.01.16.04.12.05;	author TWikiContributor;	state Exp;
colas@0
    15
branches;
colas@0
    16
next	1.22;
colas@0
    17
colas@0
    18
1.22
colas@0
    19
date	2006.04.01.05.55.12;	author TWikiContributor;	state Exp;
colas@0
    20
branches;
colas@0
    21
next	1.21;
colas@0
    22
colas@0
    23
1.21
colas@0
    24
date	2006.02.01.12.01.19;	author TWikiContributor;	state Exp;
colas@0
    25
branches;
colas@0
    26
next	1.20;
colas@0
    27
colas@0
    28
1.20
colas@0
    29
date	2004.08.20.05.55.02;	author PeterThoeny;	state Exp;
colas@0
    30
branches;
colas@0
    31
next	1.19;
colas@0
    32
colas@0
    33
1.19
colas@0
    34
date	2004.08.15.09.48.58;	author PeterThoeny;	state Exp;
colas@0
    35
branches;
colas@0
    36
next	1.18;
colas@0
    37
colas@0
    38
1.18
colas@0
    39
date	2004.04.25.06.50.02;	author PeterThoeny;	state Exp;
colas@0
    40
branches;
colas@0
    41
next	1.17;
colas@0
    42
colas@0
    43
1.17
colas@0
    44
date	2003.08.23.04.03.47;	author PeterThoeny;	state Exp;
colas@0
    45
branches;
colas@0
    46
next	1.16;
colas@0
    47
colas@0
    48
1.16
colas@0
    49
date	2003.01.25.09.23.07;	author PeterThoeny;	state Exp;
colas@0
    50
branches;
colas@0
    51
next	1.15;
colas@0
    52
colas@0
    53
1.15
colas@0
    54
date	2002.08.27.15.15.00;	author PeterThoeny;	state Exp;
colas@0
    55
branches;
colas@0
    56
next	1.14;
colas@0
    57
colas@0
    58
1.14
colas@0
    59
date	2002.01.05.21.30.00;	author MikeMannix;	state Exp;
colas@0
    60
branches;
colas@0
    61
next	1.13;
colas@0
    62
colas@0
    63
1.13
colas@0
    64
date	2001.12.03.10.09.02;	author MikeMannix;	state Exp;
colas@0
    65
branches;
colas@0
    66
next	1.12;
colas@0
    67
colas@0
    68
1.12
colas@0
    69
date	2001.09.15.10.02.52;	author MikeMannix;	state Exp;
colas@0
    70
branches;
colas@0
    71
next	1.11;
colas@0
    72
colas@0
    73
1.11
colas@0
    74
date	2001.09.14.09.31.19;	author PeterThoeny;	state Exp;
colas@0
    75
branches;
colas@0
    76
next	1.10;
colas@0
    77
colas@0
    78
1.10
colas@0
    79
date	2001.09.12.06.51.29;	author MikeMannix;	state Exp;
colas@0
    80
branches;
colas@0
    81
next	1.9;
colas@0
    82
colas@0
    83
1.9
colas@0
    84
date	2001.09.09.06.51.31;	author MikeMannix;	state Exp;
colas@0
    85
branches;
colas@0
    86
next	1.8;
colas@0
    87
colas@0
    88
1.8
colas@0
    89
date	2001.09.07.23.27.02;	author MikeMannix;	state Exp;
colas@0
    90
branches;
colas@0
    91
next	1.7;
colas@0
    92
colas@0
    93
1.7
colas@0
    94
date	2001.09.07.11.10.16;	author MikeMannix;	state Exp;
colas@0
    95
branches;
colas@0
    96
next	1.6;
colas@0
    97
colas@0
    98
1.6
colas@0
    99
date	2001.09.04.09.53.16;	author JohnTalintyre;	state Exp;
colas@0
   100
branches;
colas@0
   101
next	1.5;
colas@0
   102
colas@0
   103
1.5
colas@0
   104
date	2001.09.01.11.07.46;	author MikeMannix;	state Exp;
colas@0
   105
branches;
colas@0
   106
next	1.4;
colas@0
   107
colas@0
   108
1.4
colas@0
   109
date	2001.09.01.05.55.27;	author MikeMannix;	state Exp;
colas@0
   110
branches;
colas@0
   111
next	1.3;
colas@0
   112
colas@0
   113
1.3
colas@0
   114
date	2001.08.29.16.10.24;	author JohnTalintyre;	state Exp;
colas@0
   115
branches;
colas@0
   116
next	1.2;
colas@0
   117
colas@0
   118
1.2
colas@0
   119
date	2001.08.16.12.26.05;	author JohnTalintyre;	state Exp;
colas@0
   120
branches;
colas@0
   121
next	1.1;
colas@0
   122
colas@0
   123
1.1
colas@0
   124
date	2001.08.07.16.22.54;	author JohnTalintyre;	state Exp;
colas@0
   125
branches;
colas@0
   126
next	;
colas@0
   127
colas@0
   128
colas@0
   129
desc
colas@0
   130
@none
colas@0
   131
@
colas@0
   132
colas@0
   133
colas@0
   134
1.24
colas@0
   135
log
colas@0
   136
@buildrelease
colas@0
   137
@
colas@0
   138
text
colas@0
   139
@%META:TOPICINFO{author="TWikiContributor" date="1177881299" format="1.1" version="24"}%
colas@0
   140
%STARTINCLUDE%
colas@0
   141
---+ TWiki Forms
colas@0
   142
colas@0
   143
_Add structure to content with forms attached to twiki topics. TWiki forms (with form fields) and formatted search are the base for building database applications._
colas@0
   144
colas@0
   145
%TOC%
colas@0
   146
colas@0
   147
---++ Overview
colas@0
   148
colas@0
   149
By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. A form is enabled for a web and can be added to a topic. The form data is shown in tabular format when the topic is viewed, and can be changed in edit mode using edit fields, radio buttons, check boxes and list boxes. Many different form types can be defined in a web, though a topic can only have one form attached to it at a time.
colas@0
   150
colas@0
   151
Typical steps to build an application based on TWiki forms:
colas@0
   152
   1. Define a form template
colas@0
   153
   1. Enable the form for a web
colas@0
   154
   1. Add the form to a [[TWikiTemplates#Template_Topics][template topic]]
colas@0
   155
   1. Build an HTML form to create new topics based on that template topic
colas@0
   156
   1. Build a FormattedSearch to list topics that share the same form
colas@0
   157
colas@0
   158
---++ Defining a Form
colas@0
   159
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.
colas@0
   160
   1. Create a new topic with your form name: ==<nop>YourForm==, ==<nop>ExpenseReportForm==, ==<nop>InfoCategoryForm==, ==<nop>RecordReviewForm==, whatever you need.
colas@0
   161
   1. 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)_.
colas@0
   162
   1. For each field, fill in a new line; for the type of field, select from the list.
colas@0
   163
   1. Save the topic _(you can later choose to [[#EnablingForms][enable/disable]] individual forms)_.
colas@0
   164
colas@0
   165
<blockquote>
colas@0
   166
*Example:* %BR%
colas@0
   167
=| <nop>*Name* | <nop>*Type* | <nop>*Size* | <nop>*Values* | <nop>*Tooltip message* | <nop>*Attributes* |= %BR%
colas@0
   168
=| !TopicClassification | select | 1 | !NoDisclosure, !PublicSupported, !PublicFAQ | blah blah... | &nbsp; |= %BR%
colas@0
   169
=| !OperatingSystem | checkbox | 3 | !OsHPUX, !OsLinux, !OsSolaris, !OsWin | blah blah... | &nbsp; |= %BR%
colas@0
   170
=| !OsVersion | text | 16 | | blah blah... | &nbsp; |=
colas@0
   171
colas@0
   172
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
colas@0
   173
| <a href="%SCRIPTURLPATH{"view"}%/Sandbox/TopicClassification"><nop>TopicClassification</a> | select |  1  | <a href="%SCRIPTURLPATH{"view"}%/Sandbox/NoDisclosure"><nop>NoDisclosure</a>, <a href="%SCRIPTURLPATH{"view"}%/Sandbox/PublicSupported"><nop>PublicSupported</a>, <a href="%SCRIPTURLPATH{"view"}%/Sandbox/PublicFAQ"><nop>PublicFAQ</a> | blah blah... | &nbsp; |
colas@0
   174
| <a href="%SCRIPTURLPATH{"view"}%/Sandbox/OperatingSystem"><nop>OperatingSystem</a> | checkbox |  3  | <a href="%SCRIPTURLPATH{"view"}%/Sandbox/OsHPUX"><nop>OsHPUX</a>, <a href="%SCRIPTURLPATH{"view"}%/Sandbox/OsLinux"><nop>OsLinux</a>, <a href="%SCRIPTURLPATH{"view"}%/Sandbox/OsSolaris"><nop>OsSolaris</a>, <a href="%SCRIPTURLPATH{"view"}%/Sandbox/OsWin"><nop>OsWin</a> | blah blah... | &nbsp; |
colas@0
   175
| <a href="%SCRIPTURLPATH{"view"}%/Sandbox/OsVersion"><nop>OsVersion</a> | text |  16  | | blah blah... | &nbsp; |
colas@0
   176
</blockquote>
colas@0
   177
colas@0
   178
See [[#FormStructure][structure of a form]] for full details of what types are available and what all the columns mean.
colas@0
   179
colas@0
   180
You can also retrieve possible values for =select=, =checkbox= or =radio= types from other topics:
colas@0
   181
colas@0
   182
<blockquote>
colas@0
   183
*Example:*
colas@0
   184
colas@0
   185
   * In the <nop>WebForm topic, define the form:
colas@0
   186
     <br />
colas@0
   187
     | *Name* | *Type* | *Size* | *Values*  | *Tooltip message* | *Attributes* |
colas@0
   188
     | <nop>TopicClassification | select | 1 |    | blah blah... | &nbsp; |
colas@0
   189
     | <nop>OperatingSystem | checkbox | 3 |    | blah blah... | &nbsp; |
colas@0
   190
     | <nop>OsVersion | text | 16 |    | blah blah... | &nbsp; |
colas@0
   191
     <br />
colas@0
   192
     %X% Leave the ==Values== field *blank*.
colas@0
   193
colas@0
   194
   * Then in the <nop>TopicClassification topic, define the possible values:
colas@0
   195
     <br />
colas@0
   196
     =| <nop>*Name*            |= %BR%
colas@0
   197
     =| <nop>NoDisclosure      |= %BR%
colas@0
   198
     =| Public Supported  |= %BR%
colas@0
   199
     =| Public FAQ        |= %BR%
colas@0
   200
     | *Name* |
colas@0
   201
     | <nop>NoDisclosure |
colas@0
   202
     | Public Supported |
colas@0
   203
     | Public FAQ |
colas@0
   204
</blockquote>
colas@0
   205
colas@0
   206
Field values can also be set using the result of expanding other TWiki variables. For example,
colas@0
   207
colas@0
   208
<blockquote>
colas@0
   209
=%<nop>SEARCH{"Office$" scope="topic" web="%<nop>USERSWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%=
colas@0
   210
</blockquote>
colas@0
   211
colas@0
   212
When used in the value field of the form definition, this will find all topic names in the Main web which end in "Office" and use them as the legal field values.
colas@0
   213
colas@0
   214
#EnablingForms
colas@0
   215
---++ Enabling Forms by Web
colas@0
   216
colas@0
   217
Forms have to be enabled for each individual web. The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible form templates.
colas@0
   218
<blockquote>
colas@0
   219
*Example:*
colas@0
   220
   * <nop>Set WEBFORMS = <nop>BugForm, <nop>FeatureForm, Books.<nop>BookLoanForm
colas@0
   221
</blockquote>
colas@0
   222
   * 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.
colas@0
   223
   * You have to list the available form topics explicitly. You cannot use a =SEARCH= to define =WEBFORMS=.
colas@0
   224
colas@0
   225
---++ Adding a form to a topic
colas@0
   226
colas@0
   227
   * Edit the topic and follow the "Add form" button to add a Form. This is typically done to a [[TWikiTemplates#TemplateTopic][template topic]], 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.
colas@0
   228
colas@0
   229
   * 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:
colas@0
   230
      * other than checkboxes: ==name==, ex: ==?BugPriority=1==
colas@0
   231
      * checkbox: ==namevalue=1==, ex: ==?ColorRed=1==. <br /> 
colas@0
   232
        Boxes with a tick must be specified.
colas@0
   233
      * Example: This will add a textfield for the new topic name and a "Create"-Button to your topic. When the button is pressed, the topic editor will open with the form "MyForm" already attached to the new topic.
colas@0
   234
       <verbatim>
colas@0
   235
    <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/">
colas@0
   236
       <input type="hidden" name="formtemplate" value="MyForm" />
colas@0
   237
       New topic name <input type="text" name="topic" size="40" />
colas@0
   238
       <input type="submit" class="twikiSubmit" value="Create" />
colas@0
   239
    </form>
colas@0
   240
       </verbatim>
colas@0
   241
   * __%T% Tip:__ For TWiki applications you can [[TWikiTemplates#AutomaticallyGeneratedTopicname][automatically generate unique topicnames]].
colas@0
   242
colas@0
   243
   * __%X% Note:__ Initial values will *not* be set in the form of a new topic if you _only_ use the formtemplate parameter.
colas@0
   244
colas@0
   245
---++ Changing a form
colas@0
   246
   * You can change a form definition, and TWiki will try to make sure you don't lose any data from the topics that use that form. 
colas@0
   247
colas@0
   248
   * If you change the form definition, the changes will not take affect in a topic that uses that form until you edit and save it.
colas@0
   249
colas@0
   250
   * If you add a new field to the form, then it will appear next time you edit a topic that uses the form.
colas@0
   251
colas@0
   252
   * If you delete a field from the form, or change a field name, then the data will not be visible when you edit the topic (the changed form definition will be used). *If you save the topic, the old data will be lost* (though thanks to revision control, you can always see it in older versions of the topic)
colas@0
   253
colas@0
   254
   * If two people edit the same topic containing a form at exactly the same time, and both change fields in the form, TWiki will try to merge the changes so that no data is lost.
colas@0
   255
colas@0
   256
#FormStructure
colas@0
   257
---++ Structure of a Form Template
colas@0
   258
colas@0
   259
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.
colas@0
   260
colas@0
   261
Each *column* of the table is one element of an entry field: ==Name==, ==Type==, ==Size==, ==Values==, ==Tooltip message==, and ==Attributes==.
colas@0
   262
colas@0
   263
The =Name=, =Type= and =Size= columns are required. Other columns are optional. The form *must* have a header row (e.g. =| <nop>*Name* | <nop>*Type* | <nop>*Size* |=).
colas@0
   264
colas@0
   265
==Name== is the name of the form field.
colas@0
   266
colas@0
   267
The ==Type==, ==Size== and ==Value== fields describe the legal values for this field, and how to display them.
colas@0
   268
   * ==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.
colas@0
   269
      * ==Type== =checkbox+buttons= will add *Set* and *Clear* buttons to the basic =checkbox= type.
colas@0
   270
   * ==Type== =radio= is like =checkbox= except that radio buttons are mutually exclusive; only one can be selected.
colas@0
   271
   * ==Type== =label= specifies read-only label text. The =Value= field should contain the text of the label.
colas@0
   272
   * ==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.
colas@0
   273
      * There are two modifiers that can be applied to the =select= type:
colas@0
   274
         * =select+multi= turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
colas@0
   275
         * =select+values= allows the definition of values that are different to the displayed text. For example:
colas@0
   276
         <pre>| Field 9 | select+values | 5 | One, Two=2, Three=III, Four | Various values formats |</pre> shows <select size="2"><option>One</option><option>Two</option><option>Three</option><option>Four</option></select> but the values or options =Two= and =Three= are =2= and =III= respectively.<br />
colas@0
   277
      You can combine these modifiers e.g. =select+multi+values=
colas@0
   278
   * ==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.
colas@0
   279
   * ==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
colas@0
   280
   * ==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
colas@0
   281
colas@0
   282
==Tooltip message== is a message that will be displayed when the cursor is hovered over the field in =edit= view.
colas@0
   283
colas@0
   284
==Attributes== specifies special attributes for the field. Multiple attributes can be entered, separated by spaces.
colas@0
   285
   * An attribute =H= indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
colas@0
   286
   * 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.
colas@0
   287
colas@0
   288
For example, a simple form just supporting entry of a name and a date would look as follows:
colas@0
   289
<verbatim>
colas@0
   290
| *Name* | *Type* | *Size* |
colas@0
   291
| Name   | text   | 80     |
colas@0
   292
| Date   | date   | 30     |
colas@0
   293
</verbatim>
colas@0
   294
*Field Name Notes:*
colas@0
   295
   * Field names have to be unique.
colas@0
   296
   * 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.
colas@0
   297
   * You can space out the title of the field, and it will still find the topic e.g. =Aeroplane Manufacturers= is equivalent to =AeroplaneManufacturers=.
colas@0
   298
   * If a =label= field has no name, it will *not* be shown when the form is *viewed*, only when it is *edited*.
colas@0
   299
   * 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  ==[<nop>[...]]== 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. 
colas@0
   300
   * Leading and trailing spaces are _not_ significant.
colas@0
   301
*Field Value Notes:*
colas@0
   302
   * 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.
colas@0
   303
   * Leading and trailing spaces are _not_ significant.
colas@0
   304
   * Field values can also be generated through a %SYSTEMWEB%.FormattedSearch, which must yield a suitable table as the result.
colas@0
   305
   * Variables in the initial values of a form definition get expanded when the form definition is loaded.
colas@0
   306
      * If you want to use a =|= character in the initial values field, you have to precede it with a backslash, thus: =\|=.
colas@0
   307
      * You can use =&lt;nop>= to prevent TWiki variables from being expanded.
colas@0
   308
      * The FormatTokens can be used to prevent expansion of other characters.
colas@0
   309
*General Notes:*
colas@0
   310
   * The topic definition is not read when a topic is viewed.
colas@0
   311
   * 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.
colas@0
   312
colas@0
   313
---+++ Values in Other Topics
colas@0
   314
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:
colas@0
   315
<verbatim>
colas@0
   316
| *Name*                 | *Type* | *Size* |
colas@0
   317
| AeroplaneManufacturers | select |        |
colas@0
   318
</verbatim>
colas@0
   319
the TWiki will look for the topic !AeroplaneManufacturers to get the possible values for the =select=.
colas@0
   320
colas@0
   321
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.
colas@0
   322
colas@0
   323
For example:
colas@0
   324
<verbatim>
colas@0
   325
| *Name* |
colas@0
   326
| Routan |
colas@0
   327
| Focke-Wulf |
colas@0
   328
| De Havilland |
colas@0
   329
</verbatim>
colas@0
   330
colas@0
   331
*Notes:*
colas@0
   332
   * The ==Values== column *must be empty* in the referring form definition.
colas@0
   333
 
colas@0
   334
---++ Extending the range of form data types
colas@0
   335
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:
colas@0
   336
   * any type name starting with =checkbox=
colas@0
   337
   * any type name with =+multi= anywhere in the name
colas@0
   338
Types with names like this can both take multiple values.
colas@0
   339
colas@0
   340
---++ Hints and Tips
colas@0
   341
---+++ Build an HTML form to create new Form-based topics
colas@0
   342
   * New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a =<nop>SubmitExpenseReport= topic where you can create new expense reports, a =<nop>SubmitVacationRequest= topic, and so on. These can specify the required template topic with its associated form. [[TWikiTemplates#TemplateTopics][Template topics]] has more.
colas@0
   343
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.
colas@0
   344
#UsingFormData
colas@0
   345
---+++ Searching for Form Data
colas@0
   346
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 [[FormattedSearch][TWiki Formatted Search]].
colas@0
   347
colas@0
   348
<blockquote>
colas@0
   349
*Example* %BR%
colas@0
   350
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:
colas@0
   351
<verbatim>
colas@0
   352
| *Topic* | *Classification* |
colas@0
   353
%SEARCH{"%USERSWEB%.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on"
colas@0
   354
format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%
colas@0
   355
</verbatim>
colas@0
   356
</blockquote> 
colas@0
   357
colas@0
   358
Searching forms this way is obviously pretty inefficient, but it's easy to do. If you want better performance, take a look at some of the structured wiki extensions that support higher performance searching e.g. TWiki:Plugins.DBCachePlugin.
colas@0
   359
---+++ Gotcha!
colas@0
   360
   * Some browsers may strip linefeeds from =text= fields when a topic is saved. If you need linefeeds in a field, make sure it is a =textarea=.
colas@0
   361
colas@0
   362
%STOPINCLUDE%
colas@0
   363
colas@0
   364
__Related Topics:__ UserDocumentationCategory, TWikiTemplates
colas@0
   365
@
colas@0
   366
colas@0
   367
colas@0
   368
1.23
colas@0
   369
log
colas@0
   370
@buildrelease
colas@0
   371
@
colas@0
   372
text
colas@0
   373
@d1 1
colas@0
   374
a1 2
colas@0
   375
%META:TOPICINFO{author="TWikiContributor" date="1163619832" format="1.0" version="23"}%
colas@0
   376
%TOC%  
colas@0
   377
d3 1
colas@0
   378
a3 1
colas@0
   379
---# TWiki Forms
colas@0
   380
d7 2
colas@0
   381
d11 1
colas@0
   382
a11 1
colas@0
   383
By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. A form is enabled for a web and can be added to a topic. The form data is shown in tabular format when the topic is viewed, and can be changed in edit mode using edit fields, radio buttons, check boxes and list boxes. Many different form types can be defined in a web, though a topic can only have only form attached to it at a time.
colas@0
   384
d68 1
colas@0
   385
a68 1
colas@0
   386
Field values can also be obtained as the result of a %TWIKIWEB%.FormattedSearch. For example,
colas@0
   387
d71 1
colas@0
   388
a71 1
colas@0
   389
=%<nop>SEARCH{"Office$" scope="topic" web="%<nop>MAINWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%=
colas@0
   390
d74 1
colas@0
   391
a74 1
colas@0
   392
when used in the value field of the form definition, this will find all topic names in the Main web which end in "Office" and use them as the legal field values.
colas@0
   393
d105 1
colas@0
   394
a105 1
colas@0
   395
   * __%X% Note:__ Initial values will not be submitted to the form of a new topic if you only use the formtemplate parameter.
colas@0
   396
d133 1
colas@0
   397
a133 1
colas@0
   398
   * ==Type== =label= specifies read-only label text, The =Value= field should contian the text of the label.
colas@0
   399
d166 5
colas@0
   400
a170 2
colas@0
   401
   * Field values can also be generated through a %TWIKIWEB%.FormattedSearch, which must yield a suitable table as the result.
colas@0
   402
   * 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.
colas@0
   403
d215 1
colas@0
   404
a215 1
colas@0
   405
%SEARCH{"%MAINWEB%.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on"
colas@0
   406
@
colas@0
   407
colas@0
   408
colas@0
   409
1.22
colas@0
   410
log
colas@0
   411
@buildrelease
colas@0
   412
@
colas@0
   413
text
colas@0
   414
@d1 1
colas@0
   415
a1 1
colas@0
   416
%META:TOPICINFO{author="TWikiContributor" date="1117921800" format="1.0" version="22"}%
colas@0
   417
d19 2
colas@0
   418
a20 24
colas@0
   419
---++ Defining a Form Template
colas@0
   420
colas@0
   421
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 is one form field.
colas@0
   422
colas@0
   423
---+++ Form Template Elements
colas@0
   424
colas@0
   425
   * *form template* - a set of fields defining a form
colas@0
   426
      * A web can use one or more form templates
colas@0
   427
   * *form* - additional meta data (besides the freeform TEXTAREA) attached to a topic
colas@0
   428
      * Within a form-enabled web, individual topics can have a form or no form
colas@0
   429
   * *form field* - a named item in a form (also known as a _key_)
colas@0
   430
   * *field type* - selects the field type:
colas@0
   431
     | *Input type* | *Type field* | *Size field* | *Value field* |
colas@0
   432
     | One or more checkboxes | =checkbox= | number of items per line | comma list of item labels |
colas@0
   433
     | One or more checkboxes, plus *Set* and *Clear* buttons | =checkbox+buttons= | (same) | (same) |
colas@0
   434
     | One or more radio buttons (radio buttons are mutually exclusive; only one can be selected) | =radio= | (same) | (same) |
colas@0
   435
     | Read-only label text | =label= | _ignored_ | text |
colas@0
   436
     | Drop-down menu or scrollable box | =select= | =1= for drop down, =2= and up for scrollable box | comma-separated list of options |
colas@0
   437
     | 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 |
colas@0
   438
     | 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 |
colas@0
   439
   * *field value* - one or more values from a fixed set (select, checkbox, radio type) or free-form (label, text, text area).
colas@0
   440
colas@0
   441
---+++ Defining a Form
colas@0
   442
colas@0
   443
d22 1
colas@0
   444
a22 1
colas@0
   445
   1. 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)_.
colas@0
   446
d26 2
colas@0
   447
a27 2
colas@0
   448
<blockquote style="background-color:#f0f0f0">
colas@0
   449
*Example: <nop>WebForm* %BR%
colas@0
   450
d39 1
colas@0
   451
a39 1
colas@0
   452
You can also retrieve possible values for select, checkbox or radio types from other topics:
colas@0
   453
d41 4
colas@0
   454
a44 2
colas@0
   455
<blockquote style="background-color:#f0f0f0">
colas@0
   456
*Example: <nop>WebForm*
colas@0
   457
d57 8
colas@0
   458
a64 4
colas@0
   459
     | *Name* | *Type* | *Tooltip message* |
colas@0
   460
     | <nop>NoDisclosure | option | blah blah... |
colas@0
   461
     | Public Supported | option | blah blah... |
colas@0
   462
     | Public FAQ | option | blah blah... |
colas@0
   463
d69 2
colas@0
   464
a70 2
colas@0
   465
<blockquote style="background-color:#f0f0f0">
colas@0
   466
=%<nop>SEARCH{"Office$" scope="topic" web="%<nop>MAINWEB%" nototal="on" nosummary="on" nosearch="on" regex="on" format="$web.$topic" separator=", " }%=
colas@0
   467
d73 1
colas@0
   468
a73 17
colas@0
   469
when used in the value field of the form definition, will take the set of field values to be all topic names in the Main web which end in "Office".
colas@0
   470
colas@0
   471
colas@0
   472
*Notes:*
colas@0
   473
   * 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.
colas@0
   474
   * 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.
colas@0
   475
   * If a =label= field has no name (blank first column in the form definition) it will *not* be shown when the form is *viewed*, only when it is *edited*.
colas@0
   476
   * The topic definition is not read when a topic is viewed.
colas@0
   477
   * Field names can 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  ==[<nop>[...]]== 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. 
colas@0
   478
   * 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 ==[<nop>[...]]== notation.
colas@0
   479
   * The topic defining field values can also be generated through a %TWIKIWEB%.FormattedSearch, which must yield a suitable table as the result.
colas@0
   480
   * 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.
colas@0
   481
   * The ==Tooltip message== column is used as a tooltip for the field name (only if field name is a %TWIKIWEB%.WikiName) - you only see the tooltip in edit view.
colas@0
   482
   * The ==Attributes== column is used to define special behavior for that form field (multiple attributes can be entered, with or without separators):
colas@0
   483
      * An attribute =H= indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
colas@0
   484
      * 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. 
colas@0
   485
</blockquote>
colas@0
   486
d79 1
colas@0
   487
a79 1
colas@0
   488
<blockquote style="background-color:#f0f0f0">
colas@0
   489
d84 1
colas@0
   490
d86 1
colas@0
   491
a86 1
colas@0
   492
---++ Add a form to a topic
colas@0
   493
d88 1
colas@0
   494
a88 1
colas@0
   495
   * Edit a topic and follow the "Add form" button to add a Form to the topic. This is typically done to a [[TWikiTemplates#TemplateTopic][template topic]], 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.
colas@0
   496
d99 1
colas@0
   497
a99 1
colas@0
   498
       <input type="submit" value="Create" />
colas@0
   499
a105 4
colas@0
   500
---++ Build an HTML form to create new Form-based topics
colas@0
   501
   
colas@0
   502
   * New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a =<nop>SubmitExpenseReport= topic where you can create new expense reports, a =<nop>SubmitVacationRequest= topic, and so on. These can specify the required template topic with its associated form. [[TWikiTemplates#TemplateTopics][Template topics]] has more.
colas@0
   503
colas@0
   504
d115 87
colas@0
   505
d203 1
colas@0
   506
a203 1
colas@0
   507
---++ Searching for Form Data
colas@0
   508
d211 1
colas@0
   509
a211 1
colas@0
   510
%SEARCH{"%MAINWEB%.UserName" scope="text" regex="off" nosearch="on" nototal="on" order="modified" reverse="on"
colas@0
   511
d216 2
colas@0
   512
a217 7
colas@0
   513
---++ Extending the range of form data types
colas@0
   514
Several Plugins allow you to extend the range of data types accepted by forms. For example, the TWiki:Plugins.DateFieldPlugin lets you add a 'date' type to the available data types. All data types are single-valued (can only have one value) with the following exceptions:
colas@0
   515
   * any type name starting with =checkbox=
colas@0
   516
   * any type name with =+multi= anywhere in the name
colas@0
   517
Types with names like this can both take multiple values.
colas@0
   518
colas@0
   519
---++ Gotcha!
colas@0
   520
a219 11
colas@0
   521
#FormsVsCategoryTables
colas@0
   522
---++ Importing Category Table Data
colas@0
   523
colas@0
   524
Very, very old TWiki releases used a system called the "TWikiCategoryTable". Later releases support automatic import of this data.
colas@0
   525
colas@0
   526
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old ==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.
colas@0
   527
colas@0
   528
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.
colas@0
   529
colas@0
   530
%T% If things aren't working correctly, there may be useful entries in =data/warning.txt=.
colas@0
   531
colas@0
   532
@
colas@0
   533
colas@0
   534
colas@0
   535
1.21
colas@0
   536
log
colas@0
   537
@buildrelease
colas@0
   538
@
colas@0
   539
text
colas@0
   540
@d1 1
colas@0
   541
a1 1
colas@0
   542
%META:TOPICINFO{author="TWikiContributor" date="1117921800" format="1.0" version="21"}%
colas@0
   543
d13 5
colas@0
   544
a17 5
colas@0
   545
	1. Define a form template
colas@0
   546
	1. Enable the form for a web
colas@0
   547
	1. Add the form to a [[TWikiTemplates#Template_Topics][template topic]]
colas@0
   548
	1. Build an HTML form to create new topics based on that template topic
colas@0
   549
	1. Build a FormattedSearch to list topics that share the same form
colas@0
   550
d25 15
colas@0
   551
a39 15
colas@0
   552
	* *form template* - a set of fields defining a form
colas@0
   553
		* A web can use one or more form templates
colas@0
   554
	* *form* - additional meta data (besides the freeform TEXTAREA) attached to a topic
colas@0
   555
		* Within a form-enabled web, individual topics can have a form or no form
colas@0
   556
	* *form field* - a named item in a form (also known as a _key_)
colas@0
   557
	* *field type* - selects the field type:
colas@0
   558
	  | *Input type* | *Type field* | *Size field* | *Value field* |
colas@0
   559
	  | One or more checkboxes | =checkbox= | number of items per line | comma list of item labels |
colas@0
   560
	  | One or more checkboxes, plus *Set* and *Clear* buttons | =checkbox+buttons= | (same) | (same) |
colas@0
   561
	  | One or more radio buttons (radio buttons are mutually exclusive; only one can be selected) | =radio= | (same) | (same) |
colas@0
   562
	  | Read-only label text | =label= | _ignored_ | text |
colas@0
   563
	  | Drop-down menu or scrollable box | =select= | =1= for drop down, =2= and up for scrollable box | comma-separated list of options |
colas@0
   564
	  | 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 |
colas@0
   565
	  | 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 |
colas@0
   566
	* *field value* - one or more values from a fixed set (select, checkbox, radio type) or free-form (label, text, text area).
colas@0
   567
d43 4
colas@0
   568
a46 4
colas@0
   569
	1. Create a new topic with your form name: ==<nop>YourForm==, ==<nop>ExpenseReportForm==, ==<nop>InfoCategoryForm==, ==<nop>RecordReviewForm==, whatever you need.
colas@0
   570
	1. 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)_.
colas@0
   571
	1. For each field, fill in a new line; for the type of field, select from the list.
colas@0
   572
	1. Save the topic _(you can later choose to [[#EnablingForms][enable/disable]] individual forms)_.
colas@0
   573
d66 15
colas@0
   574
a80 15
colas@0
   575
	* In the <nop>WebForm topic, define the form:
colas@0
   576
	  <br />
colas@0
   577
	  | *Name* | *Type* | *Size* | *Values*  | *Tooltip message* | *Attributes* |
colas@0
   578
	  | <nop>TopicClassification | select | 1 |	 | blah blah... | &nbsp; |
colas@0
   579
	  | <nop>OperatingSystem | checkbox | 3 |	 | blah blah... | &nbsp; |
colas@0
   580
	  | <nop>OsVersion | text | 16 |	 | blah blah... | &nbsp; |
colas@0
   581
	  <br />
colas@0
   582
	  %X% Leave the ==Values== field *blank*.
colas@0
   583
colas@0
   584
	* Then in the <nop>TopicClassification topic, define the possible values:
colas@0
   585
	  <br />
colas@0
   586
	  | *Name* | *Type* | *Tooltip message* |
colas@0
   587
	  | <nop>NoDisclosure | option | blah blah... |
colas@0
   588
	  | Public Supported | option | blah blah... |
colas@0
   589
	  | Public FAQ | option | blah blah... |
colas@0
   590
d93 12
colas@0
   591
a104 12
colas@0
   592
	* 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.
colas@0
   593
	* 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.
colas@0
   594
	* If a =label= field has no name (blank first column in the form definition) it will *not* be shown when the form is *viewed*, only when it is *edited*.
colas@0
   595
	* The topic definition is not read when a topic is viewed.
colas@0
   596
	* Field names can 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  ==[<nop>[...]]== 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. 
colas@0
   597
	* 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 ==[<nop>[...]]== notation.
colas@0
   598
	* The topic defining field values can also be generated through a %TWIKIWEB%.FormattedSearch, which must yield a suitable table as the result.
colas@0
   599
	* 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.
colas@0
   600
	* The ==Tooltip message== column is used as a tooltip for the field name (only if field name is a %TWIKIWEB%.WikiName) - you only see the tooltip in edit view.
colas@0
   601
	* The ==Attributes== column is used to define special behavior for that form field (multiple attributes can be entered, with or without separators):
colas@0
   602
		* An attribute =H= indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
colas@0
   603
		* 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. 
colas@0
   604
d113 1
colas@0
   605
a113 1
colas@0
   606
	* <nop>Set WEBFORMS = <nop>BugForm, <nop>FeatureForm, Books.<nop>BookLoanForm
colas@0
   607
d115 1
colas@0
   608
a115 1
colas@0
   609
	* 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.
colas@0
   610
d119 1
colas@0
   611
a119 1
colas@0
   612
	* Edit a topic and follow the "Add form" button to add a Form to the topic. This is typically done to a [[TWikiTemplates#TemplateTopic][template topic]], 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.
colas@0
   613
d121 13
colas@0
   614
a133 13
colas@0
   615
	* 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:
colas@0
   616
		* other than checkboxes: ==name==, ex: ==?BugPriority=1==
colas@0
   617
		* checkbox: ==namevalue=1==, ex: ==?ColorRed=1==. <br /> 
colas@0
   618
		  Boxes with a tick must be specified.
colas@0
   619
		* Example: This will add a textfield for the new topic name and a "Create"-Button to your topic. When the button is pressed, the topic editor will open with the form "MyForm" already attached to the new topic.
colas@0
   620
		 <verbatim>
colas@0
   621
	 <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/">
colas@0
   622
		 <input type="hidden" name="formtemplate" value="MyForm" />
colas@0
   623
		 New topic name <input type="text" name="topic" size="40" />
colas@0
   624
		 <input type="submit" value="Create" />
colas@0
   625
	 </form>
colas@0
   626
		 </verbatim>
colas@0
   627
	* __%T% Tip:__ For TWiki applications you can [[TWikiTemplates#AutomaticallyGeneratedTopicname][automatically generate unique topicnames]].
colas@0
   628
d135 1
colas@0
   629
a135 1
colas@0
   630
	* __%X% Note:__ Initial values will not be submitted to the form of a new topic if you only use the formtemplate parameter.
colas@0
   631
d138 2
colas@0
   632
a139 2
colas@0
   633
	
colas@0
   634
	* New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a =<nop>SubmitExpenseReport= topic where you can create new expense reports, a =<nop>SubmitVacationRequest= topic, and so on. These can specify the required template topic with its associated form. [[TWikiTemplates#TemplateTopics][Template topics]] has more.
colas@0
   635
d142 1
colas@0
   636
a142 1
colas@0
   637
	* You can change a form definition, and TWiki will try to make sure you don't lose any data from the topics that use that form. 
colas@0
   638
d144 1
colas@0
   639
a144 1
colas@0
   640
	* If you change the form definition, the changes will not take affect in a topic that uses that form until you edit and save it.
colas@0
   641
d146 1
colas@0
   642
a146 1
colas@0
   643
	* If you add a new field to the form, then it will appear next time you edit a topic that uses the form.
colas@0
   644
d148 1
colas@0
   645
a148 1
colas@0
   646
	* If you delete a field from the form, or change a field name, then the data will not be visible when you edit the topic (the changed form definition will be used). *If you save the topic, the old data will be lost* (though thanks to revision control, you can always see it in older versions of the topic)
colas@0
   647
d166 2
colas@0
   648
a167 2
colas@0
   649
	* any type name starting with =checkbox=
colas@0
   650
	* any type name with =+multi= anywhere in the name
colas@0
   651
d171 1
colas@0
   652
a171 1
colas@0
   653
	* Some browsers may strip linefeeds from =text= fields when a topic is saved. If you need linefeeds in a field, make sure it is a =textarea=.
colas@0
   654
@
colas@0
   655
colas@0
   656
colas@0
   657
1.20
colas@0
   658
log
colas@0
   659
@none
colas@0
   660
@
colas@0
   661
text
colas@0
   662
@d1 1
colas@0
   663
a1 2
colas@0
   664
%META:TOPICINFO{author="PeterThoeny" date="1092981301" format="1.0" version="1.20"}%
colas@0
   665
%META:TOPICPARENT{name="WebHome"}%
colas@0
   666
d6 1
colas@0
   667
a6 1
colas@0
   668
_Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web &amp; topic_
colas@0
   669
d10 1
colas@0
   670
a10 1
colas@0
   671
By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved. 
colas@0
   672
d12 6
colas@0
   673
a17 1
colas@0
   674
Form Templates replace <nop>TWikiCategoryTables from the 01-Dec-2000 version of TWiki. - see [[#FormsVsCategoryTables]]
colas@0
   675
d21 1
colas@0
   676
a21 1
colas@0
   677
A Form Template is simply a page containing your form, defined as a table where each row is one form field.
colas@0
   678
d25 1
colas@0
   679
a25 1
colas@0
   680
	* *form template* - a set of fields defining a form (replaces _category table definition_)
colas@0
   681
d27 1
colas@0
   682
a27 1
colas@0
   683
	* *form* - a topic containing additional meta data (besides the freeform TEXTAREA) that categorizes the content (replaces _category table_)
colas@0
   684
d29 2
colas@0
   685
a30 2
colas@0
   686
	* *form field* - a named item in a form (replaces _category item name_)
colas@0
   687
	* *field type* - selects the INPUT type:
colas@0
   688
d32 1
colas@0
   689
a32 1
colas@0
   690
	  | One or more checkboxes | =checkbox= | number of checkboxes per line | comma list of checkbox labels |
colas@0
   691
d34 6
colas@0
   692
a39 6
colas@0
   693
	  | Read-only label text | =label= | =1= | (unused) |
colas@0
   694
	  | One or more radio buttons | =radio= | number of radio buttons per line | comma list of checkbox labels |
colas@0
   695
	  | Drop-down menu or scrollable box | =select= | =1= for drop down, =2= and up for scrollable box | comma list of options |
colas@0
   696
	  | A one-line text field | =text= | text box width in number of characters | (unused) |
colas@0
   697
	  | A text box; size is 40x10 (columns x rows) | =textarea= | columns x rows, e.g. =40x6= | (unused) |
colas@0
   698
	* *field value* - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces _category item value_)
colas@0
   699
d41 1
colas@0
   700
a41 1
colas@0
   701
---+++ Defining a Form in One Topic
colas@0
   702
d43 2
colas@0
   703
a44 2
colas@0
   704
	1. Create a new topic with your form name: ==<nop>YourForm==, ==<nop>ExpenseReport==, ==<nop>InfoCategory==, ==<nop>RecordReview==, whatever you need.
colas@0
   705
	1. Create a TWiki table, with each column head representing one element of an entry field: ==Name==, ==Type==, ==Size==, ==Values==, and ==Tooltip message== _(see sample below)_.
colas@0
   706
d49 10
colas@0
   707
a58 10
colas@0
   708
*Example:* ==<nop>WebForm== %BR%
colas@0
   709
=| <nop>*Name* | <nop>*Type* | <nop>*Size* | <nop>*Values* | <nop>*Tooltip message* |= %BR%
colas@0
   710
=| !TopicClassification | select | 1 | !NoDisclosure, !PublicSupported, !PublicFAQ | blah blah... |= %BR%
colas@0
   711
=| !OperatingSystem | checkbox | 3 | !OsHPUX, !OsLinux, !OsSolaris, !OsWin | blah blah... |= %BR%
colas@0
   712
=| !OsVersion | text | 16 | | blah blah... |=
colas@0
   713
colas@0
   714
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* |
colas@0
   715
| <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/TopicClassification"><nop>TopicClassification</a> | select |  1  | <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/NoDisclosure"><nop>NoDisclosure</a>, <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/PublicSupported"><nop>PublicSupported</a>, <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/PublicFAQ"><nop>PublicFAQ</a> | blah blah... |
colas@0
   716
| <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/OperatingSystem"><nop>OperatingSystem</a> | checkbox |  3  | <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/OsHPUX"><nop>OsHPUX</a>, <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/OsLinux"><nop>OsLinux</a>, <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/OsSolaris"><nop>OsSolaris</a>, <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/OsWin"><nop>OsWin</a> | blah blah... |
colas@0
   717
| <a href="%SCRIPTURL%/view%SCRIPTSUFFIX%/Sandbox/OsVersion"><nop>OsVersion</a> | text |  16  | | blah blah... |
colas@0
   718
d61 1
colas@0
   719
a61 6
colas@0
   720
---+++ Defining a Form with Multiple Topics
colas@0
   721
colas@0
   722
Forms can also be defined by using form templates that retrieve field values from one or more separate topics:
colas@0
   723
colas@0
   724
	* A ==FormTemplate== topic defines the Form, ex: ==<nop>YourFormTemplate==.
colas@0
   725
	* For each field that has a value list - select, radio, checkbox - can use separate topic to define the available values.
colas@0
   726
d64 1
colas@0
   727
a64 1
colas@0
   728
*Example: <nop>WebFormTemplate*
colas@0
   729
d66 6
colas@0
   730
a71 6
colas@0
   731
	* <nop><nop>WebFormTemplate main definition:
colas@0
   732
	  <br /> &nbsp;
colas@0
   733
	  | *Name* | *Type* | *Size* | *Values*  | *Tooltip message* |
colas@0
   734
	  | <nop>TopicClassification | select | 1 |	 | blah blah... |
colas@0
   735
	  | <nop>OperatingSystem | checkbox | 3 |	 | blah blah... |
colas@0
   736
	  | <nop>OsVersion | text | 16 |	 | blah blah... |
colas@0
   737
d75 2
colas@0
   738
a76 2
colas@0
   739
	* <nop><nop>TopicClassification field value definition:
colas@0
   740
	  <br /> &nbsp;
colas@0
   741
d79 2
colas@0
   742
a80 2
colas@0
   743
	  | <nop>PublicSupported | option | blah blah... |
colas@0
   744
	  | <nop>PublicFAQ | option | blah blah... |
colas@0
   745
d83 23
colas@0
   746
a105 6
colas@0
   747
	* *Implementation Notes:* This format allows you to define field items with or without TWiki.WikiNames, depending on your needs.
colas@0
   748
		* Topics can be protected in the usual manner, using  TWikiAccessControl, to limit who can change the form template and/or individual value lists.
colas@0
   749
		* ==[<nop>[...]]== links can be used to force a link (at present, the ==[<nop>[...][...]]== format is not supported).
colas@0
   750
		* The ==Tooltip message== column is used as a tooltip for the field name (only if field name is a %TWIKIWEB%.WikiName) - you only see the tooltip In edit.
colas@0
   751
		* The first item in the list is the default item. Alternative initial values can be set in a topic template, like ==WebTopicEditTemplate==, with ==field=value==, or, for checkboxes, ==field<checkbox name>=1==.
colas@0
   752
		* The topic definition is not read when a topic is viewed.
colas@0
   753
d110 5
colas@0
   754
a114 3
colas@0
   755
Forms are enabled on a per web basis. The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible form templates. Example:
colas@0
   756
	* <nop>Set WEBFORMS = <nop>BugForm, <nop>FeatureForm, <nop>BookLoanForm
colas@0
   757
colas@0
   758
d117 1
colas@0
   759
a117 1
colas@0
   760
---++ Including Forms in New Topics
colas@0
   761
d119 1
colas@0
   762
a119 1
colas@0
   763
	* 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.  
colas@0
   764
d121 1
colas@0
   765
a121 1
colas@0
   766
	* Additionally 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:
colas@0
   767
d125 9
colas@0
   768
d135 1
colas@0
   769
a135 1
colas@0
   770
---++ Setting Up Multiple Form Options
colas@0
   771
d137 1
colas@0
   772
a137 1
colas@0
   773
	* The optional ==WEBFORMS== variable defines alternative forms that can be selected by pressing *Change* in edit mode.
colas@0
   774
d139 6
colas@0
   775
a144 3
colas@0
   776
	* A topic template can use any form.
colas@0
   777
	
colas@0
   778
	* New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a =<nop>SubmitExpenseReport= topic where you can create new expense reports, a =<nop>SubmitVacationRequest= topic, and so on. These can specify the required template topic with its associated form.
colas@0
   779
d146 1
colas@0
   780
a146 1
colas@0
   781
---++ Form Data Storage
colas@0
   782
d148 1
colas@0
   783
a148 1
colas@0
   784
The form topic name, fields and values are stored as TWikiMetaData - the order of the field/value pairs is the same as in the template.
colas@0
   785
d151 21
colas@0
   786
a171 2
colas@0
   787
---++ Using Form Data
colas@0
   788
TWikiForms 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, ==SEARCH== and ==METASEARCH== variables in TWikiVariables, and [[FormattedSearch][TWiki Formatted Search]] for various options.
colas@0
   789
d174 1
colas@0
   790
a174 1
colas@0
   791
---++ Main Changes from Category Tables
colas@0
   792
d176 1
colas@0
   793
a176 9
colas@0
   794
The Form Template system is a more powerful, flexible replacement for the original <nop>TWikiCategoryTable. Data from existing category tables can be imported directly.
colas@0
   795
 
colas@0
   796
|  *Form Templates*  |  *Category Tables*  |
colas@0
   797
|  defined in topics  |  defined in templates  |
colas@0
   798
|  many forms per web  |  one table per web  |
colas@0
   799
|  saved as Meta Data  |  saved as HTML  |
colas@0
   800
|  *Change* &amp; *Add Form* buttons  |  *<nop>UseCategory* radio button  |
colas@0
   801
colas@0
   802
---+++ Importing Category Table Data
colas@0
   803
d182 1
colas@0
   804
a182 4
colas@0
   805
%T% *NOTE:* If things aren't working correctly, there may be useful entries in =data/warning.txt=.
colas@0
   806
colas@0
   807
---++ Using Forms For Settings
colas@0
   808
Example process to change your WebPreferences to use forms instead of ={3 spaces}* Set= statements:
colas@0
   809
a183 54
colas@0
   810
	1 create !WebPrefencesForm topic
colas@0
   811
	2 fill it with a table like this: %BR%
colas@0
   812
	  =| *Name*|*Type*|*Size*|*Value*|*Tooltip message*|*Attributes*|= %BR%
colas@0
   813
	  =| WEBTOPICLIST |textarea| |	  | List of topics of the !%WEB% web |S|= %BR%
colas@0
   814
	  =| SITEMAPLIST  |select  |3| on, | list this web in the Site Map  |S|= %BR%
colas@0
   815
	  =| SITEMAPWHAT  |textarea| |	  | short web summary				 |S|= %BR%
colas@0
   816
	  =| WEBBGCOLOR	|text	 |8|	  | Web specific background color |S|= %BR%
colas@0
   817
	  etc...
colas@0
   818
	3 Edit WebPreferences and:
colas@0
   819
		* Add or Change the form to !WebPrefencesForm
colas@0
   820
		* add !WebPrefencesForm to the =Set WEBFORMS= line
colas@0
   821
		* Save
colas@0
   822
	4 Edit WebPreferences, jump straight down to the form ignoring all the =textarea= stuff, and set as you like
colas@0
   823
	5 if everything works as you like it, you can delete the Set statements (the form overrides set if they are both used).
colas@0
   824
colas@0
   825
__Notes:__
colas@0
   826
colas@0
   827
If it isn't working, double check that the ==S== attribute has been specified (S for Setting).
colas@0
   828
If you change the form, the changes will not take affect until you edit and save the preferences' topics again.
colas@0
   829
colas@0
   830
Using the TWiki:Plugins.EditTablePlugin on !WebPreferencesForm makes adding new prefedrences a breeze.
colas@0
   831
colas@0
   832
A possibly unwanted side effect for using forms for the SKINS setting in their personal user topic: because the User Preferences are final you can't have different skins for different webs as the user's setting always wins. A workaround is to simply omit SKIN in the form.
colas@0
   833
colas@0
   834
Another example, this one using !EditTablePlugin, source:
colas@0
   835
colas@0
   836
=%<nop>EDITTABLE{ header="|*Name*|*Type*|*Size*|*Values*|*Tooltip message*|*Attributes*|" format="|text,20|text,20|text,20|text,20|text,20|text,1|" }%=
colas@0
   837
colas@0
   838
Result (after some editing):
colas@0
   839
colas@0
   840
%EDITTABLE{ header="|*Name*|*Type*|*Size*|*Values*|*Tooltip message*|*Attributes*|" format="|text,20|text,20|text,20|text,20|text,20|text,1|" }%
colas@0
   841
|*Name* | *Type* | *Size* | *Values* | *tooltip message* | *Attributes*|
colas@0
   842
|ALLOWTOPICCHANGE | textarea |  |  | Users or groups __allowed__ to change or rename this <nop>%TOPIC% topic: (I.e. %MAINWEB%.TWikiAdminGroup) | S|
colas@0
   843
|ALLOWWEBCHANGE | textarea |  |  | Users or groups who __are__  allowed to  __change__ topics in the <nop>%WEB% web: (See %TWIKIWEB%.TWikiAccessControl) | S|
colas@0
   844
|ALLOWWEBRENAME | textarea |  | %MAINWEB%.TWikiAdminGroup | Users or groups who __are__  allowed to  __rename__ topics in the <nop>%WEB% web: (See %TWIKIWEB%.TWikiAccessControl) | S|
colas@0
   845
|ALLOWWEBVIEW | textarea |  |  | Users or groups who __are__  allowed to __view__  topics in the <nop>%WEB% web: (See %TWIKIWEB%.TWikiAccessControl) | S|
colas@0
   846
|DENYWEBCHANGE | textarea |  |  | Users or groups who __are not__  allowed to  __change__ topics in the <nop>%WEB% web: (See %TWIKIWEB%.TWikiAccessControl) | S|
colas@0
   847
|DENYWEBRENAME | textarea |  |  | Users or groups who __are not__  allowed to  __rename__ topics in the <nop>%WEB% web: (See %TWIKIWEB%.TWikiAccessControl) | S|
colas@0
   848
|DENYWEBVIEW | textarea |  |  | Users or groups who __are not__  allowed to __view__  topics in the <nop>%WEB% web: (See %TWIKIWEB%.TWikiAccessControl) | S|
colas@0
   849
|FINALPREFERENCES | textarea |  | "NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME" | Web preferences that are *not* allowed to be overridden by user preferences | S|
colas@0
   850
|NOSEARCHALL | text |  | ",on" | "Exclude web from a =web=""all""= search: (Set to =on= for hidden webs)" | S|
colas@0
   851
|SITEMAPLIST | select |  | "on, ," | List this web in the %TWIKIWEB%.SiteMap | S|
colas@0
   852
|SITEMAPUSETO | textarea |  | ...to do something. | ...to do something. | S|
colas@0
   853
|SITEMAPWHAT | textarea |  | Describe what this web does. | Describe what this web does. | |
colas@0
   854
|SKIN | select |  | "twiki, free, gnu, koala, pattern, plain, tiger" | list of installed skins | S|
colas@0
   855
|WEBBGCOLOR | select |  | lightpink, pink, crimson, lavenderblush, palevioletred, hotpink, deeppink, mediumvioletred, orchid, thistle, plum, violet, fuchsia, fuchsia, darkmagenta, purple, mediumorchid, darkviolet, darkorchid, indigo, blueviolet, mediumpurple, mediumslateblue, slateblue, darkslateblue, ghostwhite, lavender, blue, mediumblue, darkblue, navy, midnightblue, royalblue, cornflowerblue, lightsteelblue, lightslategray, slategray, dodgerblue, aliceblue, steelblue, lightskyblue, skyblue, deepskyblue, lightblue, powderblue, cadetblue, darkturquoise, azure, lightcyan, paleturquoise, aqua, aqua, darkcyan, teal, darkslategray, mediumturquoise, lightseagreen, turquoise, aquamarine, mediumaquamarine, mediumspringgreen, mintcream, springgreen, mediumseagreen, seagreen, honeydew, darkseagreen, palegreen, lightgreen, limegreen, lime, forestgreen, green, darkgreen, lawngreen, chartreuse, greenyellow, darkolivegreen, yellowgreen, olivedrab, ivory, beige, lightyellow, lightgoldenrodyellow, yellow, olive, darkkhaki, palegoldenrod, lemonchiffon, khaki, gold, cornsilk, goldenrod, darkgoldenrod, floralwhite, oldlace, wheat, orange, moccasin, papayawhip, blanchedalmond, navajowhite, antiquewhite, tan, burlywood, darkorange, bisque, linen, peru, peachpuff, sandybrown, chocolate, saddlebrown, seashell, sienna, lightsalmon, coral, orangered, darksalmon, tomato, salmon, mistyrose, lightcoral, snow, rosybrown, indianred, red, brown, firebrick, darkred, maroon, white, whitesmoke, gainsboro, lightgrey, silver, darkgray, gray, dimgray, black | Web specific background color: (Pick a lighter one of the %TWIKIWEB%.StandardColors) | S|
colas@0
   856
|WEBFORMS | textarea |  |  | %TWIKIWEB%.TWikiForms: How to enable form(s) | S|
colas@0
   857
|WEBTOPICLIST | textarea |  | [[WebHome]], [[WebChanges][Changes]], [[WebTopicList][Topics]], [[WebIndex][Index]], [[WebSearch][Search]], Go <input type="text" name="topic" size="16" /> | the main entry point topics for this web | S|
colas@0
   858
colas@0
   859
colas@0
   860
-- TWiki:Main.JohnTalintyre - 16 Aug 2001 %BR%
colas@0
   861
-- TWiki:Main.MikeMannix - 05 Jan 2002 %BR%
colas@0
   862
-- TWiki:Main.PeterThoeny - 25 Apr 2004 %BR%
colas@0
   863
-- TWiki:Main.MattWilkie - 27 Jul 2004 %BR%
colas@0
   864
d186 1
colas@0
   865
a186 1
colas@0
   866
%META:TOPICMOVED{by="MikeMannix" date="1000277489" from="TWiki.TWikiFormTemplate" to="TWiki.TWikiForms"}%
colas@0
   867
@
colas@0
   868
colas@0
   869
colas@0
   870
1.19
colas@0
   871
log
colas@0
   872
@none
colas@0
   873
@
colas@0
   874
text
colas@0
   875
@d1 1
colas@0
   876
a1 1
colas@0
   877
%META:TOPICINFO{author="PeterThoeny" date="1092563338" format="1.0" version="1.19"}%
colas@0
   878
d32 1
colas@0
   879
a32 1
colas@0
   880
	  | Drop-down menu or scrollable box | =label= | =1= for drop down, =2= and up for scrollable box | comma list of options |
colas@0
   881
@
colas@0
   882
colas@0
   883
colas@0
   884
1.18
colas@0
   885
log
colas@0
   886
@none
colas@0
   887
@
colas@0
   888
text
colas@0
   889
@d1 1
colas@0
   890
a1 1
colas@0
   891
%META:TOPICINFO{author="PeterThoeny" date="1082875802" format="1.0" version="1.18"}%
colas@0
   892
d45 5
colas@0
   893
a49 9
colas@0
   894
*Example:* ==<nop>WebForm==
colas@0
   895
<verbatim>
colas@0
   896
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* |
colas@0
   897
| Know.TopicClassification | select | 1 | Know.NoDisclosure, 
colas@0
   898
  Know.PublicSupported, Know.PublicFAQ | blah blah... |
colas@0
   899
| Know.OperatingSystem | checkbox | 3 | Know.OsHPUX, Know.OsLinux,
colas@0
   900
  Know.OsSolaris, Know.OsWin | blah blah... |
colas@0
   901
| Know.OsVersion | text | 16 | | blah blah... |
colas@0
   902
</verbatim>
colas@0
   903
d52 3
colas@0
   904
a54 3
colas@0
   905
| Know.TopicClassification | select |  1  | Know.NoDisclosure, Know.PublicSupported, Know.PublicFAQ | blah blah... |
colas@0
   906
| Know.OperatingSystem | checkbox |  3  | Know.OsHPUX, Know.OsLinux, Know.OsSolaris, Know.OsWin | blah blah... |
colas@0
   907
| Know.OsVersion | text |  16  | | blah blah... |
colas@0
   908
d67 1
colas@0
   909
a67 1
colas@0
   910
	* Know.<nop>WebFormTemplate main definition:
colas@0
   911
d70 3
colas@0
   912
a72 3
colas@0
   913
	  | Know.TopicClassification | select | 1 |	 | blah blah... |
colas@0
   914
	  | Know.OperatingSystem | checkbox | 3 |	 | blah blah... |
colas@0
   915
	  | Know.OsVersion | text | 16 |	 | blah blah... |
colas@0
   916
d76 1
colas@0
   917
a76 1
colas@0
   918
	* Know.<nop>TopicClassification field value definition:
colas@0
   919
d79 3
colas@0
   920
a81 3
colas@0
   921
	  | Know.NoDisclosure | option | blah blah... |
colas@0
   922
	  | Know.PublicSupported | option | blah blah... |
colas@0
   923
	  | Know.PublicFAQ | option | blah blah... |
colas@0
   924
d105 1
colas@0
   925
a105 1
colas@0
   926
		* checkbox: ==namevalue=1==, ex: ==?ColourRed=1==. <br /> 
colas@0
   927
d143 53
colas@0
   928
d198 2
colas@0
   929
a199 1
colas@0
   930
-- TWiki:Main.PeterThoeny - 25 Apr 2004
colas@0
   931
@
colas@0
   932
colas@0
   933
colas@0
   934
1.17
colas@0
   935
log
colas@0
   936
@none
colas@0
   937
@
colas@0
   938
text
colas@0
   939
@d1 1
colas@0
   940
a1 1
colas@0
   941
%META:TOPICINFO{author="PeterThoeny" date="1061611427" format="1.0" version="1.17"}%
colas@0
   942
d3 149
colas@0
   943
a151 145
colas@0
   944
%TOC%  
colas@0
   945
%STARTINCLUDE%
colas@0
   946
---# TWiki Forms
colas@0
   947
colas@0
   948
_Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web &amp; topic_
colas@0
   949
colas@0
   950
---++ Overview
colas@0
   951
colas@0
   952
By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved. 
colas@0
   953
colas@0
   954
Form Templates replace <nop>TWikiCategoryTables from the 01-Dec-2000 version of TWiki. - see [[#FormsVsCategoryTables]]
colas@0
   955
colas@0
   956
---++ Defining a Form Template
colas@0
   957
colas@0
   958
A Form Template is simply a page containing your form, defined as a table where each row is one form field.
colas@0
   959
colas@0
   960
---+++ Form Template Elements
colas@0
   961
colas@0
   962
	* *form template* - a set of fields defining a form (replaces _category table definition_)
colas@0
   963
		* A web can use one or more form templates
colas@0
   964
	* *form* - a topic containing additional meta data (besides the freeform TEXTAREA) that categorizes the content (replaces _category table_)
colas@0
   965
		* Within a form-enabled web, individual topics can have a form or no form
colas@0
   966
	* *form field* - a named item in a form (replaces _category item name_)
colas@0
   967
	* *field type* - selects the INPUT type:
colas@0
   968
		* *select* - drop-down menu or scrollable box
colas@0
   969
		* *checkbox* - one or more checkboxes
colas@0
   970
		* *checkbox+buttons* - one or more checkboxes, plus *Set* and *Clear* buttons
colas@0
   971
		* *radio* - one or more radio buttons
colas@0
   972
		* *text* - a one-line text field
colas@0
   973
		* *textarea* - a text box; size is 40x10 (columns x rows)
colas@0
   974
	* *field value* - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces _category item value_)
colas@0
   975
colas@0
   976
---+++ Defining a Form in One Topic
colas@0
   977
colas@0
   978
	1. Create a new topic with your form name: ==<nop>YourForm==, ==<nop>ExpenseReport==, ==<nop>InfoCategory==, ==<nop>RecordReview==, whatever you need.
colas@0
   979
	1. Create a TWiki table, with each column head representing one element of an entry field: ==Name==, ==Type==, ==Size==, ==Values==, and ==Tooltip message== _(see sample below)_.
colas@0
   980
	1. For each field, fill in a new line; for the type of field, select from the list.
colas@0
   981
	1. Save the topic _(you can later choose to [[#EnablingForms][enable/disable]] individual forms)_.
colas@0
   982
colas@0
   983
<blockquote style="background-color:#f0f0f0">
colas@0
   984
*Example:* ==<nop>WebForm==
colas@0
   985
<verbatim>
colas@0
   986
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* |
colas@0
   987
| Know.TopicClassification | select | 1 | Know.NoDisclosure, 
colas@0
   988
  Know.PublicSupported, Know.PublicFAQ | blah blah... |
colas@0
   989
| Know.OperatingSystem | checkbox | 3 | Know.OsHPUX, Know.OsLinux,
colas@0
   990
  Know.OsSolaris, Know.OsWin | blah blah... |
colas@0
   991
| Know.OsVersion | text | 16 | | blah blah... |
colas@0
   992
</verbatim>
colas@0
   993
colas@0
   994
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* |
colas@0
   995
| Know.TopicClassification | select |  1  | Know.NoDisclosure, Know.PublicSupported, Know.PublicFAQ | blah blah... |
colas@0
   996
| Know.OperatingSystem | checkbox |  3  | Know.OsHPUX, Know.OsLinux, Know.OsSolaris, Know.OsWin | blah blah... |
colas@0
   997
| Know.OsVersion | text |  16  | | blah blah... |
colas@0
   998
</blockquote>
colas@0
   999
colas@0
  1000
---+++ Defining a Form with Multiple Topics
colas@0
  1001
colas@0
  1002
Forms can also be defined by using form templates that retrieve field values from one or more separate topics:
colas@0
  1003
colas@0
  1004
	* A ==FormTemplate== topic defines the Form, ex: ==<nop>YourFormTemplate==.
colas@0
  1005
	* For each field that has a value list - select, radio, checkbox - can use separate topic to define the available values.
colas@0
  1006
colas@0
  1007
<blockquote style="background-color:#f0f0f0">
colas@0
  1008
*Example: <nop>WebFormTemplate*
colas@0
  1009
colas@0
  1010
	* Know.<nop>WebFormTemplate main definition:
colas@0
  1011
	  <br /> &nbsp;
colas@0
  1012
	  | *Name* | *Type* | *Size* | *Values*  | *Tooltip message* |
colas@0
  1013
	  | Know.TopicClassification | select | 1 |	 | blah blah... |
colas@0
  1014
	  | Know.OperatingSystem | checkbox | 3 |	 | blah blah... |
colas@0
  1015
	  | Know.OsVersion | text | 16 |	 | blah blah... |
colas@0
  1016
	  <br />
colas@0
  1017
	  %X% Leave the ==Values== field *blank*.
colas@0
  1018
colas@0
  1019
	* Know.<nop>TopicClassification field value definition:
colas@0
  1020
	  <br /> &nbsp;
colas@0
  1021
	  | *Name* | *Type* | *Tooltip message* |
colas@0
  1022
	  | Know.NoDisclosure | option | blah blah... |
colas@0
  1023
	  | Know.PublicSupported | option | blah blah... |
colas@0
  1024
	  | Know.PublicFAQ | option | blah blah... |
colas@0
  1025
</blockquote>
colas@0
  1026
colas@0
  1027
	* *Implementation Notes:* This format allows you to define field items with or without TWiki.WikiNames, depending on your needs.
colas@0
  1028
		* Topics can be protected in the usual manner, using  TWikiAccessControl, to limit who can change the form template and/or individual value lists.
colas@0
  1029
		* ==[<nop>[...]]== links can be used to force a link (at present, the ==[<nop>[...][...]]== format is not supported).
colas@0
  1030
		* The ==Tooltip message== column is used as a tooltip for the field name (only if field name is a %TWIKIWEB%.WikiName) - you only see the tooltip In edit.
colas@0
  1031
		* The first item in the list is the default item. Alternative initial values can be set in a topic template, like ==WebTopicEditTemplate==, with ==field=value==, or, for checkboxes, ==field<checkbox name>=1==.
colas@0
  1032
		* The topic definition is not read when a topic is viewed.
colas@0
  1033
colas@0
  1034
#EnablingForms
colas@0
  1035
---++ Enabling Forms by Web
colas@0
  1036
colas@0
  1037
Forms are enabled on a per web basis. The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible form templates. Example:
colas@0
  1038
	* <nop>Set WEBFORMS = <nop>BugForm, <nop>FeatureForm, <nop>BookLoanForm
colas@0
  1039
colas@0
  1040
	* 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.
colas@0
  1041
colas@0
  1042
---++ Including Forms in New Topics
colas@0
  1043
colas@0
  1044
	* 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.  
colas@0
  1045
colas@0
  1046
	* Additionally 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:
colas@0
  1047
		* other than checkboxes: ==name==, ex: ==?BugPriority=1==
colas@0
  1048
		* checkbox: ==namevalue=1==, ex: ==?ColourRed=1==. <br /> 
colas@0
  1049
		  Boxes with a tick must be specified.
colas@0
  1050
colas@0
  1051
---++ Setting Up Multiple Form Options
colas@0
  1052
colas@0
  1053
	* The optional ==WEBFORMS== variable defines alternative forms that can be selected by pressing *Change* in edit mode.
colas@0
  1054
	
colas@0
  1055
	* A topic template can use any form.
colas@0
  1056
	
colas@0
  1057
	* New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a =<nop>SubmitExpenseReport= topic where you can create new expense reports, a =<nop>SubmitVacationRequest= topic, and so on. These can specify the required template topic with its associated form.
colas@0
  1058
colas@0
  1059
---++ Form Data Storage
colas@0
  1060
colas@0
  1061
The form topic name, fields and values are stored as TWikiMetaData - the order of the field/value pairs is the same as in the template.
colas@0
  1062
colas@0
  1063
#UsingFormData
colas@0
  1064
---++ Using Form Data
colas@0
  1065
TWikiForms 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, ==SEARCH== and ==METASEARCH== variables in TWikiVariables, and [[FormattedSearch][TWiki Formatted Search]] for various options.
colas@0
  1066
colas@0
  1067
#FormsVsCategoryTables
colas@0
  1068
---++ Main Changes from Category Tables
colas@0
  1069
colas@0
  1070
The Form Template system is a more powerful, flexible replacement for the original <nop>TWikiCategoryTable. Data from existing category tables can be imported directly.
colas@0
  1071
 
colas@0
  1072
|  *Form Templates*  |  *Category Tables*  |
colas@0
  1073
|  defined in topics  |  defined in templates  |
colas@0
  1074
|  many forms per web  |  one table per web  |
colas@0
  1075
|  saved as Meta Data  |  saved as HTML  |
colas@0
  1076
|  *Change* &amp; *Add Form* buttons  |  *<nop>UseCategory* radio button  |
colas@0
  1077
colas@0
  1078
---+++ Importing Category Table Data
colas@0
  1079
colas@0
  1080
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old ==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.
colas@0
  1081
colas@0
  1082
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.
colas@0
  1083
colas@0
  1084
%T% *NOTE:* If things aren't working correctly, there may be useful entries in =data/warning.txt=.
colas@0
  1085
colas@0
  1086
-- JohnTalintyre - 16 Aug 2001 <br />
colas@0
  1087
-- Main.MikeMannix - 05 Jan 2002 
colas@0
  1088
%STOPINCLUDE%
colas@0
  1089
@
colas@0
  1090
colas@0
  1091
colas@0
  1092
1.16
colas@0
  1093
log
colas@0
  1094
@none
colas@0
  1095
@
colas@0
  1096
text
colas@0
  1097
@d1 1
colas@0
  1098
a1 1
colas@0
  1099
%META:TOPICINFO{author="PeterThoeny" date="1043486587" format="1.0" version="1.16"}%
colas@0
  1100
d13 1
colas@0
  1101
a13 20
colas@0
  1102
Form Templates replace <nop>TWikiCategoryTables from the 01-Dec-2000 version of TWiki.
colas@0
  1103
colas@0
  1104
#FormsVsCategoryTables
colas@0
  1105
---++ Main Changes from Category Tables
colas@0
  1106
colas@0
  1107
The Form Template system is a more powerful, flexible replacement for the original <nop>TWikiCategoryTable. Data from existing category tables can be imported directly.
colas@0
  1108
 
colas@0
  1109
|  *Form Templates*  |  *Category Tables*  |
colas@0
  1110
|  defined in topics  |  defined in templates  |
colas@0
  1111
|  many forms per web  |  one table per web  |
colas@0
  1112
|  saved as Meta Data  |  saved as HTML  |
colas@0
  1113
|  *Change* &amp; *Add Form* buttons  |  *<nop>UseCategory* radio button  |
colas@0
  1114
colas@0
  1115
---+++ Importing Category Table Data
colas@0
  1116
colas@0
  1117
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old ==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.
colas@0
  1118
colas@0
  1119
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.
colas@0
  1120
colas@0
  1121
%T% *NOTE:* If things aren't working correctly, there may be useful entries in =data/warning.txt=.
colas@0
  1122
d125 19
colas@0
  1123
@
colas@0
  1124
colas@0
  1125
colas@0
  1126
1.15
colas@0
  1127
log
colas@0
  1128
@none
colas@0
  1129
@
colas@0
  1130
text
colas@0
  1131
@d1 1
colas@0
  1132
a1 1
colas@0
  1133
%META:TOPICINFO{author="PeterThoeny" date="1030461300" format="1.0" version="1.15"}%
colas@0
  1134
d120 2
colas@0
  1135
a127 10
colas@0
  1136
colas@0
  1137
---++ Including Forms in New Topics
colas@0
  1138
colas@0
  1139
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. You can start all new topics with forms enabled, and pre-select a form if there's more than one available:
colas@0
  1140
colas@0
  1141
	1. *Edit* the WebTopicEditTemplate topic, adding the name of an available Form.
colas@0
  1142
	2. *Create* a new topic to check - the Form should appear with values set.
colas@0
  1143
		* Click *Change* to switch or remove Forms.
colas@0
  1144
colas@0
  1145
A form embedded in a topic also appears in a new topic. This is done by specifying the ==formtemplate== parameter in the URL.
colas@0
  1146
@
colas@0
  1147
colas@0
  1148
colas@0
  1149
1.14
colas@0
  1150
log
colas@0
  1151
@none
colas@0
  1152
@
colas@0
  1153
text
colas@0
  1154
@d1 1
colas@0
  1155
a1 1
colas@0
  1156
%META:TOPICINFO{author="MikeMannix" date="1010266200" format="1.0" version="1.14"}%
colas@0
  1157
d18 1
colas@0
  1158
a18 1
colas@0
  1159
Form Templates more powerful, flexible replacement for the original <nop>TWikiCategoryTable. Data from existing category tables can be imported directly.
colas@0
  1160
d57 1
colas@0
  1161
a57 1
colas@0
  1162
	1. Create a TWiki table, with each column head representing one element of an entry field: ==Name==, ==Type==, ==Size==, ==Values==, and ==Tooltip msessage== _(see sample below)_.
colas@0
  1163
@
colas@0
  1164
colas@0
  1165
colas@0
  1166
1.13
colas@0
  1167
log
colas@0
  1168
@none
colas@0
  1169
@
colas@0
  1170
text
colas@0
  1171
@d1 1
colas@0
  1172
a1 1
colas@0
  1173
%META:TOPICINFO{author="MikeMannix" date="1007374142" format="1.0" version="1.13"}%
colas@0
  1174
d7 1
colas@0
  1175
a7 1
colas@0
  1176
_Form-based input in topics, with name/value pairs stored as Meta Data variables; multiple forms per web &amp; topic_
colas@0
  1177
d11 1
colas@0
  1178
a11 1
colas@0
  1179
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; all data is saved. 
colas@0
  1180
d13 1
colas@0
  1181
a13 1
colas@0
  1182
Form Templates replace <nop>TWikiCategory Tables from the 01-Dec-2000 version of TWiki.
colas@0
  1183
d32 1
colas@0
  1184
a32 1
colas@0
  1185
__NOTE:__ If things aren't working correctly, there may be useful entries in =data/warning.txt=.
colas@0
  1186
d36 1
colas@0
  1187
a36 1
colas@0
  1188
A Form Template is simply a page containing your form, defined in a table where each row is one form field.
colas@0
  1189
d41 3
colas@0
  1190
a43 3
colas@0
  1191
		* A web can use one or more form templates.
colas@0
  1192
	* *form* - A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (replaces _category table_)
colas@0
  1193
		* A topic has zero or one of the defined forms. So there are topics with a form or without.
colas@0
  1194
d56 2
colas@0
  1195
a57 2
colas@0
  1196
	1. Create a new topic with your Form name: <nop>MyForm, <nop>ExpenseReport, <nop>InfoCategory, <nop>RecordReview, whatever you need.
colas@0
  1197
	1. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (see sample below).
colas@0
  1198
d59 1
colas@0
  1199
a59 1
colas@0
  1200
	1. Save the topic.
colas@0
  1201
d62 1
colas@0
  1202
a62 1
colas@0
  1203
*Example: <nop>WebForm from the TWiki.Know web*
colas@0
  1204
d80 1
colas@0
  1205
a80 1
colas@0
  1206
The Form Template can also be defined in an alternative way by using more then one topic:
colas@0
  1207
d82 2
colas@0
  1208
a83 2
colas@0
  1209
	* A Form Template topic defines the Form.
colas@0
  1210
	* Fields that have more then one value - radio, select, checkbox - can be defined in individual field value topics.
colas@0
  1211
d88 2
colas@0
  1212
a89 2
colas@0
  1213
	* Know.<nop>WebFormTemplate Form main definition:
colas@0
  1214
	  <br> &nbsp;
colas@0
  1215
d91 5
colas@0
  1216
a95 3
colas@0
  1217
	  | Know.TopicClassification | select | 1 |  ...  | blah blah... |
colas@0
  1218
	  | Know.OperatingSystem | checkbox | 3 |  ...  | blah blah... |
colas@0
  1219
	  | Know.OsVersion | text | 16 |  ...  | blah blah... |
colas@0
  1220
d98 1
colas@0
  1221
a98 1
colas@0
  1222
	  <br> &nbsp;
colas@0
  1223
d106 4
colas@0
  1224
a109 4
colas@0
  1225
		* The topic can be protected in the usual manner so that not everybody can change the form template - see TWikiAccessControl
colas@0
  1226
		* =[<nop>[...]]= links can be used for force a link, at present =[<nop>[...][...]]= format is not supported.
colas@0
  1227
		* 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.
colas@0
  1228
		* 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<checkbox name>=1.
colas@0
  1229
d112 1
colas@0
  1230
d115 1
colas@0
  1231
a115 1
colas@0
  1232
Forms are enabled on a per web basis. The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible Form Templates. Example:
colas@0
  1233
d118 1
colas@0
  1234
a118 1
colas@0
  1235
	* 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.
colas@0
  1236
d123 3
colas@0
  1237
a125 2
colas@0
  1238
		* other than checkboxes: =name=, ex: =?BugPriority=1=
colas@0
  1239
		* checkbox: =namevalue=1=, ex: =?ColourRed=1=. <br> Boxes with a tick must be specified.
colas@0
  1240
d129 1
colas@0
  1241
a129 1
colas@0
  1242
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. You can start all new topics with forms enabled, and pre-select a form if there's more than one available:
colas@0
  1243
d135 1
colas@0
  1244
a135 1
colas@0
  1245
A form embedded in a topic also appears in a new topic. This is done by specifying the =formtemplate= parameter in the URL.
colas@0
  1246
d139 1
colas@0
  1247
a139 1
colas@0
  1248
	* The optional ==WEBFORMS== variable defines alternative Form Templates that can be selected by pressing *Change* in edit mode.
colas@0
  1249
d141 1
colas@0
  1250
a141 1
colas@0
  1251
	* A Template topic can use any Form Template.
colas@0
  1252
d143 1
colas@0
  1253
a143 1
colas@0
  1254
	* New topics with a Form are created by simple HTML forms asking for a topic name. For example, you can have a =<nop>SubmitExpenseReport= topic where you can create new expense reports - a =<nop>SubmitVacationRequest= topic and so on. These can specify the required template topic with its associated Form.
colas@0
  1255
d145 1
colas@0
  1256
a145 1
colas@0
  1257
---++ Form Template Data Storage
colas@0
  1258
d147 5
colas@0
  1259
a151 1
colas@0
  1260
The Form Template topic name, fields and values are stored as TWikiMetaData. The order of field/value pairs in the Meta Data is the same as in the Template.
colas@0
  1261
d154 2
colas@0
  1262
a155 1
colas@0
  1263
-- Main.MikeMannix - 03 Dec 2001	
colas@0
  1264
@
colas@0
  1265
colas@0
  1266
colas@0
  1267
1.12
colas@0
  1268
log
colas@0
  1269
@none
colas@0
  1270
@
colas@0
  1271
text
colas@0
  1272
@d1 1
colas@0
  1273
a1 1
colas@0
  1274
%META:TOPICINFO{author="MikeMannix" date="1000548172" format="1.0" version="1.12"}%
colas@0
  1275
d3 1
colas@0
  1276
a3 1
colas@0
  1277
%TOC%
colas@0
  1278
a103 1
colas@0
  1279
colas@0
  1280
a104 1
colas@0
  1281
colas@0
  1282
a105 1
colas@0
  1283
colas@0
  1284
a106 1
colas@0
  1285
colas@0
  1286
a107 1
colas@0
  1287
colas@0
  1288
d146 1
colas@0
  1289
a146 1
colas@0
  1290
-- MikeMannix - 15 Sep 2001 <br />
colas@0
  1291
@
colas@0
  1292
colas@0
  1293
colas@0
  1294
1.11
colas@0
  1295
log
colas@0
  1296
@none
colas@0
  1297
@
colas@0
  1298
text
colas@0
  1299
@d1 1
colas@0
  1300
a1 1
colas@0
  1301
%META:TOPICINFO{author="PeterThoeny" date="1000459879" format="1.0" version="1.11"}%
colas@0
  1302
d150 2
colas@0
  1303
a151 1
colas@0
  1304
-- JohnTalintyre - 16 Aug 2001 <br>
colas@0
  1305
@
colas@0
  1306
colas@0
  1307
colas@0
  1308
1.10
colas@0
  1309
log
colas@0
  1310
@none
colas@0
  1311
@
colas@0
  1312
text
colas@0
  1313
@d1 1
colas@0
  1314
a1 1
colas@0
  1315
%META:TOPICINFO{author="MikeMannix" date="1000277643" format="1.0" version="1.10"}%
colas@0
  1316
a2 2
colas@0
  1317
%INCLUDE{"UtilTempDocNote"}%
colas@0
  1318
colas@0
  1319
d11 1
colas@0
  1320
a11 1
colas@0
  1321
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#TWiki_Meta_Data][TWikiMetaData]]; all data is saved. 
colas@0
  1322
d28 1
colas@0
  1323
a28 1
colas@0
  1324
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old ==twikicatitems.tmpl==. The replacement Form Template must be set as the first item in the WebPreferences variable ==WEBFORM=. If missing, pages will display, but attempting to edit results in an error message.
colas@0
  1325
d62 1
colas@0
  1326
a62 1
colas@0
  1327
*Example: <nop>WebFormTemplate from the TWiki.Know web*
colas@0
  1328
d104 1
colas@0
  1329
a104 1
colas@0
  1330
		
colas@0
  1331
d106 5
colas@0
  1332
a110 5
colas@0
  1333
		
colas@0
  1334
		* =[[...]]= can be used for force a link, at present =[[...][...]]= format is not supported.
colas@0
  1335
		
colas@0
  1336
		* 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.
colas@0
  1337
		
colas@0
  1338
d112 1
colas@0
  1339
a112 1
colas@0
  1340
		
colas@0
  1341
d148 1
colas@0
  1342
a148 1
colas@0
  1343
The Form Template topic name, fields and values are stored as [[TWikiDocumentation#TWikiMetaData][Meta Data]]. The order of field/value pairs in the Meta Data is the same as in the Template.
colas@0
  1344
@
colas@0
  1345
colas@0
  1346
colas@0
  1347
1.9
colas@0
  1348
log
colas@0
  1349
@none
colas@0
  1350
@
colas@0
  1351
text
colas@0
  1352
@d1 1
colas@0
  1353
a1 1
colas@0
  1354
%META:TOPICINFO{author="MikeMannix" date="1000019840" format="1.0" version="1.9"}%
colas@0
  1355
d3 2
colas@0
  1356
d7 1
colas@0
  1357
a7 1
colas@0
  1358
---# TWiki Form Templates
colas@0
  1359
d153 1
colas@0
  1360
@
colas@0
  1361
colas@0
  1362
colas@0
  1363
1.8
colas@0
  1364
log
colas@0
  1365
@none
colas@0
  1366
@
colas@0
  1367
text
colas@0
  1368
@d1 1
colas@0
  1369
a1 1
colas@0
  1370
%META:TOPICINFO{author="MikeMannix" date="999906486" format="1.0" version="1.8"}%
colas@0
  1371
d16 1
colas@0
  1372
a16 1
colas@0
  1373
---++ Changes from the Category Table System
colas@0
  1374
a18 2
colas@0
  1375
colas@0
  1376
Main changes from <nop>TWikiCategoryTable:
colas@0
  1377
d26 1
colas@0
  1378
a26 1
colas@0
  1379
---+++ Importing Existing Category Table Data
colas@0
  1380
d34 5
colas@0
  1381
a38 1
colas@0
  1382
---++ Form Template Elements
colas@0
  1383
d54 1
colas@0
  1384
a54 3
colas@0
  1385
---+++ Defining a Form Template
colas@0
  1386
colas@0
  1387
A Form Template is simply a page containing your form, defined in a table where each row is one form field.
colas@0
  1388
a70 6
colas@0
  1389
</blockquote>
colas@0
  1390
colas@0
  1391
---+++ Defining a Form in One Topic
colas@0
  1392
colas@0
  1393
<blockquote style="background-color:#f0f0f0">
colas@0
  1394
*Example: <nop>WebFormTemplate from the TWiki.Know web*
colas@0
  1395
d78 1
colas@0
  1396
a78 1
colas@0
  1397
---+++ Defining a Form in Multiple Topics
colas@0
  1398
d82 2
colas@0
  1399
a83 2
colas@0
  1400
	* A Form Template topic defines the form.
colas@0
  1401
	* Values of fields that have more then one value - radio, select, checkbox - can be defined by field value Template topics.
colas@0
  1402
d86 1
colas@0
  1403
a86 1
colas@0
  1404
*Code from:*
colas@0
  1405
d88 2
colas@0
  1406
a89 1
colas@0
  1407
	* <nop>WebFormTemplate of the TWiki.Know web:
colas@0
  1408
d91 3
colas@0
  1409
a93 3
colas@0
  1410
	  | Know.TopicClassification | select | 1 | | blah blah... |
colas@0
  1411
	  | Know.OperatingSystem | checkbox | 3 | | blah blah... |
colas@0
  1412
	  | Know.OsVersion | text | 16 | | blah blah... |
colas@0
  1413
d95 2
colas@0
  1414
a96 1
colas@0
  1415
	* <nop>TopicClassification topic:
colas@0
  1416
d103 1
colas@0
  1417
a103 3
colas@0
  1418
---++++ Implementation Notes
colas@0
  1419
colas@0
  1420
		* This format allows you to define field items with / without TWiki.WikiNames, depending on your needs.
colas@0
  1421
d128 3
colas@0
  1422
a130 1
colas@0
  1423
---++ Creating New Topics with Forms
colas@0
  1424
d132 3
colas@0
  1425
a134 1
colas@0
  1426
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.
colas@0
  1427
@
colas@0
  1428
colas@0
  1429
colas@0
  1430
1.7
colas@0
  1431
log
colas@0
  1432
@none
colas@0
  1433
@
colas@0
  1434
text
colas@0
  1435
@d1 1
colas@0
  1436
a1 1
colas@0
  1437
%META:TOPICINFO{author="MikeMannix" date="999861016" format="1.0" version="1.7"}%
colas@0
  1438
d5 1
colas@0
  1439
a5 1
colas@0
  1440
---# Form Templates
colas@0
  1441
d7 1
colas@0
  1442
a7 1
colas@0
  1443
Include form-based input in topics, with unlimited, user-selectable forms per web;  values stored as Meta Data
colas@0
  1444
d13 22
colas@0
  1445
a34 1
colas@0
  1446
Form Templates replace <nop>TWikiCategory Tables from the previous version of TWiki.
colas@0
  1447
d62 1
colas@0
  1448
a62 1
colas@0
  1449
<span style="color:#0000ff"><b>Example:</b> Form Template  </span>
colas@0
  1450
d64 6
colas@0
  1451
a69 4
colas@0
  1452
| *Name:* | *Type:* | *Size:* | *Values:* | *Tooltip message:* |
colas@0
  1453
| TopClass | select | 1 | Select one..., Private, Public | must fill |
colas@0
  1454
| Target	| checkbox+buttons | 3 | 1, No.2, No.3 | Select OS |
colas@0
  1455
| Version | text | 16 | | OS version |
colas@0
  1456
d75 2
colas@0
  1457
a76 1
colas@0
  1458
Example: <nop>WebFormTemplate of the TWiki.Know web:
colas@0
  1459
d78 5
colas@0
  1460
a82 4
colas@0
  1461
| *Name:* | *Type:* | *Size:* | *Values:* | *Tooltip message:* |
colas@0
  1462
| Know.TopicClassification | select | 1 | Know.NoDisclosure, Know.PublicSupported, Know.PublicFAQ | blah blah... |
colas@0
  1463
| Know.OperatingSystem | checkbox | 3 | Know.OsHPUX, Know.OsLinux, Know.OsSolaris, Know.OsWin | blah blah... |
colas@0
  1464
| Know.OsVersion | text | 16 | | blah blah... |
colas@0
  1465
d86 1
colas@0
  1466
a86 1
colas@0
  1467
The form template can also be defined in an alternative way by using more then one topic:
colas@0
  1468
d88 2
colas@0
  1469
a89 2
colas@0
  1470
	* A *form template topic* defines the form
colas@0
  1471
	* 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*
colas@0
  1472
d91 2
colas@0
  1473
a92 2
colas@0
  1474
</blockquote><blockquote style="background-color:#f0f0f0">
colas@0
  1475
<span style="color:#0000ff"><b>Code from:</b>  </span>
colas@0
  1476
d95 1
colas@0
  1477
a95 1
colas@0
  1478
	  | *Name:* | *Type:* | *Size:* | *Values:*  | *Tooltip message:* |
colas@0
  1479
d101 1
colas@0
  1480
a101 1
colas@0
  1481
	  | *Name:* | *Type:* | *Tooltip message:* |
colas@0
  1482
d130 3
colas@0
  1483
a132 3
colas@0
  1484
	* 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:
colas@0
  1485
		* Not checkboxes - name e.g. ?BugPriority=1
colas@0
  1486
		* Checkbox - namevalue=1 e.g. ?ColourRed=1.  Note that all boxes with a tick must be specified.
colas@0
  1487
@
colas@0
  1488
colas@0
  1489
colas@0
  1490
1.6
colas@0
  1491
log
colas@0
  1492
@none
colas@0
  1493
@
colas@0
  1494
text
colas@0
  1495
@d1 1
colas@0
  1496
a1 1
colas@0
  1497
%META:TOPICINFO{author="JohnTalintyre" date="999597196" format="1.0" version="1.6"}%
colas@0
  1498
d5 1
colas@0
  1499
a5 1
colas@0
  1500
---## Form Templates
colas@0
  1501
d7 1
colas@0
  1502
a7 1
colas@0
  1503
Topics allow for flexible free format data, sometimes you want to ensure strucutre to some of the topic information, this can be done with Forms e.g. saying what type of topic it is (e.g. Bug, Feature, FAQ entry etc) and then filling in fields using dropdowns, radio buttons etc.
colas@0
  1504
d9 1
colas@0
  1505
a9 1
colas@0
  1506
---+++ Overview
colas@0
  1507
d11 1
colas@0
  1508
a11 1
colas@0
  1509
If forms are enabled for a Web and a topic has a form you will see it as a table when viewing the page.  When you edit you will see the various edit controls below the normal text area.  There will be a button at the top of the form marked _Change_ which allows you to change to a different form, or remove the form.  If you edit a topic without a form, there will be a button _Add Form_, that let's you associate a form with the topic; note that changes you have made to the topic are not lost when you select this option.
colas@0
  1510
d13 1
colas@0
  1511
a13 1
colas@0
  1512
You can search for topics with specific form data using the %<nop>SEARCH% variable - see [[TWikiDocumentation#TWikiVariables][TWikiVariables]].
colas@0
  1513
d15 1
colas@0
  1514
a15 1
colas@0
  1515
---+++ <nop>TWikiCategoryTables Are History
colas@0
  1516
d17 3
colas@0
  1517
a19 23
colas@0
  1518
Form Templates more powerful, flexible replacement for the original <nop>TWikiCategoryTable. 
colas@0
  1519
colas@0
  1520
---++++ Changes from the Category Table System
colas@0
  1521
colas@0
  1522
Main changes from <nop>TWikiCategoryTable: The templates for category view/edit have been dropped, and the forma renders to HTML on viewing.
colas@0
  1523
colas@0
  1524
| *Form Templates* | *Category Tables* |
colas@0
  1525
| defined by topics | defined in a template file |
colas@0
  1526
| multiple forms per web | one category per web |
colas@0
  1527
| data saved in Meta variables | data saved as HTML |
colas@0
  1528
| [Change] form and [Add Form] contol buttons | <nop>UseCategory radio button |
colas@0
  1529
colas@0
  1530
---++++ Migrating Existing Category Table Data
colas@0
  1531
colas@0
  1532
The new Form Template system should work with old Category Table data with no special conversion. Old data should be transparently upgraded to the new Meta format when a page imported from the old TWiki is edited and saved in the new system for the first time.
colas@0
  1533
colas@0
  1534
On upgrading, the administrator must produce a form template topic for each web that uses the old Category Tables. =twikicatitems.tmpl= defines the categories and is used in the conversion. The form template must be set as the first item in the WebPreferences variable ==WEBFORM=. If it's not present, =view= works, but =edit= results in an _oops_ dialog result. If things aren't working correctly, there may be entries in =data/warning.txt=.
colas@0
  1535
colas@0
  1536
---+++ Form Template Elements
colas@0
  1537
colas@0
  1538
	* *Form Template:* A set of fields defining a form. (_Class_ in OO speak; used to be called _category table definition_)
colas@0
  1539
		* A web may contain more then zero or more form template.
colas@0
  1540
	* *Form:* A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (_Object_ in OO speak; used to be called _category table_)
colas@0
  1541
d21 9
colas@0
  1542
a29 9
colas@0
  1543
	* *Form Field:* A named item in a form. (Used to be called _category item name_)
colas@0
  1544
	* *Field Type:* The type of a field when editing a form. The type defines the HTML INPUT tag widgets when editing a topic:
colas@0
  1545
		* *select:* Drop down box or selector
colas@0
  1546
		* *checkbox:* One or more check boxes
colas@0
  1547
		* *checkbox+buttons:* One or more check boxes, plus [Set] and [][Clear] buttons to set/clear all checkboxes
colas@0
  1548
		* *radio:* One or more radio buttons
colas@0
  1549
		* *text:* A one-line text field
colas@0
  1550
		* *textarea:* A general text area - size is <i>rows</i>x<i>cols</i> 40x10
colas@0
  1551
	* *Field Value:* Value of a form field. Can be one or more values from a fixed set (select, checkbox, radio type) or free form (text type). (Used to be called _category item value_)
colas@0
  1552
d31 1
colas@0
  1553
a31 1
colas@0
  1554
---++++ Defining a Form Template
colas@0
  1555
d50 1
colas@0
  1556
a50 1
colas@0
  1557
---++++ Defining a Form in One Topic
colas@0
  1558
d59 1
colas@0
  1559
a59 1
colas@0
  1560
---++++ Defining a Form in Multiple Topics
colas@0
  1561
d82 1
colas@0
  1562
a82 1
colas@0
  1563
---++++ Various Implementation Notes
colas@0
  1564
d84 11
colas@0
  1565
a94 6
colas@0
  1566
	* This format allows you to define field items with / without TWiki.WikiNames, depending on your needs.
colas@0
  1567
	* The topic can be protected in the usual manner so that not everybody can change the form template - see TWikiAccessControl
colas@0
  1568
	* =[[...]]= can be used for force a link, at present =[[...][...]]= format is not supported
colas@0
  1569
	* 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
colas@0
  1570
	* 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<checkbox name>=1
colas@0
  1571
	* The topic definition is not read when a topic is viewed
colas@0
  1572
d96 1
colas@0
  1573
a96 1
colas@0
  1574
---+++ Enabling Forms by Web
colas@0
  1575
d98 1
colas@0
  1576
a98 1
colas@0
  1577
Forms are enabled on a per web basis. The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible form templates e.g.
colas@0
  1578
d101 1
colas@0
  1579
a101 1
colas@0
  1580
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 lead to a screen that enables _no form_ to be selected or one of those specified by =WEBFORMS=.
colas@0
  1581
d103 1
colas@0
  1582
a103 1
colas@0
  1583
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.  
colas@0
  1584
d105 3
colas@0
  1585
a107 3
colas@0
  1586
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:
colas@0
  1587
	* Not checkboxes - name e.g. ?BugPriority=1
colas@0
  1588
	* Checkbox - namevalue=1 e.g. ?ColourRed=1.  Note that all boxes with a tick must be specified.
colas@0
  1589
d109 1
colas@0
  1590
a109 1
colas@0
  1591
---+++ Creating New Topics with Forms
colas@0
  1592
d111 1
colas@0
  1593
a111 1
colas@0
  1594
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.
colas@0
  1595
d115 1
colas@0
  1596
a115 1
colas@0
  1597
---+++ Setting Up Multiple Form Options
colas@0
  1598
d117 5
colas@0
  1599
a121 3
colas@0
  1600
	* The optional ==WEBFORMS== variable defines alternative Form Templates that can be selected after pressing [Change] on the Edit page
colas@0
  1601
	* A template topic can use any form template 
colas@0
  1602
	* New topics with a form get instantiated by simple HTML forms asking for a topic name. If there is a <nop>SubmitExpenseReport topic were you can create new expense reports, a <nop>SubmitVacationRequest topic and so on. These can specify the required template topic and hence form. __HUH?__
colas@0
  1603
d123 1
colas@0
  1604
d125 1
colas@0
  1605
a125 1
colas@0
  1606
---+++ Form Template Data Storage
colas@0
  1607
a126 1
colas@0
  1608
The Form Template topic name, fields and values are stored in the topic [[TWikiDocumentation#TWikiMetaData][Meta Data]]. The order of field/value pairs in the Meta Data is the same as in the Template. The Form name is required for [Edit] and [Save].
colas@0
  1609
@
colas@0
  1610
colas@0
  1611
colas@0
  1612
1.5
colas@0
  1613
log
colas@0
  1614
@none
colas@0
  1615
@
colas@0
  1616
text
colas@0
  1617
@d1 1
colas@0
  1618
a1 1
colas@0
  1619
%META:TOPICINFO{author="MikeMannix" date="999346121" format="1.0" version="1.5"}%
colas@0
  1620
d108 1
colas@0
  1621
a108 1
colas@0
  1622
	* 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
colas@0
  1623
d121 2
colas@0
  1624
a122 2
colas@0
  1625
	* Not checkboxs - nameFLD e.g. ?BugPriorityFLD=1
colas@0
  1626
	* Checkbox - nameFLDvalue=1 e.g. ?ColourFLDRed=1.  Note that all boxes with a tick must be specified.
colas@0
  1627
@
colas@0
  1628
colas@0
  1629
colas@0
  1630
1.4
colas@0
  1631
log
colas@0
  1632
@none
colas@0
  1633
@
colas@0
  1634
text
colas@0
  1635
@d1 1
colas@0
  1636
a1 1
colas@0
  1637
%META:TOPICINFO{author="MikeMannix" date="999323727" format="1.0" version="1.4"}%
colas@0
  1638
d15 1
colas@0
  1639
a15 1
colas@0
  1640
---+++ Goodby to <nop>TWikiCategoryTables 
colas@0
  1641
d17 1
colas@0
  1642
a17 1
colas@0
  1643
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.
colas@0
  1644
d21 1
colas@0
  1645
a21 1
colas@0
  1646
Main changes from <nop>TWikiCategoryTable: The templates for category view/edit have been dropped.and render to HTML on viewing
colas@0
  1647
a34 1
colas@0
  1648
colas@0
  1649
d45 1
colas@0
  1650
a45 1
colas@0
  1651
		* *checkbox+buttons:* One or more check boxes, plus _set_ and _clear_ buttons to set/clear all check boxes
colas@0
  1652
d48 1
colas@0
  1653
a48 1
colas@0
  1654
		* *textarea:* A general text area - size is <i>rows</i>x<i>cols</i> e.g. 40x10
colas@0
  1655
d53 1
colas@0
  1656
a53 1
colas@0
  1657
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.
colas@0
  1658
d55 14
colas@0
  1659
a68 1
colas@0
  1660
---++++ Examples
colas@0
  1661
d86 2
colas@0
  1662
a87 1
colas@0
  1663
Above Example:
colas@0
  1664
d100 1
colas@0
  1665
d102 1
colas@0
  1666
a102 1
colas@0
  1667
---++++ Notes
colas@0
  1668
d111 1
colas@0
  1669
a111 3
colas@0
  1670
---+++ Specification
colas@0
  1671
colas@0
  1672
---++++ Enabling Forms for a Web
colas@0
  1673
d113 1
colas@0
  1674
a113 3
colas@0
  1675
By default topics can be edited in free form. A form can be added to a topic to give it more structure. Forms are enabled on a per web basis.
colas@0
  1676
colas@0
  1677
The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible form templates e.g.
colas@0
  1678
d116 1
colas@0
  1679
a116 1
colas@0
  1680
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=.
colas@0
  1681
d123 1
colas@0
  1682
d132 1
colas@0
  1683
a132 1
colas@0
  1684
	* The optional ==WEBFORMS== variable defines alternative Form Templates that can be selected after pressing [Change] button on the Edit page
colas@0
  1685
a133 1
colas@0
  1686
	* Decided not to ask user to choose a template or form template when creating a topic as goes against the KISS of Wiki systems.
colas@0
  1687
@
colas@0
  1688
colas@0
  1689
colas@0
  1690
1.3
colas@0
  1691
log
colas@0
  1692
@none
colas@0
  1693
@
colas@0
  1694
text
colas@0
  1695
@d1 1
colas@0
  1696
a1 1
colas@0
  1697
%META:TOPICINFO{author="JohnTalintyre" date="999102622" format="1.0" version="1.3"}%
colas@0
  1698
d9 2
colas@0
  1699
d13 22
colas@0
  1700
a34 1
colas@0
  1701
You can search for topics with specific form data using the %<nop>SEARCH% variable - see TWikiVariables.
colas@0
  1702
d36 1
colas@0
  1703
a36 1
colas@0
  1704
---+++ Terminology
colas@0
  1705
d52 1
colas@0
  1706
a52 19
colas@0
  1707
colas@0
  1708
---+++ Specification
colas@0
  1709
colas@0
  1710
---++++ Enable forms for a web
colas@0
  1711
colas@0
  1712
By default topics can be edited in free form. A form can be added to a topic to give it more structure. Forms are enabled on a per web basis.
colas@0
  1713
colas@0
  1714
The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible form templates e.g.
colas@0
  1715
	* <nop>Set WEBFORMS = <nop>BugForm, <nop>FeatureForm, <nop>BookLoanForm
colas@0
  1716
colas@0
  1717
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=.
colas@0
  1718
colas@0
  1719
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.  
colas@0
  1720
colas@0
  1721
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:
colas@0
  1722
	* Not checkboxs - nameFLD e.g. ?BugPriorityFLD=1
colas@0
  1723
	* Checkbox - nameFLDvalue=1 e.g. ?ColourFLDRed=1.  Note that all boxes with a tick must be specified.
colas@0
  1724
colas@0
  1725
---++++ Defining a form template
colas@0
  1726
d56 1
colas@0
  1727
a56 1
colas@0
  1728
---+++ Examples
colas@0
  1729
d58 1
colas@0
  1730
a58 1
colas@0
  1731
---++++ Defining form in one topic
colas@0
  1732
d67 1
colas@0
  1733
a67 2
colas@0
  1734
colas@0
  1735
---++++ Defining a form in multiple topics
colas@0
  1736
d97 1
colas@0
  1737
a97 1
colas@0
  1738
---+++ Changes from category system
colas@0
  1739
d99 1
colas@0
  1740
a99 7
colas@0
  1741
Main changes from TWikiCategoryTable:
colas@0
  1742
	* Name changed in the hope that form is more readily understandable than category
colas@0
  1743
	* The templates for category view/edit have been dropped
colas@0
  1744
	* Forms are defined by topics, categories were defined in a template file
colas@0
  1745
	* A Web can have multiple forms, only one category was possible
colas@0
  1746
	* Form data is saved in meta variables - see MetaDataDefinition, and render to HTML on viewing.  Category data was stored as HTML
colas@0
  1747
	* The <nop>UseCategory radio button has gone, the replacement being the _Change_ form and _Add Form_ buttons.
colas@0
  1748
d101 1
colas@0
  1749
a101 1
colas@0
  1750
---+++ Creating new topics with forms
colas@0
  1751
d103 2
colas@0
  1752
a104 1
colas@0
  1753
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.
colas@0
  1754
d106 1
colas@0
  1755
a106 1
colas@0
  1756
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.
colas@0
  1757
d108 1
colas@0
  1758
a108 1
colas@0
  1759
---+++ Topic meta data
colas@0
  1760
d110 4
colas@0
  1761
a113 1
colas@0
  1762
See MetaDataDefinition.
colas@0
  1763
d115 1
colas@0
  1764
a115 1
colas@0
  1765
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.
colas@0
  1766
d117 1
colas@0
  1767
a117 1
colas@0
  1768
The order of form field/value items in the meta-data is the same as in the form template.
colas@0
  1769
d119 1
colas@0
  1770
a119 1
colas@0
  1771
---+++ UI for multiple form templates
colas@0
  1772
d121 1
colas@0
  1773
a121 1
colas@0
  1774
	* Optional ==WEBFORMS== variable defines possible form templates that can be selected after pressing "Change" (forms) button on edit page
colas@0
  1775
d124 1
colas@0
  1776
a124 1
colas@0
  1777
	* New topics with a form get instantiated by simple HTML forms asking for a topic name, i.e. there is a <nop>SubmitExpenseReport topic were you can create new expense reports, a <nop>SubmitVacationRequest topic and so on. These can specify the required template topic and hence form.
colas@0
  1778
a125 1
colas@0
  1779
---+++ Migration of Category information
colas@0
  1780
d127 1
colas@0
  1781
a127 9
colas@0
  1782
Principle: new system should work with old data with no special conversion.
colas@0
  1783
colas@0
  1784
Old data should be transparently upgraded to the new meta format when a topic is edit/previewed/saved.
colas@0
  1785
colas@0
  1786
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=.
colas@0
  1787
colas@0
  1788
---+++ History
colas@0
  1789
colas@0
  1790
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.
colas@0
  1791
d129 1
colas@0
  1792
@
colas@0
  1793
colas@0
  1794
colas@0
  1795
1.2
colas@0
  1796
log
colas@0
  1797
@none
colas@0
  1798
@
colas@0
  1799
text
colas@0
  1800
@d1 1
colas@0
  1801
a1 1
colas@0
  1802
%META:TOPICINFO{author="JohnTalintyre" date="997965810" format="1.0beta2" version="1.2"}%
colas@0
  1803
d3 2
colas@0
  1804
d7 3
colas@0
  1805
a9 1
colas@0
  1806
%TOC%
colas@0
  1807
d11 1
colas@0
  1808
a11 1
colas@0
  1809
Topics allow for flexible free format data, sometimes you want to ensure strucutre to some of the topic information, this can be done with Forms e.g. saying what type of topic it is (Bug, Feature, FAQ entry etc).
colas@0
  1810
d63 1
colas@0
  1811
a63 1
colas@0
  1812
---++++ Defining form in multiple topics
colas@0
  1813
d111 1
colas@0
  1814
a111 1
colas@0
  1815
See TWikiMetaDataDefinition.
colas@0
  1816
d136 1
colas@0
  1817
a136 1
colas@0
  1818
-- Main.JohnTalintyre - 16 Aug 2001 <br>
colas@0
  1819
@
colas@0
  1820
colas@0
  1821
colas@0
  1822
1.1
colas@0
  1823
log
colas@0
  1824
@none
colas@0
  1825
@
colas@0
  1826
text
colas@0
  1827
@d1 1
colas@0
  1828
a1 1
colas@0
  1829
%META:TOPICINFO{author="JohnTalintyre" date="997201374" format="1.0beta2" version="1.1"}%
colas@0
  1830
d7 1
colas@0
  1831
a7 3
colas@0
  1832
---+++ Background
colas@0
  1833
colas@0
  1834
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.
colas@0
  1835
d12 1
colas@0
  1836
a12 1
colas@0
  1837
		* A web may contain more then one form template.
colas@0
  1838
d30 1
colas@0
  1839
a30 1
colas@0
  1840
By default topics can be edited in free form. A form can be added to a topic to give it more structure. Forms are enabled on a per web basis.  This can be done in two ways.  One is similar to that used for the older category system, with this a Web can have only one form.  The other allows a Web to have any number of forms.
colas@0
  1841
d32 2
colas@0
  1842
a33 1
colas@0
  1843
A default form template can be provided by creating the ==WebTopicEditTemplate== topic in a Web and adding a form to it.  Initial form values can be set here.  
colas@0
  1844
d35 1
colas@0
  1845
a35 1
colas@0
  1846
---++++ Enabling single default form
colas@0
  1847
d37 1
colas@0
  1848
a37 3
colas@0
  1849
The ==DEFAULTFORM== variable in WebPreferences is optional.  If present it specifies the default form for all topics in the Web.  Every time you edit a topic you will be presented with a form.  The form must contain the special field =UseForm= (analogous to the =UseCategory= line in the old category system).  The values for this must be:
colas@0
  1850
	* First field - "Yes" (any capitalisation)
colas@0
  1851
	* Second field - any text, but must mean _no form_
colas@0
  1852
d39 3
colas@0
  1853
a41 1
colas@0
  1854
---++++ Enabling multiple forms
colas@0
  1855
d43 1
colas@0
  1856
a43 6
colas@0
  1857
The ==WEBFORMS== variable in WebPreferences is optional and defines a list of possible form templates e.g.
colas@0
  1858
	* <nop>Set WEBFORMS = <nop>BugForm, <nop>FeatureForm, <nop>BookLoanForm
colas@0
  1859
colas@0
  1860
With this present an extra button is added to the edit view.  If the topic doesn't have a form the button appears at the end of the page.  If a form is present the button appears in the top row of the form.  Pressing the button leads to a screen that enables _no form_ to be selected of one of those specified by =WEBFORMS=.
colas@0
  1861
colas@0
  1862
---++++ Define a form template
colas@0
  1863
a53 1
colas@0
  1864
| Know.UseForm | radio | 0 | Yes, No | Select 'No' to remove the form |
colas@0
  1865
a69 1
colas@0
  1866
	  | Know.UseForm | radio | 0 | Yes, No | blah blah... |
colas@0
  1867
d83 1
colas@0
  1868
a83 1
colas@0
  1869
	* The topic can be protected in the usual manner so that not everybody can change the form template.
colas@0
  1870
d87 1
colas@0
  1871
a87 5
colas@0
  1872
	* The =UseForm= field is special.
colas@0
  1873
		* Will always default to second value (don't use form) when topic doesn't have a form
colas@0
  1874
		* Is not show on preview or view
colas@0
  1875
		* When set to no on save, form data is deleted.
colas@0
  1876
	* It is not a good idea to use both =DEFAULTFORM= and =WEBFORMS= WebPreferences in the same Web.
colas@0
  1877
a92 1
colas@0
  1878
	* =UseCategory= is now =UseForm=
colas@0
  1879
d97 1
colas@0
  1880
d101 1
colas@0
  1881
a101 1
colas@0
  1882
When you create a new topic in a web that has the WEBFORM preferences variable set you will get a topic with the default form template specified by the variable.
colas@0
  1883
d103 1
colas@0
  1884
a103 1
colas@0
  1885
For simplicity we should use the default form template when one creates a new topic by question mark link or "Go" field, i.e. better not to show a menu to select a form template.
colas@0
  1886
d115 1
colas@0
  1887
a115 1
colas@0
  1888
	* Optional ==WEBFORMS== variable defines possibles form templates that can be selected after pressing "Change" (forms) button on edit page
colas@0
  1889
d126 5
colas@0
  1890
a130 1
colas@0
  1891
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== or ==DEFAULTFORM== (if/when put in).  If it's not present, an _oops_ dialog results.
colas@0
  1892
d132 1
colas@0
  1893
a132 1
colas@0
  1894
-- Main.JohnTalintyre - 07 Aug 2001 <br>
colas@0
  1895
@