1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
## <a name="Form_Templates"> Form Templates </a>
%TOC%
### <a name="Background"> Background </a>
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.
### <a name="Terminology"> Terminology </a>
* **Form Template:** A set of fields defining a form. (_Class_ in OO speak; used to be called _category table definition_)
* A web may contain more then one form template.
* **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_)
* A topic has zero or one of the defined forms. So there are topics with a form or without.
* **Form Field:** A named item in a form. (Used to be called _category item name_)
* **Field Type:** The type of a field when editing a form. The type defines the HTML INPUT tag widgets when editing a topic:
* **select:** Drop down box or selector
* **checkbox:** One or more check boxes
* **checkbox+buttons:** One or more check boxes, plus _set_ and _clear_ buttons to set/clear all check boxes
* **radio:** One or more radio buttons
* **text:** A one-line text field
* **textarea:** A general text area - size is _rows_x_cols_ e.g. 40x10
* **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_)
### <a name="Specification"> Specification </a>
#### <a name="Enable_forms_for_a_web"> Enable forms for a web </a>
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.
A default form template can be provided by creating the <code>**WebTopicEditTemplate**</code> topic in a Web and adding a form to it. Initial form values can be set here.
#### <a name="Enabling_single_default_form"> Enabling single default form </a>
The <code>**DEFAULTFORM**</code> 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:
* First field - "Yes" (any capitalisation)
* Second field - any text, but must mean _no form_
#### <a name="Enabling_multiple_forms"> Enabling multiple forms </a>
The <code>**WEBFORMS**</code> variable in [[WebPreferences]] is optional and defines a list of possible form templates e.g.
* Set WEBFORMS = BugForm, FeatureForm, BookLoanForm
With this present an extra button is added to the edit view. If the topic doesn't have a form 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`.
#### <a name="Define_a_form_template"> Define a form template </a>
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.
### <a name="Examples"> Examples </a>
#### <a name="Defining_form_in_one_topic"> Defining form in one topic </a>
Example: WebFormTemplate of the TWiki.Know web:
<table border="1" cellpadding="1" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong>Name:</strong></th>
<th bgcolor="#99CCCC"><strong>Type:</strong></th>
<th bgcolor="#99CCCC"><strong>Size:</strong></th>
<th bgcolor="#99CCCC"><strong>Values:</strong></th>
<th bgcolor="#99CCCC"><strong>Tooltip message:</strong></th>
</tr>
<tr>
<td><span style="background:"><font color="">Use Form</font></span><a href="http://LOCATIONKnow/UseForm">?</a></td>
<td> radio </td>
<td> 0 </td>
<td> Yes, No </td>
<td> Select 'No' to remove the form </td>
</tr>
<tr>
<td><span style="background:"><font color="">Topic Classification</font></span><a href="http://LOCATIONKnow/TopicClassification">?</a></td>
<td> select </td>
<td> 1 </td>
<td><span style="background:"><font color="">No Disclosure</font></span><a href="http://LOCATIONKnow/NoDisclosure">?</a>, <span style="background:"><font color="">Public Supported</font></span><a href="http://LOCATIONKnow/PublicSupported">?</a>, <span style="background:"><font color="">Public FAQ</font></span><a href="http://LOCATIONKnow/PublicFAQ">?</a></td>
<td> blah blah... </td>
</tr>
<tr>
<td><span style="background:"><font color="">Operating System</font></span><a href="http://LOCATIONKnow/OperatingSystem">?</a></td>
<td> checkbox </td>
<td> 3 </td>
<td><span style="background:"><font color="">Os HPUX</font></span><a href="http://LOCATIONKnow/OsHPUX">?</a>, <span style="background:"><font color="">Os Linux</font></span><a href="http://LOCATIONKnow/OsLinux">?</a>, <span style="background:"><font color="">Os Solaris</font></span><a href="http://LOCATIONKnow/OsSolaris">?</a>, <span style="background:"><font color="">Os Win</font></span><a href="http://LOCATIONKnow/OsWin">?</a></td>
<td> blah blah... </td>
</tr>
<tr>
<td><span style="background:"><font color="">Os Version</font></span><a href="http://LOCATIONKnow/OsVersion">?</a></td>
<td> text </td>
<td> 16 </td>
<td> </td>
<td> blah blah... </td>
</tr>
</table>
#### <a name="Defining_form_in_multiple_topics"> Defining form in multiple topics </a>
The form template can also be defined in an alternative way by using more then one topic:
* A **form template topic** defines the form
* Values of fields that have more then one value, e.g. of type radio, select and checkbox can be defined by **field value template topics**
Above Example:
* WebFormTemplate of the TWiki.Know web: <table border="1" cellpadding="1" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong>Name:</strong></th>
<th bgcolor="#99CCCC"><strong>Type:</strong></th>
<th bgcolor="#99CCCC"><strong>Size:</strong></th>
<th bgcolor="#99CCCC"><strong>Values:</strong></th>
<th bgcolor="#99CCCC"><strong>Tooltip message:</strong></th>
</tr>
<tr>
<td><span style="background:"><font color="">Use Form</font></span><a href="http://LOCATIONKnow/UseForm">?</a></td>
<td> radio </td>
<td> 0 </td>
<td> Yes, No </td>
<td> blah blah... </td>
</tr>
<tr>
<td><span style="background:"><font color="">Topic Classification</font></span><a href="http://LOCATIONKnow/TopicClassification">?</a></td>
<td> select </td>
<td> 1 </td>
<td> </td>
<td> blah blah... </td>
</tr>
<tr>
<td><span style="background:"><font color="">Operating System</font></span><a href="http://LOCATIONKnow/OperatingSystem">?</a></td>
<td> checkbox </td>
<td> 3 </td>
<td> </td>
<td> blah blah... </td>
</tr>
<tr>
<td><span style="background:"><font color="">Os Version</font></span><a href="http://LOCATIONKnow/OsVersion">?</a></td>
<td> text </td>
<td> 16 </td>
<td> </td>
<td> blah blah... </td>
</tr>
</table>
* TopicClassification topic: <table border="1" cellpadding="1" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong>Name:</strong></th>
<th bgcolor="#99CCCC"><strong>Type:</strong></th>
<th bgcolor="#99CCCC"><strong>Tooltip message:</strong></th>
</tr>
<tr>
<td><span style="background:"><font color="">No Disclosure</font></span><a href="http://LOCATIONKnow/NoDisclosure">?</a></td>
<td> option </td>
<td> blah blah... </td>
</tr>
<tr>
<td><span style="background:"><font color="">Public Supported</font></span><a href="http://LOCATIONKnow/PublicSupported">?</a></td>
<td> option </td>
<td> blah blah... </td>
</tr>
<tr>
<td><span style="background:"><font color="">Public FAQ</font></span><a href="http://LOCATIONKnow/PublicFAQ">?</a></td>
<td> option </td>
<td> blah blah... </td>
</tr>
</table>
#### <a name="Notes"> Notes </a>
* This format allows you to define field items with / without [[TWiki/WikiNames]], depending on your needs.
* The topic can be protected in the usual manner so that not everybody can change the form template.
* `...` can be used for force a link, at present `...` format is not supported
* 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
* The first item in the list is the default item. Alternative initial values can be given in a topic template such as <code>**WebTopicEditTemplate**</code> or using fieldFLD=value or for checkboxes fieldFLDcheckbox=1 in URL
* The `UseForm` field is special.
* Will always default to second value (don't use form) when topic doesn't have a form
* Is not show on preview or view
* When set to no on save, form data is deleted.
* It is not a good idea to use both `DEFAULTFORM` and `WEBFORMS` [[WebPreferences]] in the same Web.
### <a name="Changes_from_category_system"> Changes from category system </a>
Main changes from [[TWikiCategoryTable]]:
* Name changed in the hope that form is more readily understandable than category
* `UseCategory` is now `UseForm`
* The templates for category view/edit have been dropped
* Forms are defined by topics, categories were defined in a template file
* A Web can have multiple forms, only one category was possible
* Form data is saved in meta variables - see [[MetaDataDefinition]], and render to HTML on viewing. Category data was stored as HTML
### <a name="Creating_new_topics_with_forms"> Creating new topics with forms </a>
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.
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.
### <a name="Topic_meta_data"> Topic meta data </a>
See [[TWikiMetaDataDefinition]].
The form template topic name and all form fields/values are stored in the topic meta data. The form template topic name is needed for edit and save.
The order of form field/value items in the meta-data is the same as in the form template.
### <a name="UI_for_multiple_form_templates"> UI for multiple form templates </a>
* Optional <code>**WEBFORMS**</code> variable defines possibles form templates that can be selected after pressing "Change" (forms) button on edit page
* A template topic can use any form template
* Decided not to ask user to choose a template or form template when creating a topic as goes against the KISS of Wiki systems.
* New topics with a form get instantiated by simple HTML forms asking for a topic name, i.e. there is a SubmitExpenseReport topic were you can create new expense reports, a SubmitVacationRequest topic and so on. These can specify the required template topic and hence form.
### <a name="Migration_of_Category_informatio"> Migration of Category information </a>
Principle: new system should work with old data with no special conversion.
Old data should be transparently upgraded to the new meta format when a topic is edit/previewed/saved.
On upgrading the administrator must produce a form template topic for each Web that using the old category system. `twikicatitems.tmpl` defines the categories and is used in the conversion. The form template must be put as first item in [[WebPreferences]] variable <code>**WEBFORM**</code> or <code>**DEFAULTFORM**</code> (if/when put in). If it's not present, an _oops_ dialog results.
-- [[Main/JohnTalintyre]] - 07 Aug 2001 <br />
|
