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