From a84b233ffbf84933fb445bbc83ab9b976d89aa7f Mon Sep 17 00:00:00 2001 From: John Talintyre Date: Tue, 7 Aug 2001 16:22:54 +0000 Subject: none --- TWiki/TWikiForms.mdwn | 219 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 TWiki/TWikiForms.mdwn 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 @@ +## Form Templates + +%TOC% + +### Background + +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. + +### Terminology + +* **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_) + +### Specification + +#### Enable forms for a web + +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 **WebTopicEditTemplate** topic in a Web and adding a form to it. Initial form values can be set here. + +#### Enabling single default form + +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: + +* First field - "Yes" (any capitalisation) +* Second field - any text, but must mean _no form_ + +#### Enabling multiple forms + +The **WEBFORMS** 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`. + +#### Define a form template + +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. + +### Examples + +#### Defining form in one topic + +Example: WebFormTemplate of the TWiki.Know web: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name:Type:Size:Values:Tooltip message:
Use Form? radio 0 Yes, No Select 'No' to remove the form
Topic Classification? select 1 No Disclosure?, Public Supported?, Public FAQ? blah blah...
Operating System? checkbox 3 Os HPUX?, Os Linux?, Os Solaris?, Os Win? blah blah...
Os Version? text 16   blah blah...
+ +#### Defining form in multiple topics + +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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name:Type:Size:Values:Tooltip message:
Use Form? radio 0 Yes, No blah blah...
Topic Classification? select 1   blah blah...
Operating System? checkbox 3   blah blah...
Os Version? text 16   blah blah...
+ +* TopicClassification topic: + + + + + + + + + + + + + + + + + + + + +
Name:Type:Tooltip message:
No Disclosure? option blah blah...
Public Supported? option blah blah...
Public FAQ? option blah blah...
+ +#### Notes + +* 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 **WebTopicEditTemplate** 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. + +### Changes from category system + +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 + +### Creating new topics with forms + +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. + +### Topic meta data + +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. + +### UI for multiple form templates + +* Optional **WEBFORMS** 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. + +### Migration of Category information + +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 **WEBFORM** or **DEFAULTFORM** (if/when put in). If it's not present, an _oops_ dialog results. + +-- [[Main/JohnTalintyre]] - 07 Aug 2001
-- cgit v1.2.3