Data Forms

Structured data, how to set up and work with 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.

• 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

• 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

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.

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. Expand form fields into the text using the %FORMFIELD% macro - see VarFORMFIELD
4. Create a custom View Template to display your data. See SkinTemplates and AutoViewTemplatePlugin.
5. Build a search to create a report from the stored data

The data definition

The data form topic

| *Name*  | *Type* | *Size* | *Values* | *Description* | *Attributes* | *Default* |
| TopicTitle | text | 100 | | Title of the topic | 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 | Mandatory status | M | Asked |
| 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

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

1. Name
2. Type
3. Size
4. Values
5. Description
6. Attributes
7. Default

Header row

| *Name*  | *Type* | *Size* | *Values* | *Description* | *Attributes* | *Default* |

Form field rows

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 [[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* |
| MyColor | color | 10 |

Size

Values

• The field value will be used to initialize a field when a form is created (unless default column exists), 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: \|.
    • \| escaping is _only active in the Values column. It is not usable elsewhere. Use &vbar; or | in other columns.
  • You can use <nop> to prevent macros from being expanded.
  • The Format tokens can be used to prevent expansion of other characters.

Default

| *Name*  | *Type* | *Size* |
| AeroplaneManufacturers | select | |

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

| *Name*  | *Type* | *Size* | *Values* |
| 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]*).*)" \
}% | | |

Description

Attributes

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

Enabling forms

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

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

Using the edit template

Using url parameters

%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

<form name="newtopic" action="%SCRIPTURLPATH{"save"}%/Sandbox/" 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>

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

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