none

1 files changed, 219 insertions, 0 deletions

diff --git a/TWiki/TWikiForms.mdwn b/TWiki/TWikiForms.mdwn
new file mode 100644
index 00000000..f77e0fd6
--- /dev/null
+++ b/TWiki/TWikiForms.mdwn
@@ -0,0 +1,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 />