Data Forms

Data forms allow you to add structured data to topics. The data stored in the form fields can be used to search and filter topics. The combination of structured data and search queries are the base for building database applications.

Overview

By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. A form is enabled for a web and can be added to a topic. The form data is shown in tabular format when the topic is viewed, and can be changed in edit mode using edit fields, radio buttons, check boxes and list boxes. Many different form types can be defined in a web, though a topic can only have one form attached to it at a time.

Typical steps to build an application based on Foswiki forms:

  1. Define a form definition
  2. Enable the form for a web
  3. Build an HTML form to create new topics based on that template topic
  4. Build a FormattedSearch to list topics that share the same form

For a step by step tutorial, see AnApplicationWithWikiForm.

Defining a form

A form definition specifies the fields in a form. A form definition is simply a page containing a Foswiki table, where each row of the table specifies one form field.
  1. Create a new topic with your form name: YourForm, ExpenseReportForm, InfoCategoryForm, RecordReviewForm, whatever you need.
  2. Create a TML table, with each column representing one element of an entry field: Name, Type, Size, Values, Tooltip message, and Attributes (see sample below).
  3. For each field, fill in a new line; for the type of field, select from the list.
  4. Save the topic (you can later choose to enable/disable individual forms).

Example:
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| TopicClassification | select | 1 | NoDisclosure, PublicSupported, PublicFAQ | blah blah... |   |
| OperatingSystem | checkbox | 3 | OsHPUX, OsLinux, OsSolaris, OsWin | blah blah... |   |
| OsVersion | text | 16 | | blah blah... |   |

Name Type Size Values Tooltip message Attributes
TopicClassification select 1 NoDisclosure, PublicSupported, PublicFAQ blah blah...  
OperatingSystem checkbox 3 OsHPUX, OsLinux, OsSolaris, OsWin blah blah...  
OsVersion text 16   blah blah...  

See structure of a form for full details of what types are available and what all the columns mean.

You can also retrieve possible values for select, checkbox or radio types from other topics:

Example:

  • In the WebForm topic, define the form:
    Name Type Size Values Tooltip message Attributes
    TopicClassification select 1   blah blah...  
    OperatingSystem checkbox 3   blah blah...  
    OsVersion text 16   blah blah...  

    ALERT! Leave the Values field blank.

  • Then in the TopicClassification topic, define the possible values:
    | *Name*            |
    | NoDisclosure      |
    | Public Supported  |
    | Public FAQ        |
    Name
    NoDisclosure
    Public Supported
    Public FAQ

Field values can also be set using the result of expanding other macros. For example,

%SEARCH{"Office$" scope="topic" web="%USERSWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%

When used in the value field of the form definition, this will find all topic names in the Main web which end in "Office" and use them as the legal field values.

Enabling forms by Web

Forms have to be enabled for each individual web. The WEBFORMS setting in WebPreferences is optional and defines a list of possible form definitions.

Example:
  • Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm

Adding a form to a topic

Changing a form

Structure of a form definition

A form definition specifies the fields in a form. A form definition is simply a TML table contained in a topic, where each row of the table specifies one form field.

Each column of the table is one element of an entry field: Name, Type, Size, Values, Tooltip message, and Attributes.

The Name, Type and Size columns are required. Other columns are optional. The form must have a header row (e.g. | *Name* | *Type* | *Size* |).

Name is the name of the form field.

The Type, Size and Value fields describe the legal values for this field, and how to display them.

Tooltip message is a message that will be displayed when the cursor is hovered over the field in edit view.

Attributes specifies special attributes for the field. Multiple attributes can be entered, separated by spaces.

For example, a simple form just supporting entry of a name and a date would look as follows:

| *Name* | *Type* | *Size* |
| Name   | text   | 80     |
| Date   | date   | 30     |
Field Name Notes: Field Value Notes: General Notes:

Values in other topics

As described above, you can also retrieve possible values for select, checkbox or radio types from other topics. For example, if you have a rows defined like this:
| *Name*                 | *Type* | *Size* |
| AeroplaneManufacturers | select |        |
the Foswiki will look for the topic AeroplaneManufacturers to get the possible values for the select.

The AeroplaneManufacturers topic must contain a table, where each row of the table describes a possible value. The table only requires one column, Name. Other columns may be present, but are ignored.

For example:

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

Notes:

Extending the range of form data types

You can extend the range of data types accepted by forms by using Plugins. All such extended data types are single-valued (can only have one value) with the following exceptions: Types with names like this can both take multiple values.

Hints and tips

Build an HTML form to create new form-based topics

A form definition specifies the fields in a form. A form definition is simply a page containing a Foswiki table, where each row of the table specifies one form field.

Searching in form data

The best way to search in form data is using the structured query language in the SEARCH macro. See QuerySearch for more information.

Gotcha!


Related Topics: UserDocumentationCategory, TemplateTopics, AnApplicationWithWikiForm spacer