TWiki/TWikiForms.mdwn

   1 <div>
   2   <ul>
   3     <li><a href="#Form Templates"> Form Templates</a><ul>
   4         <li><a href="#Overview"> Overview</a></li>
   5         <li><a href="#Form Template Elements"> Form Template Elements</a><ul>
   6             <li><a href="#Defining a Form Template"> Defining a Form Template</a></li>
   7             <li><a href="#Defining a Form in One Topic"> Defining a Form in One Topic</a></li>
   8             <li><a href="#Defining a Form in Multiple Topi"> Defining a Form in Multiple Topics</a><ul>
   9                 <li><a href="#Implementation Notes"> Implementation Notes</a></li>
  10               </ul>
  11             </li>
  12           </ul>
  13         </li>
  14         <li><a href="#Enabling Forms by Web"> Enabling Forms by Web</a></li>
  15         <li><a href="#Creating New Topics with Forms"> Creating New Topics with Forms</a></li>
  16         <li><a href="#Setting Up Multiple Form Options"> Setting Up Multiple Form Options</a></li>
  17         <li><a href="#Form Template Data Storage"> Form Template Data Storage</a></li>
  18       </ul>
  19     </li>
  20   </ul>
  21 </div>
  22
  23 # <a name="Form Templates"></a> Form Templates
  24
  25 Include form-based input in topics, with unlimited, user-selectable forms per web; values stored as Meta Data
  26
  27 ## <a name="Overview"></a> Overview
  28
  29 By adding form-based input to free-form content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, the form appears in edit mode, and the contents are rendered as a table when viewing the actual page. When editing, can switch forms, if more than one is defined, or remove forms entirely. Form input values are stored as [[TWikiMetaData|Main/TWikiDocumentation#TWiki_Meta_Data]]; all data is saved.
  30
  31 Form Templates replace TWikiCategory Tables from the previous version of TWiki.
  32
  33 ## <a name="Form Template Elements"></a> Form Template Elements
  34
  35 - **form template** - a set of fields defining a form (replaces _category table definition_)
  36   - A web can use one or more form templates.
  37 - **form** - A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (replaces _category table_)
  38   - A topic has zero or one of the defined forms. So there are topics with a form or without.
  39 - **form field** - a named item in a form (replaces _category item name_)
  40 - **field type** - selects the INPUT type:
  41   - **select** - drop-down menu or scrollable box
  42   - **checkbox** - one or more checkboxes
  43   - **checkbox+buttons** - one or more checkboxes, plus **Set** and **Clear** buttons
  44   - **radio** - one or more radio buttons
  45   - **text** - a one-line text field
  46   - **textarea** - a text box; size is 40x10 (columns x rows)
  47 - **field value** - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces _category item value_)
  48
  49 ### <a name="Defining a Form Template"></a> Defining a Form Template
  50
  51 A Form Template is simply a page containing your form, defined in a table where each row is one form field.
  52
  53 1. Create a new topic with your Form name: MyForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
  54 2. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (see sample below).
  55 3. For each field, fill in a new line; for the type of field, select from the list.
  56 4. Save the topic.
  57
  58 > <span><font>**Example:** Form Template </font></span>
  59 >
  60 >     | *Name:* | *Type:* | *Size:* | *Values:* | *Tooltip message:* |
  61 >     | TopClass | select | 1 | Select one..., Private, Public | must fill |
  62 >     | Target   | checkbox+buttons | 3 | 1, No.2, No.3 | Select OS |
  63 >     | Version | text | 16 | | OS version |
  64
  65 ### <a name="Defining a Form in One Topic"></a> Defining a Form in One Topic
  66
  67 Example: WebFormTemplate of the TWiki.Know web:
  68
  69 <table border="1" cellpadding="0" cellspacing="0">
  70   <tr>
  71     <th bgcolor="#99CCCC"><strong> Name: </strong></th>
  72     <th bgcolor="#99CCCC"><strong> Type: </strong></th>
  73     <th bgcolor="#99CCCC"><strong> Size: </strong></th>
  74     <th bgcolor="#99CCCC"><strong> Values: </strong></th>
  75     <th bgcolor="#99CCCC"><strong> Tooltip message: </strong></th>
  76   </tr>
  77   <tr>
  78     <td>[[Know/TopicClassification]]</td>
  79     <td> select </td>
  80     <td> 1 </td>
  81     <td>[[Know/NoDisclosure]], [[Know/PublicSupported]], [[Know/PublicFAQ]]</td>
  82     <td> blah blah... </td>
  83   </tr>
  84   <tr>
  85     <td>[[Know/OperatingSystem]]</td>
  86     <td> checkbox </td>
  87     <td> 3 </td>
  88     <td>[[Know/OsHPUX]], [[Know/OsLinux]], [[Know/OsSolaris]], [[Know/OsWin]]</td>
  89     <td> blah blah... </td>
  90   </tr>
  91   <tr>
  92     <td>[[Know/OsVersion]]</td>
  93     <td> text </td>
  94     <td> 16 </td>
  95     <td>   </td>
  96     <td> blah blah... </td>
  97   </tr>
  98 </table>
  99
 100 ### <a name="Defining a Form in Multiple Topi"></a> Defining a Form in Multiple Topics
 101
 102 The form template can also be defined in an alternative way by using more then one topic:
 103
 104 - A **form template topic** defines the form
 105 - 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**
 106
 107 > <span><font>**Code from:** </font></span>
 108 >
 109 > - WebFormTemplate of the TWiki.Know web: <table border="1" cellpadding="0" cellspacing="0">
 110 >   <tr>
 111 >     <th bgcolor="#99CCCC"><strong> Name: </strong></th>
 112 >     <th bgcolor="#99CCCC"><strong> Type: </strong></th>
 113 >     <th bgcolor="#99CCCC"><strong> Size: </strong></th>
 114 >     <th bgcolor="#99CCCC"><strong> Values: </strong></th>
 115 >     <th bgcolor="#99CCCC"><strong> Tooltip message: </strong></th>
 116 >   </tr>
 117 >   <tr>
 118 >     <td>[[Know/TopicClassification]]</td>
 119 >     <td> select </td>
 120 >     <td> 1 </td>
 121 >     <td>   </td>
 122 >     <td> blah blah... </td>
 123 >   </tr>
 124 >   <tr>
 125 >     <td>[[Know/OperatingSystem]]</td>
 126 >     <td> checkbox </td>
 127 >     <td> 3 </td>
 128 >     <td>   </td>
 129 >     <td> blah blah... </td>
 130 >   </tr>
 131 >   <tr>
 132 >     <td>[[Know/OsVersion]]</td>
 133 >     <td> text </td>
 134 >     <td> 16 </td>
 135 >     <td>   </td>
 136 >     <td> blah blah... </td>
 137 >   </tr>
 138 > </table>
 139 >
 140 > - TopicClassification topic: <table border="1" cellpadding="0" cellspacing="0">
 141 >   <tr>
 142 >     <th bgcolor="#99CCCC"><strong> Name: </strong></th>
 143 >     <th bgcolor="#99CCCC"><strong> Type: </strong></th>
 144 >     <th bgcolor="#99CCCC"><strong> Tooltip message: </strong></th>
 145 >   </tr>
 146 >   <tr>
 147 >     <td>[[Know/NoDisclosure]]</td>
 148 >     <td> option </td>
 149 >     <td> blah blah... </td>
 150 >   </tr>
 151 >   <tr>
 152 >     <td>[[Know/PublicSupported]]</td>
 153 >     <td> option </td>
 154 >     <td> blah blah... </td>
 155 >   </tr>
 156 >   <tr>
 157 >     <td>[[Know/PublicFAQ]]</td>
 158 >     <td> option </td>
 159 >     <td> blah blah... </td>
 160 >   </tr>
 161 > </table>
 162
 163 #### <a name="Implementation Notes"></a> Implementation Notes
 164
 165 - - This format allows you to define field items with / without [[WikiNames]], depending on your needs.
 166
 167 - - The topic can be protected in the usual manner so that not everybody can change the form template - see [[TWikiAccessControl]]
 168
 169 - - <code>[[...|/WebHome]]</code> can be used for force a link, at present <code>[[...|/WebHome]]</code> format is not supported.
 170
 171 - - 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.
 172
 173 - - The first item in the list is the default item. Alternative initial values can be given in a topic template such as `WebTopicEditTemplate` or using field=value or for checkboxes field=1.
 174
 175 - - The topic definition is not read when a topic is viewed.
 176
 177 ## <a name="Enabling Forms by Web"></a> Enabling Forms by Web
 178
 179 Forms are enabled on a per web basis. The <code>**WEBFORMS**</code> variable in [[WebPreferences]] is optional and defines a list of possible Form Templates. Example:
 180
 181 - Set WEBFORMS = BugForm, FeatureForm, BookLoanForm
 182
 183 - 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.
 184
 185 - 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.
 186
 187 - 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:
 188   - Not checkboxes - name e.g. ?BugPriority=1
 189   - Checkbox - namevalue=1 e.g. ?ColourRed=1. Note that all boxes with a tick must be specified.
 190
 191 ## <a name="Creating New Topics with Forms"></a> Creating New Topics with Forms
 192
 193 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.
 194
 195 A form embedded in a topic also appears in a new topic. This is done by specifying the `formtemplate` parameter in the URL.
 196
 197 ## <a name="Setting Up Multiple Form Options"></a> Setting Up Multiple Form Options
 198
 199 - The optional <code>**WEBFORMS**</code> variable defines alternative Form Templates that can be selected by pressing **Change** in edit mode.
 200
 201 - A Template topic can use any Form Template.
 202
 203 - New topics with a Form are created by simple HTML forms asking for a topic name. For example, you can have a `SubmitExpenseReport` topic where you can create new expense reports - a `SubmitVacationRequest` topic and so on. These can specify the required template topic with its associated Form.
 204
 205 ## <a name="Form Template Data Storage"></a> Form Template Data Storage
 206
 207 The Form Template topic name, fields and values are stored as [[Meta Data|Main/TWikiDocumentation#TWikiMetaData]]. The order of field/value pairs in the Meta Data is the same as in the Template.
 208
 209 -- [[JohnTalintyre]] - 16 Aug 2001 <br />