Table of contents:

Background

This discussion and spec started in CategoryEditor. This topic here is a completely refactored version of CategoryEditor.

RichardDonkin had an excellent idea when saying that a "category table" is nothing else then a "form". I prefer the "form" terminology over "category table" for situations where topics are actually forms, like in a WorkFlow system or in a knowledge base, e.g. when you have many form fields. Can this also be said for the TWiki:Codev web and the TWiki:Support web? Here we have just one "form field" (aka "category item") which is used to categorize a topic. May be yes. Anyway, "form" is a better understood terminology for what we already have, so lets do the switch in terminology.

We are shortly before a code freeze. For now we should define a clear spec with these goals in mind:

• KISS.
• Minimum impact for existing installations, easy upgrade.
• Spec can be extended in the future to support a powerful WorkFlowSystem.

This is part of TWikiReleaseSpring2001.

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 rowsxcols 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.

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. Initial values can also be provided in URLs or as form values. They are of the form:

• Not checkboxs - nameFLD e.g. ?BugPriorityFLD=1
• Checkbox - nameFLDvalue=1 e.g. ?ColourFLDRed=1. Note that all boxes with a tick must be specified.

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 an Add topic appears at the end of the topic. If a form is present a Change button appears in the top row of the form to the right of the form name. Pressing the button leads to a screen that enables no form to be selected or 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:

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:
  TopicClassification	select	1		blah blah...
  OperatingSystem	checkbox	3		blah blah...
  OsVersion	text	16		blah blah...

• TopicClassification topic:

  Name:	Type:	Tooltip message:
  NoDisclosure	option	blah blah...
  PublicSupported	option	blah blah...
  PublicFAQ	option	blah blah...

Notes

• This syntax with required type ensures that the chance of unwanted side-effects with descriptive text is minimal.
  • [ JohnTalintyre] - the type field is still not present, as I'm still confused as to it's purpose. I guess the idea is to avoid picked up incorrect data from the prevous column, but I'm not so sure this is required.
• This format allows you to define field items with / without 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 WikiName)
  • [ JohnTalintyre ] - currently gives toolip for all formats, but only on edit. Otherwise tooltip must be stored in each topic or definition must be read on preview and view.
• 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 FIXME field=value in URL

Changes from category system

Main changes from category system:

• Name changed in the hope that form is more readily understandable than category
• 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

Also see FormTemplateSystemInitialDiscussion

Questions

• [ JohnTalintyre ] - do we allow form templates to be shared between Webs. I think for consistency we should.
  • [ PeterThoeny ] - Makes sense. Needs to be coded accordingly, in a similar way like %INCLUDE% does, i.e. by adding the web name to the topic name in case it is not the current web.

• [ JohnTalintyre ] - if a topic is moved to a Web (with different form templates) what do we do? We could refer back to the old definition when viewing, on edit could give choice to change to another form template.
  • [ PeterThoeny ] - For simplicity I suggest to keep the current form, e.g. the form points back to the original form template.

• [ JohnTalintyre ] - the above specifies tooltips. These won't appear when viewing the topic as normal rendering will just see these a WikiNames. Does this matter? It does raise the more general issue of tooltip for topics, a topic could store a tooltip within it, possibly as meta data, but cost would be moderatly high for reading it out when refering from another topic.
  • [ PeterThoeny ] - I was thinking of showing the tooltips just in edit for the links opening up the popup help windows.

Creating new topics with forms

When you create a new topic in a web that has the WEBFORMS preferences variable set you will get a Add Form button at the bottom of the page. However, if the WebTopicEditTemplate topic has had a form added this will appear with values set; Change in the form can be pressed to remove the template or switch to a different one.

A form embedded in a topic can also cause a form to be present in a new topic, this is done by specifying the formtemplate parameter in the URL.

Topic meta data

See MetaDataDefinition.

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.

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 WEBFORMS. If it's not present, using edit gives an oops dialog.

Questions

• Do we need script to upgrade all topics (running would be optional)?
  • [ PeterThoeny ] - I don't think this is needed, but could be offered for convenience.

Future

Please see FormTemplateFutureIdeas.

Notes

Form definition is not ready on topic view ...