Data Forms

Overview

Topic data is normally not visible when you view a topic (except for a small table at the bottom of the topic - dependent on the used skin). Topic data works "behind the scenes" and facilitates searches, reports and custom displays.

Topic data, or better: structured data, can be used in many ways. The Foswiki Support questions serves as a demonstration how topic data can be used:

• To create a complete list of "Support Questions" topics
• To show a subset of all questions that have not been answered yet
• To display the title and subject of each question

Another uses for structured data could be:

• Create a list of all contributions of one particular author
• Create a quick report of all employee names and phone numbers
• Create a software documentation repository
• Create and track tasks
• Create a bug tracker

To work with topic data, you will need 3 things:

1. The data definition, specified in a table in a "data form" topic. The table lists all fields and their types - see The data definition.
2. The web's WebPreferences needs to list the form in the WEBFORMS setting - see Enabling forms.
3. The form must get connected to the topic - see Adding a form to a topic.

Optional further steps are:

1. Create a template topic so that new topics based on that template have the form already added - see Template topics.
2. Build an HTML form to create new topics based on that template topic, or to pass field values from the HTML form to the data form.
3. Build a search to create a report from the stored data

For a step by step tutorial, see the FAQ How can I create a simple data form based application?.

The data definition

The data form topic

| *Name*  | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| TopicTitle | text | 100 | | | H |
| Version | select | 1 | ,Version in SVN,Foswiki 1.1.4,Foswiki 1.1.3,Foswiki 1.1.2,Foswiki 1.1.1 | | |
| Status | select | 1 | Asked,More info required,Answered | | M |
| Related Topics | textboxlist | | | |

The name of the data form topic usually ends with "Form". For example, the form topic for the Support Questions is named "QuestionForm". The form topic can be placed in any web, but usually this is in the same web as the topics that will be using it.

The form table

The data form table is a kind of spreadsheet:

• Each row of the table specifies one form field
• The table header defines what attributes of the form fields need to be specified

Header row

| *Name*  | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |

Only Name, Type and Size are required. So the minimum table has this header row:

| *Name* | *Type* | *Size* |

A simple form just supporting entry of a name and a date would be:

| *Name* | *Type* | *Size* |
| Name   | text   | 80     |
| Date   | date   | 30     |

Form field rows

As said, only Name, Type and Size are required.

Form field attributes

Name

• Names have to be unique for each data definition.
• A very few field names are reserved. If you try to use one of these names, Foswiki will automatically append an underscore to the name when the form is used. But do not use the field name undefined (or any variant of that name, such as UnDefined), as that name is reserved for use in search queries.
• You can space out the title of the field, and it will still find the topic e.g. Aeroplane Manufacturers is equivalent to AeroplaneManufacturers.
• If a label field has no name, it will not be shown when the form is viewed, only when it is edited.
• Field names can in theory include any text, but you should stick to alphanumeric characters. If you want to use a non-wikiname for a select, checkbox or radio field, and want to get the values from another topic, you can use [[...]] double bracket links. This notation can also be used when referencing another topic to obtain field values, but a name other than the topic name is required as the name of the field.
• If you want the Field name to include embedded spaces, use the format [<nop>[FieldName][Descriptive human-friendly Field Name]].
• Leading and trailing spaces do not matter.

Type

The control appearance is also specified by size and (initial) value. More on those attributes below.

| Field 9 | select+values | 1 | One, Two=2, Three=III, Four | Various values formats |

<select name="Field9" size="1" class="foswikiSelect">
<option value="One" class="foswikiOption">One</option>
<option value="2" class="foswikiOption">Two</option>
<option value="III" class="foswikiOption">Three</option>
<option value="Four" class="foswikiOption">Four</option>
</select>

| *Name*  | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| MyColor | color | 10 | | | |

Size

Values

• The field value will be used to initialize a field when a form is created, unless specific values are given by the topic template or query parameters. The first item in the list for a select or radio type is the default item. For label, text, and textarea fields the value may also contain commas. checkbox fields cannot be initialized through the form definition.
• Leading and trailing spaces do not matter.
• Field values can also be generated through a FormattedSearch, which must yield a suitable table as the result.
• Macros in the initial values of a form definition get expanded when the form definition is loaded.
  • If you want to use a | character in the initial values field, you have to precede it with a backslash, thus: \|.
  • You can use <nop> to prevent macros from being expanded.
  • The Format tokens can be used to prevent expansion of other characters.

| *Name*  | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| AeroplaneManufacturers | select | | | | | 

| *Name* |
| Routan |
| Focke-Wulf |
| De Havilland |

| *Name*  | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| Subject | select+multi | 10 | ,%SEARCH{ \
   "Wiki" \
   scope="topic" \
   web="%SYSTEMWEB%" \
   nonoise="on" \
   type="regex" \
   format="$topic" \
   separator=", " \
}% | | |

| Subject | select+multi | 10 | ,%SEARCH{ \
   "   *\s*.*?" \
   topic="QuestionSubjectCategory" \
   type="regex" \
   multiple="on" \
   casesensitive="on" \
   nonoise="on" \
   separator="," \
   format="$pattern(.*   \*\s*([^\n]*).*)" \
}% | | |

Tooltip message

Attributes

Multiple attributes can be entered, separated by spaces:

| TopicTitle | text | 100 | | | H M |

Enabling forms

This is done by adding the form topic name to the WEBFORMS setting. The setting accepts a comma-separated list of form topics:

   * Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm, %USERSWEB%.UserForm

You have to list the available form topics explicitly. You cannot use a SEARCH to define WEBFORMS.

Adding a form to a topic

Manual operation

1. Add a form: click the "Add form" button and select one of the forms in the list.
2. Switching or removing a form: click the "Change form" button and select another one, or none, from the list.

Automatically adding a form to a new topic

Using a template topic

For example, Question topics on foswiki.org are created using QuestionTemplate:

%META:FORM{name="QuestionForm"}%
%META:FIELD{name="TopicTitle" attributes="H" title="TopicTitle" value=""}%
%META:FIELD{name="Subject" attributes="" title="Subject" value=""}%
%META:FIELD{name="Status" attributes="M" title="Status" value="Asked"}%

Using the edit template

Using url parameters

For example:

%SCRIPTURL{edit}%/%WEB%/KnowledgeTopicAUTOINC00001?formtemplate=MyForm;Subject=FAQWhatIsWikiWiki;Category=One;Category=Two;action=form

• XxxYyyAUTOINC00001: creates a new auto-numbered topic name with base "XxxYyy" - see automatically generate unique topic names
• formtemplate: specifies the form topic, like: formtemplate=MyForm
• form values: name=value, like: Subject=FAQWhatIsWikiWiki
• form values with multiple values like checkboxes: name=value1;name=value2, like: Category=One;Category=Two
• action=form: shows the topic data form and hides the topic text form

Using a web form to create a topic and pass data

The same parameters as above can be set in HTML (hidden) form fields:

<form name="newtopic" action="%SCRIPTURLPATH{"save"}%/%SANDBOXWEB%/" method="post">
<input type="hidden" name="formtemplate" value="SimpleForm" />
<input type="hidden" name="topic" value="KnowledgeTopicAUTOINC00001" />
<input type="hidden" name="Subject" value="FAQWhatIsWikiWiki" />
<input type="hidden" name="Category" value="One" />
<input type="hidden" name="Category" value="Two" />
<input type="submit" class="foswikiSubmit" value="Create topic" />
</form>

Creates:

Changing a form

• If you change the form definition, the changes will not take affect in a topic that uses that form until you edit and save it.
• If you add a new field to the form, then it will appear next time you edit a topic that uses the form.
• If you delete a field from the form, or change a field name, then the data will not be visible when you edit the topic (the changed form definition will be used). If you save the topic, the old data will be lost (though thanks to revision control, you can always see it in older versions of the topic)
• If two people edit the same topic containing a form at exactly the same time, and both change fields in the form, Foswiki will try to merge the changes so that no data is lost.

Searching in form data

As an example, the search used on Foswiki Support questions is:

%SEARCH{
   "QuestionForm.Status='Asked'"
   type="query"
   excludetopic="QuestionTemplate"
   web="%WEB%"
   format="   * [[$web.$topic][$formfield(TopicTitle)]] $formfield(Subject)"
   order="formfield(Extension)"
   nonoise="on"
}%

See SEARCH for an overview of SEARCH parameters, and Query Search for the query language specifics.