-- PeterThoeny - 24 Jul 2002

Here is the beginning of one structure that the doc might take, but probably not the way it will be when finished. Feel free to alter, reword, add to, fill in, or delete anything. I've stolen and modified some text from an old doc to start us off. -- SueBlake - 01 Aug 2002

TWiki Forms

• what they are

By default, TWiki topics are edited as free text. A form can be added to a topic, or to all topics in a web, to give it more structure.

A form is a set of fields and values that can be stored in the metadata of a topic and are displayed as a special table when the topic is viewed. The field values can be used in searches and reports. The fields and values display in a two column table at the end of the topic to help the user to know the context of that topic. During topic edit, the values can be changed by choosing from the provided options or by typing into text fields. Several different link:[field types] are available, including checkboxes, lists, and so on.

• what they can be used for

One of the simplest uses of forms is to categorise all topics in a web. If a small form of only one field is included with each new topic, allowing a choice of category, it will be easy to pull out all topics of one category. An example of this use of a form can be seen on the Support web at TWiki.org.

Forms are also commonly used ....

You could try using forms to ... or with a ... or ...

• Working examples in distribution and on twiki.org

Using forms that are already set up

• when new topics get created with the form
• adding a form to a topic
• changing to another form when editing
• searches using forms data (intro; link to search docs)
• reports in webs where all topics have forms

How forms work

If you just want to get up and running with using forms, feel free to skip this section and continue with Creating and enabling forms. This section is for people who like to know how all the pieces fit together when forms are used.

...

Creating and enabling forms

Creating a (simple?) form

examples

Creating a (not-so-simple/othertype?) form

examples

Creating a (fancy?) form

examples

Common difficulties

If your forms do not seem to be active, first check ....

If the wrong form is used by default when new topics are created, check WebPreferences ...

If you need to make slight changes to the form over time, for example if you need to add an extra value to a drop down list, it is usually OK to change the form. Topics created before the form was edited will still work the same way, and topics created after the form was edited will have, for example, the opportunity to select the extra value, or an extra row in their form table if you added a field.

...

See also

This is a wonderful start! I'd love to see this finished off and moved over to the TWiki web for production release when it's done.

-- GrantBow - 25 Jan 2003

Wow, it's really sad that no one has enough interest in documenting things in plain English that this topic has seen no action in 5 years.

-- DavidWolfe - 09 May 2008