Defining a Form

1. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, Tooltip message, and Attributes (see sample below).

Example:

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

Example:

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

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

Adding a form to a topic

• Edit the topic and follow the "Add form" button to add a Form. This is typically done to a template topic, either to the WebTopicEditTemplate topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.

• If two people edit the same topic containing a form at exactly the same time, and both change fields in the form, TWiki will try to merge the changes so that no data is lost.

Structure of a Form Template

A Form Template specifies the fields in a form. A Form Template is simply a page containing a TWiki table, 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.

• Type checkbox specifies one or more checkboxes. The Size field specifies how many checkboxes will be displayed on each line. The Value field should be a comma-separated list of item labels.
  • Type checkbox+buttons will add Set and Clear buttons to the basic checkbox type.
• Type radio is like checkbox except that radio buttons are mutually exclusive; only one can be selected.
• Type label specifies read-only label text, The Value field should contian the text of the label.
• Type select specifies a select box. The Value field should contain a comma-separated list of options for the box. The Size field can specify a fixed size for the box (e.g. 1, or a range e.g. 3..10. If you specify a range, then the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options.
  • There are two modifiers that can be applied to the select type:
    • select+multi turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
    • select+values allows the definition of values that are different to the displayed text. For example:

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

      shows OneTwoThreeFour but the values or options Two and Three are 2 and III respectively.
      You can combine these modifiers e.g. select+multi+values
• Type text specifies a one-line text field. Size specifies the text box width in number of characters. Value is the initial (default) content when a new topic is created with this form template.
• Type textarea specifies a multi-line text box. The Size field should specify columns x rows, e.g. 80x6; default size is 40x5. As for text, the Value field specifies the initial text
• Type date specifies a single-line text box and a button next to it; clicking on the button will bring up a calendar from which the user can select a date. The date can also be typed into the text box. Size specifies the text box width in characters. As for text, the Value field specifies the initial text

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.

• An attribute H indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
• An attribute M indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops page. Mandatory fields are indicated by an asterisks next to the field name.

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 names have to be unique.
• A very few field names are reserved. If you try to use one of these names, TWiki will automatically append an underscore to the name when the form is used.
• 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 [[...]] 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.
• Leading and trailing spaces are not significant.

• 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 template.
• Leading and trailing spaces are not significant.
• Field values can also be generated through a FormattedSearch, which must yield a suitable table as the result.
• Variables in the initial values of a form definition get expanded when form values are initialized from the form definition. The escape words $quot ("), $percnt (%), $dollar ($), $n (newline), and $nop can be used to prevent expansion.

• The topic definition is not read when a topic is viewed.
• Form definition topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists. Note that view access is required to be able to edit topics that use the form definition, though view access to the form definition is not required to view a topic where the form has been used.

Values in Other Topics

| *Name*                 | *Type* | *Size* |
| AeroplaneManufacturers | 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:

• The Values column must be empty in the referring form definition.

Extending the range of form data types

• any type name starting with checkbox
• any type name with +multi anywhere in the name

Hints and Tips

Build an HTML form to create new Form-based topics

• New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form. Template topics has more.

Searching for Form Data

Gotcha!

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

• form template - a set of fields defining a form

• form - additional meta data (besides the freeform TEXTAREA) attached to a topic

• form field - a named item in a form (also known as a key)
• field type - selects the field type:

• field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (label, text, text area).

Defining a Form

1. Create a new topic with your form name: YourForm, ExpenseReportForm, InfoCategoryForm, RecordReviewForm, whatever you need.
2. Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, Tooltip message, and Attributes (see sample below).

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

• Then in the TopicClassification topic, define the possible values:
  

%SEARCH{"Office$" scope="topic" web="%MAINWEB%" nototal="on" nosummary="on" nosearch="on" regex="on" format="$web.$topic" separator=", " }%

when used in the value field of the form definition, will take the set of field values to be all topic names in the Main web which end in "Office".

Notes:

• A very few field names are reserved. If you try to use one of these names, TWiki will automatically append an underscore to the name when the form is used.
• 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 template.
• If a label field has no name (blank first column in the form definition) it will not be shown when the form is viewed, only when it is edited.

• Field names can 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 [[...]] 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.
• Field names have to be unique. If the same name is necessary (as when the field values for several fields are obtained from the same topic), an alternative name must be assigned using the [[...]] notation.
• The topic defining field values can also be generated through a FormattedSearch, which must yield a suitable table as the result.
• Form definition topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists. Note that view access is required to be able to edit topics that use the form definition, though view access to the form definition is not required to view a topic where the form has been used.
• The Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip in edit view.
• The Attributes column is used to define special behavior for that form field (multiple attributes can be entered, with or without separators):
  • An attribute H indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
  • An attribute M indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops page. Mandatory fields are indicated by an asterisks next to the field name.

Example:

• Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm

Add a form to a topic

• Edit a topic and follow the "Add form" button to add a Form to the topic. This is typically done to a template topic, either to the WebTopicEditTemplate topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.

• Additionally a new topic can be given a Form using the formtemplate parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values:

• • Example: This will add a textfield for the new topic name and a "Create"-Button to your topic. When the button is pressed, the topic editor will open with the form "MyForm" already attached to the new topic.

        <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/">
           <input type="hidden" name="formtemplate" value="MyForm" />
           New topic name <input type="text" name="topic" size="40" />
           <input type="submit" value="Create" />
        </form>
           

• Tip: For TWiki applications you can automatically generate unique topicnames.

• Note: Initial values will not be submitted to the form of a new topic if you only use the formtemplate parameter.

Build an HTML form to create new Form-based topics

• New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form. Template topics has more.

Changing a form

• You can change a form definition, and TWiki will try to make sure you don't lose any data from the topics that use that 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)

Searching for Form Data

Example
TWiki users often want to have an overview of topics they contributed to. With the $formfield parameter it is easy to display the value of a classification field next to the topic link:

| *Topic* | *Classification* |
%SEARCH{"%MAINWEB%.UserName" scope="text" regex="off" nosearch="on" nototal="on" order="modified" reverse="on"
format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%

Extending the range of form data types

• any type name starting with checkbox
• any type name with +multi anywhere in the name

Gotcha!

• Some browsers may strip linefeeds from text fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea.

Importing Category Table Data

Very, very old TWiki releases used a system called the "TWikiCategoryTable". Later releases support automatic import of this data.

• WebFormTemplate main definition:

• TopicClassification field value definition:

• • checkbox: namevalue=1, ex: ?ColorRed=1.
    

Using Forms For Settings

1. create WebPrefencesForm topic
2. fill it with a table like this:
   | *Name*|*Type*|*Size*|*Value*|*Tooltip message*|*Attributes*|
| WEBTOPICLIST |textarea| |     | List of topics of the %WEB% web |S|
| SITEMAPLIST  |select  |3| on, | list this web in the Site Map  |S|
| SITEMAPWHAT  |textarea| |     | short web summary             |S|
| WEBBGCOLOR   |text    |8|     | Web specific background color |S|
   etc...
3. Edit WebPreferences and:
   • Add or Change the form to WebPrefencesForm
   • add WebPrefencesForm to the Set WEBFORMS line
   • Save
4. Edit WebPreferences, jump straight down to the form ignoring all the textarea stuff, and set as you like
5. if everything works as you like it, you can delete the Set statements (the form overrides set if they are both used).

Notes:

If it isn't working, double check that the S attribute has been specified (S for Setting). If you change the form, the changes will not take affect until you edit and save the preferences' topics again.

Using the TWiki:Plugins.EditTablePlugin on WebPreferencesForm makes adding new prefedrences a breeze.

A possibly unwanted side effect for using forms for the SKINS setting in their personal user topic: because the User Preferences are final you can't have different skins for different webs as the user's setting always wins. A workaround is to simply omit SKIN in the form.

Another example, this one using EditTablePlugin, source:

%EDITTABLE{ header="|*Name*|*Type*|*Size*|*Values*|*Tooltip message*|*Attributes*|" format="|text,20|text,20|text,20|text,20|text,20|text,1|" }%

Result (after some editing):

<-- /editTable -->

Main Changes from Category Tables

The Form Template system is a more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.

Importing Category Table Data

On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable WEBFORMS. If missing, pages will display, but attempting to edit results in an error message.

The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.

NOTE: If things aren't working correctly, there may be useful entries in data/warning.txt.

Including Forms in New Topics

1. Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, and Tooltip message (see sample below).

• • A web can use one or more form templates
• form - a topic containing additional meta data (besides the freeform TEXTAREA) that categorizes the content (replaces category table)
  • Within a form-enabled web, individual topics can have a form or no form

1. Create a new topic with your form name: YourForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
2. Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (see sample below).

1. Save the topic (you can later choose to enable/disable individual forms).

• A FormTemplate topic defines the Form, ex: YourFormTemplate.
• For each field that has a value list - select, radio, checkbox - can use separate topic to define the available values.

• Know.WebFormTemplate main definition:
   

• • Topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists.
  • [[...]] links can be used to force a link (at present, the [[...][...]] format is not supported).
  • The Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip In edit.
  • The first item in the list is the default item. Alternative initial values can be set in a topic template, like WebTopicEditTemplate, with field=value, or, for checkboxes, field=1.

• With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.

• • other than checkboxes: name, ex: ?BugPriority=1
  • checkbox: namevalue=1, ex: ?ColourRed=1.
    Boxes with a tick must be specified.

• The optional WEBFORMS variable defines alternative forms that can be selected by pressing Change in edit mode.

• A topic template can use any form.

• New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form.

Form Data Storage

Using Form Data

• • [[...]] links 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) - you only see the tooltip on edit.

<-- template: messages.nat.tmpl -->

TWiki Forms

Main Changes from Category Tables

Importing Category Table Data

Defining a Form Template

A Form Template is simply a page containing your form, defined in a table where each row is one form field.

Form Template Elements

Defining a Form in One Topic

Defining a Form with Multiple Topics

• A Form Template topic defines the Form.
• Fields that have more then one value - radio, select, checkbox - can be defined in individual field value topics.

• Know.WebFormTemplate Form main definition:
   

• Know.TopicClassification field value definition:
   

• Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.

Including Forms in New Topics

When you create a new topic in a web that has the WEBFORMS Preferences variable set, an Add Form button appears at the bottom of the page. You can start all new topics with forms enabled, and pre-select a form if there's more than one available:

1. Edit the WebTopicEditTemplate topic, adding the name of an available Form.
2. Create a new topic to check - the Form should appear with values set.
   • Click Change to switch or remove Forms.

TWiki Form Templates

Changes from the Category Table System

Form Templates more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.

Main changes from TWikiCategoryTable:

Importing Existing Category Table Data

On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable =WEBFORM. If missing, pages will display, but attempting to edit results in an error message.

The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.

NOTE: If things aren't working correctly, there may be useful entries in data/warning.txt.

Example: WebFormTemplate from the TWiki.Know web

• A Form Template topic defines the form.
• Values of fields that have more then one value - radio, select, checkbox - can be defined by field value Template topics.

Code from:

• Additionally a new topic can be given a Form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values:
  • other than checkboxes: name, ex: ?BugPriority=1
  • checkbox: namevalue=1, ex: ?ColourRed=1.
    Boxes with a tick must be specified.

Form Templates

Overview

Form Template Elements

• form template - a set of fields defining a form (replaces category table definition)
  • A web can use one or more form templates.
• form - A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (replaces category table)

• form field - a named item in a form (replaces category item name)
• field type - selects the INPUT type:
  • select - drop-down menu or scrollable box
  • checkbox - one or more checkboxes
  • checkbox+buttons - one or more checkboxes, plus Set and Clear buttons
  • radio - one or more radio buttons
  • text - a one-line text field
  • textarea - a text box; size is 40x10 (columns x rows)
• field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces category item value)

Defining a Form Template

Defining a Form in One Topic

Defining a Form in Multiple Topics

Implementation Notes

• • ...? 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) - you only see the tooltip on edit.

• • 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 field=value or for checkboxes field=1.

• • The topic definition is not read when a topic is viewed.

Enabling Forms by Web

Forms are enabled on a per web basis. The WEBFORMS variable in WebPreferences is optional and defines a list of possible Form Templates. Example:

• With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.

• A default Form Template (new topics get this default form) can be provided by creating the WebTopicEditTemplate topic in a web and adding a form to it. Initial Form values can be set there.

• Addtionaly a new topic can be given a form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values. Names being:

Creating New Topics with Forms

Setting Up Multiple Form Options

• The optional WEBFORMS variable defines alternative Form Templates that can be selected by pressing Change in edit mode.

• A Template topic can use any Form Template.

• New topics with a Form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports - a SubmitVacationRequest topic and so on. These can specify the required template topic with its associated Form.

Form Template Data Storage

• 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 field=value or for checkboxes field=1

• Not checkboxes - name e.g. ?BugPriority=1
• Checkbox - namevalue=1 e.g. ?ColourRed=1. Note that all boxes with a tick must be specified.

TWikiCategoryTables Are History

• • checkbox+buttons: One or more check boxes, plus [Set] and [][Clear] buttons to set/clear all checkboxes

• • textarea: A general text area - size is rowsxcols 40x10

1. Create a new topic with your Form name: MyForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
2. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (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.

Example: Form Template

| *Name:* | *Type:* | *Size:* | *Values:* | *Tooltip message:* |
| TopClass | select | 1 | Select one..., Private, Public | must fill |
| Target   | checkbox+buttons | 3 | 1, No.2, No.3 | Select OS |
| Version | text | 16 | | OS version |

Code from:

Various Implementation Notes

Enabling Forms by Web

• The optional WEBFORMS variable defines alternative Form Templates that can be selected after pressing [Change] on the Edit page

Overview

Goodby to TWikiCategoryTables

This is a more general replacement for the TWikiCategoryTable? capability, in particular Forms are defined by special topics, where as categories were defineind using special templates.

Changes from the Category Table System

Main changes from TWikiCategoryTable: The templates for category view/edit have been dropped.and render to HTML on viewing

Migrating Existing Category Table Data

The new Form Template system should work with old Category Table data with no special conversion. Old data should be transparently upgraded to the new Meta format when a page imported from the old TWiki is edited and saved in the new system for the first time.

On upgrading, the administrator must produce a form template topic for each web that uses the old Category Tables. twikicatitems.tmpl defines the categories and is used in the conversion. The form template must be set as the first item in the WebPreferences variable =WEBFORM. If it's not present, view works, but edit results in an oops dialog result. If things aren't working correctly, there may be entries in data/warning.txt.

Form Template Elements

Defining a Form Template

Examples

Defining a Form in One Topic

Defining a Form in Multiple Topics

Specification

Enabling Forms for a Web

• Set WEBFORMS = BugForm, FeatureForm, BookLoanForm

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

Creating New Topics with Forms

Setting Up Multiple Form Options

• The optional WEBFORMS variable defines alternative Form Templates that can be selected after pressing [Change] button on the Edit page

• New topics with a form get instantiated by simple HTML forms asking for a topic name. If there is a SubmitExpenseReport topic were you can create new expense reports, a SubmitVacationRequest topic and so on. These can specify the required template topic and hence form. HUH?

Form Template Data Storage