Tags:
forms1Add my vote for this tag structured_wiki2Add my vote for this tag twiki_application1Add my vote for this tag create new tag
, view all tags
ALERT! NOTE: This is a DistributionDocument. Please help maintain high quality documentation: This is a wiki, please fix the documentation if you find errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below. Use the Support web for problems you are having using TWiki.

TWiki Forms - Foundation of TWiki Applications

Add structure to content with forms attached to twiki topics. TWiki forms (with form fields) and formatted search are the base for building database applications.

Overview

By adding form-based input to free form 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 TWiki forms:

  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

TIP Tip: The blog How to Create a TWiki Application on TWiki.org is a good tutorial to get started with TWiki forms based applications.

Defining a Form

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.

  1. Create a new topic with your form name: YourForm, ExpenseReportForm, InfoCategoryForm, RecordReviewForm, whatever you need.
    Tip, idea The name of a Form Template topic must end in Form.
  2. 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).
  3. For each field, fill in a new line; for the type of field, select from the list.
  4. Save the topic

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 TWiki variables. 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.

Adding a Form to a Topic

  • To add a Form, follow the "More topic actions" link at the bottom of a topic, select "Add or Replace Form".
    • Select a Form Template topic. These are topics with names ending in Form that contain a Form Template table.
    • A Form is typically added to a template topic, either to the WebTopicEditTemplate topic in a web, or a new topic that serves as an application specific template topic.
    • Modify the template topic to set the initial Form values.

  • 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:
    • other than checkboxes: name, ex: ?BugPriority=1
    • checkbox: namevalue=1, ex: ?ColorRed=1.
      Boxes with a tick must be specified.
    • 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" class="twikiSubmit" value="Create" />
          </form>
             
  • Note: You can create a topic in one step, without going through the edit screen. To do that, specify the save script instead of the edit script in the form action. When you specify the save script you have to use the "post" method. Example:
        <form name="newtopic" action="%SCRIPTURLPATH{"save"}%/%WEB%/" method="post">
           .....
        </form>
           
  • The edit and save scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.

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

Changing a Form

  • To change a Form, follow the "More topic actions" link at the bottom of a topic, select "Add or Replace Form", and select a new 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 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, 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 row of the table defines one element of an input field:

Name Type Size Values Tooltip message Attributes

The Name, Type and Size columns are required. Other columns are optional. The form template must have a header row, e.g. at least | *Name* | *Type* | *Size* | is required. Columns:

  • Name column: Name is the name of the form field.

  • Type, Size, Value columns: Type, Size and Value describe the type, size and initial value of this form field. Type text, checkbox, select and more are described in the Form Field Types section below.

  • Tooltip message column: The Tooltip message will be displayed when the cursor is hovered over the field in edit view.

  • Attributes column: Attributes may contain additional key="value" form field attributes, separated by space.
    • A hidden="1" attribute indicates that this field is hidden, e.g. not shown in view mode. However, the field is available for editing and storing information. The deprecated H attribute has the same function, it is still supported but might be removed in a future TWiki release.
      TIP Tip: The TWiki form header is suppressed in view mode if all fields of the form are hidden. For better usability it is good to hide the whole form if the display and interaction of all form fields is done externally. For example, the display and modification of form field values can be done in a header topic that is included in each page.
    • An mandatory="1" attribute 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. The deprecated M attribute has the same function, it is still supported but might be removed in a future TWiki release.
    • Additional form field type specific attributes can be used, such as onfocus="..." and spellcheck="..".

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

Field Value Notes:

  • 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 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 TWiki variables from being expanded.
    • The FormatTokens can be used to prevent expansion of other characters.

General Notes:

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

Form Field Types

Each table row of a form template defines one element of an input field:

Name Type Size Values Tooltip message Attributes

Many types of form fields are available. Some are TWiki internal, some are provided by extensions. Find more TWiki form field extensions on TWiki.org. The Size, Value and Attributes depend on the Type used. Form field types:

Type Description Size Value
text One-line text field Text box width in number of characters Initial (default) content
textarea Multi-line text box Columns x rows, such as 80x6; default is 40x5 Initial (default) content
label Read-only text label   Text of the label
checkbox One or more checkboxes that can be toggled individually Number of checkboxes shown per line Comma-space-separated list of item labels - can be a dynamic SEARCH
checkbox+buttons Like checkbox, adding [Set] and [Clear] buttons
radio Radio buttons, mutually exclusive; only one can be selected Number of radio buttons shown per line Comma-space-separated list of item labels - can be a dynamic SEARCH
combobox screenshot-combobox Text field & select combination box, rendered as a text input field and a button to open up a selector box Text box width in number of characters Comma-space-separated list of options of the select box - can be a dynamic SEARCH
select Select box, rendered as a picklist or a multi-row selector box depending on the size value 1: Show a picklist
• Number > 1: Multi-row selector box of specified size
• Range e.g. 3..10: Multi-row selector box with variable size - the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options
Comma-space-separated list of options of the select box - can be a dynamic SEARCH
select+multi Like select, turning multi-select on, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items
select+values Like select, allowing definition of values that are different to the displayed text. An option is defined as value: title, where the value is the value passed on form submit, and title is the option text shown to the user. For example:
| Field 9 | select+values | 3 | One, 2: Two, III: Three | Various values formats |
shows
but the values of options Two and Three are 2 and III, respectively. A legacy title=value syntax is supported as well, for example: One, Two=2, Three=III.
select+multi+values Combination of select+multi and select+values
color screenshot-small Single-line text box and a color picker to pick a color. The color can also be typed into the text box, such as #123456. See details. Text box width in number of characters Initial (default) color
date screenshot-small Text input field and a button next to it to pick a date from a pop-up calendar. The date can also be typed into the text box. See details. Text box width in number of characters Initial (default) date
percent screenshot-small Percent complete indicator and pick list. The percentage can be set by clicking on the percent complete indicator bar, or by picking a value from the pick list. See details. N/A Initial (default) percentage value

Note on Attributes:

  • Common attributes: hidden, mandatory, class, form, onblur, onfocus, onchange, onselect, onmouseover, onmouseout, spellcheck, style, tabindex, title, translate
  • Type-specific attributes:
    • text type: id, max, maxlength, min, pattern, placeholder
    • textarea type: autocomplete, id, maxlength, minlength, pattern, placeholder, wrap
    • label type: id, max, maxlength, min
    • combobox type: max, maxlength, min, pattern, placeholder

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 TWiki 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:

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

Using a form template on a different web

You can use a form template on a different web by specifying a form template in the WEB.TOPIC format.

In addition, you can put a comma separated list of webs in the TWIKIFORMPATH variable. It's referred to only when a form template is spcified without a web (TOPIC instead of WEB.TOPIC). The webs in TWIKIFORMPATH are examined in the listed order until the specified template is found.

TWIKIFORMPATH may contain TWiki variables. For example:

   * Set TWIKIFORMPATH = %APPLICATION_WEB%, %WEB%

If TWIKIFORMPATH is defined, the current web is examined only if all the webs listed in it don't have the form template.

Extending the range of form data types

You can extend the range of data types accepted by forms by using TWikiPlugins. All such extended data types are single-valued (can only have one value) with the following exceptions:

  • any type name starting with checkbox
  • any type name with +multi anywhere in the name
Types with names like this can both take multiple values.

Hints and Tips

Editing Just Form Data, Without Topic Text

In some cases you want to change only the form data. You have the option of hiding the topic text with two methods:

  • To display only the form whenever you edit a topic, set the preference variable EDITACTION to value form (see details).
  • To change the edit action in a URL, add a action=form parameter to the edit URL string, such as
    %SCRIPTURL{edit}%/%BASEWEB%/%BASETOPIC%?t=%SERVERTIME{$epoch}%;action=form (see details).

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.

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.

Update Specific Form Fields

All the form fields are shown and can be updated when editing a topic that has a form. It is possible to have more control over the layout of a form, or update just a subset of the form fields by using a custom HTML form. For example, in a bug tracker, each topic would include a header topic that shows a form with some fields to update specific form fields of the bug item. Use the EDITFORMFIELD variable to easily create this form in the header topic. Example:

%EDITFORMFIELD{ "form" type="start" action="save" topic="%BASETOPIC%" }%
| Priority: | %EDITFORMFIELD{ "Priority" topic="%BASETOPIC%" }% |
| Status:   | %EDITFORMFIELD{ "Status"   topic="%BASETOPIC%" }% |
|  | %EDITFORMFIELD{ "form" type="submit" value="Update" }% |
%EDITFORMFIELD{ "LastUpdate" type="hidden" value="%SERVERTIME{$year-$mo-$day}%" }%
%EDITFORMFIELD{ "form" type="end" }%

Assuming the base topic has a BugForm with Priority and Status fields of type select, a LastUpdate field of type text, and some other fields. Above form shows a table with selectors for Priority and Status, and an Update button. On form submit, the Priority, Status and LastUpdate fields are updated in the base topic.

Searching for Form Data

TWiki Forms accept user-input data, stored as TWikiMetaData. Meta data also contains program-generated info about changes, attachments, etc. To find, format and display form and other meta data, see TWikiMetaData, EDITFORMFIELD, FORMFIELD, SEARCH and METASEARCH variables in TWikiVariables, and TWiki Formatted Search.

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{"%USERSWEB%.UserName" scope="text" nosearch="on" nototal="on" sort="modified" reverse="on"
format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%

Searching forms this way is obviously pretty inefficient, but it's easy to do. If you want better performance, take a look at some of the structured wiki extensions that support higher performance searching e.g. TWiki:Plugins.DBCachePlugin.

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.

Related Topics: TWikiTemplates, TWikiScripts, VarSEARCH, FormattedSearch, UserDocumentationCategory



Comments & Questions about this Distribution Document Topic

PeterMasiar: It is possible to have two form templates for one topic? From user's point of view it makes sense to have part of parameters for a topic set on top of the page, then there are free-field areas (stuctured by a WebTopicEditTemplate, then another sets of parameters from another form. If not possible - can I have single form on the top of page? My free form text might be rather long and it is a pain to scroll down to form so see what is going on...

-- PeterMasiar - xx Dec 2001

  • Peter, You can move around anything you see in templates - TWikiTemplates is OK for info, but could use more examples - and that's a bit in the future.
  • [ See Using Form Data above - added following this question. ]
  • You can't normally have two separate forms per topic. For possible hacks, or to request a feature enhancement, you should post that question in the Codev web.
  • For Template help, if you need it, go to the Support web.

-- MikeMannix - 01 Jan 2002

Thank you, Mike, for your answer. I asked my question in Codev TwoFormsPerTopic as you suggested.

When fighting with forms, I found out that when Defining a Form with Multiple Topics, field Values in WebFormTemplate from example needs to be space to enable TWiki magic work (to let Twiki feed options in SELECT from table in related topic). If it is as in example, the only option is string "...". [ Correction and additional info added to docs. ]

-- PeterMasiar 03 Jan 2002

Peter: Excellent - good find! I've updated the docs.

Whenever you have anything else, including interesting applications of straight features - stuff that wouldn't really fit in Codev - it's welcome on the appropriate feature page here, for inclusion directly, or in a future misc. tips/cookbook-type appendix...

-- MikeMannix - 05 Jan 2002

Even better, more general and flexible solution than TwoFormsPerTopic was proposed by AdrianLynch (15 Jan 2002) in VariableForCategoryDropdown: extended format for META.

-- PeterMasiar - 16 Jan 2002

Peter: Yep. You'll probably find the gaming site Adrian & crew are cloning from LotusNotes to TWiki pretty cool, unusual TWiki-ing. Links on AlternativeTWikiTargets.

-- MikeMannix - 23 Jan 2002

Re: Form inclusion I find the TWikiDrawPlugin very easy and natural for a user. Could the same type of tag for example be used instead of writing the table data by hand? This could pave the way to a more flexible interface by using tiny little plugins for specific tasks. These tasks and the data captured in the task could be saved and shared via xml for later processing on the client or on the server.

-- DennisDaniels - 18 Mar 2002

Support.FormsConfusion clears some confusing points. I found especially AndrewSteele's notes from 07 Sep 2002 usefull.

-- PeterMasiar - 09 Sep 2002

Suggested addition under Multiple Topics section, with supplementary info from those who understand this better? smile

Advantages to Using Multiple Topics

  • You can provide more complete descriptions for each value.
  • The field values table can be included in another topic, making it easier to search for all topics that have a paraticular field value assigned???
  • Other reasons???

-- StewStryker - 11 Jul 2002

I had thought that I might be able to use % SEARCH % syntax to build option lists for a select form element, either using a single topic form definition or a multiple topic form definition. No go in either case. In the case of a single topic form defintion, I just put the search (which put ','s between the the search items) direction between the pipes surrounding the form element. That won't even show up as a valid part of the table, although there's no obvious reason why it wouldn't from the result. Likewise, if you build a page that contains a SEARCH that builds an option table, the table isn't valid to use as an option list for a form. I'm assuming that it is a problem with the order in which the variables are expanded. I'm not sure if this should be a bug report, a feature request, or just a "gee whiz" note for those of us trying to stretch the system beyond its limits.

-- BobbyMartin - 30 Oct 2002

added UsingFormsForSettings section

-- MattWilkie - 27 Jul 2004

Any reason to not rename this TWikiForm?

-- MartinCleaver - 02 Jan 2005

Umph, thousands of pointers to this topic (CoolURIsDontChange.)

-- PeterThoeny - 03 Jan 2005

Added example at Using Form Data.

thousands of pointers to this topic - ah, but that is foreseen in the core code. Singular and plural may be interchanged. So the link TWikiForms will lead to TWikiForm as well. There is no technical reason to not rename the topic.

But this topic is dealing with "forms on TWiki pages". It is not about the one possible form - although only one form is permitted, the form itself may be different for each topic. Let's say an economic report is titled "Households in France". There may be a separate chapter Households, and it would be strange to call it Household. Classifications also use plural: Animals > Herbivores, etc.

-- ArthurClemens - 19 Mar 2005

Only plural links that are internal (in this wiki) will be redirected. External links wouldn't.

I should get round to filing a bug(s) based on Sandbox.SingularPluralLinkBugs

-- SamHasler - 20 Mar 2005

Contributed How-tos

Thank you for contributing these how-tos. For now they best fit in the comment section, once edited we can find a new place for them.

-- PeterThoeny - 01 Apr 2005, MartinCleaver - 05 Apr 2005.

A Forms How-To, originally by AndrewSteele

    1. Some terminology translations:
      • A form is to a web as a table is to a database
      • You put your "create table" into a WebForm called whatever you like. It also doesn't need to be in the "Know" web, it can be in your own web.
    2. Determine what data you want to collect.
      This what you want to get stored in the META data of Topics you create.
    3. Create a Topic to put form data in. Follow the instructions on TWiki.TWikiForms#Defining_a_Form_Template to create your form table. The values field is normally blank. (I'm writing this in the context of my comments above about the single topic option being a shortcut). For list elements, make each field in the name column a WikiWord to a Topic containing a table that lists the possible values for that field.
    4. Determine the values For fields types of your form that use a list: select, checkbox, radio. The list of possibilities goes on another page (this is what is meant by the "Multiple Topics" option).
    5. Create a Topic for each list field with a table of all possible options. These tables have three columns, the middle one is always "option".
    6. Once you have create your Webform Topic with it's table defining the Webform, and all your Topics, each with a Table for your list elements, you are ready to connect it into your web.
    7. Edit the WebPreferences page and add your web form topic name to the line that has "Set WEBFORMS =". This enables your web form so Twiki knows it exists. Everytime you now edit a topic you will have an "Add Form" on at the bottom of your page.
    8. Edit or create the "WebTopicEditTemplate". This topic is what you get as the default when you create a topic. By adding the form to this topic it will come up on each new topic you create.

-- ErezZukerman - 01 Apr 2005

Another How-To, by TorbenGB

It is most convenient to follow these basic steps when creating a new template. First of all, a form must be made. Once a form exists, it can be used by any page in the same web.

Creating a form

  1. Enable the form: Add a new (not existing) WikiWord to the WEBFORMS setting in WebPreferences. This new page will contain the form template that you will create in the next step.
  2. Create the form: Click the ? and create this new page. It must contain only one table, but you can also add some descriptive text above and below it if you like.
    1. The table must contain exactly these headers: | Name | Type | Size | Values | Tooltip | and you may never rename these headers. If they are changed, then all pages that use this form will no longer be editable! (There is a fix for this.)
  3. Create categories and values: Add one row to the table for each aspect that you want to classify, e.g. one row for document status, one for owner, etc.
    1. Name can be any word to describe the classification aspect you want to add. If you write the values as WikiWords, then the classification aspect can easily be described in detail.
      • Example: ManagerApproval
    2. Type can be select, checkbox, radio, or text. This defines how a user can specify the value for this classification aspect.
      • For select and radio, only one value can be selected.
      • For checkbox, it is valid to select zero, one, several, or all values at the same time.
      • For text, any plain-text content is valid.
    3. Size
      • For select, this means how many lines will be visible. Size=1 will display a drop-down menu, and size=2 or more will display a list. Only one value can be selected.
      • For radio or checkbox, this means how many columns will be used to display the values.
      • For text, this is a little unclear. I will add more detail when I learn it.
    4. Values should be a commas-eparated list of possible values. The first value in the list will be the default value. If you write the values as WikiWords, then the values can easily be described in detail.
    5. Tooltip should contain a short sentence that explains to the user, what value to choose.
      • Example: Has a manager approved the information on this page?
  4. Save the page with the form.
  5. Set form defaults: Optional: If the form should be present on all new pages, then add the form to the WebTopicEditTemplate.
    1. Edit the WebTopicEditTemplate and click on Add form
    2. Select the form you just made.
    3. Optional: If you want certain values to be selected as default, then you can select them now. This will be the default values for forms in all new pages.
    4. Save the topic.
  • In case you want the form to be present on only a selected group of new topics within a specific web, this is what you should do instead:
    • follow the steps given above, but instead of (or additionaly to) creating the WebTopicEditTemplate within this web, you simply create a different template (something like PersonalEditTemplate). This enables you to use YourNewForm only in those topics that are based on this personal template.
    • to make sure, this PersonalEditTemplate actually uses YourNewForm, you will have to edit the template and click on Add form, and continue as described above.
    • of course, you would have to add the PersonalEditTemplate to the WEBFORMS variable in the web's WebPreferences.
      -- JuditMays - 05 Apr 2005

Now the form is ready to use.

Example

This is what a small form could look like:

Name Type Size Values Tooltip
CategoryOne select 1 DefaultValue, OtherValue1, OtherValue2 Please choose a suitable value.
CategoryTwo radio 3 DefaultChoice, OtherChoice1, OtherChoice2 Please click the relevant choice.

Explanation: The first category is shown as a drop-down menu ( type=select ). The second category is a number of radio buttons, arranged in 3 columns ( size=3 ). The first value in each category is selected by default in new pages, until a user changes it.

All category names and values have been written as WikiWords. This way, they can be easily described by creating their respective pages and adding a useful detailed description there.

  • Pages that describe a category should list all the values in that category, plus a one-sentence description of each category. This is a good overview.
  • Pages that describe a value should include a detailed description of that category, plus an embedded search that lists all the pages that have this value.

Modifying a form

It is important that the table headers | Name | Type | Size | Values | Tooltip | are never changed! If they are changed, then all pages that use this form will no longer be editable! (There is a fix for this.)

You can change all other rows of the table. If you want new aspects to be categorized, add a new row and write the name of the aspect (e.g. ImportanceForBusiness) and add suitable values as well (e.g. ImportanceNormal, ImportanceCritical). When you save the page, the new options are available when you edit and create pages.

Using a form

This requires that there is already a form created.

  • New pages: If you did the optional step Set form defaults above, then new pages automatically have the default form built-in. If you did not perform that step, new pages are handled like existing pages, see below.
    1. Before you save the new page, select appropriate values from the choices in the form. If you are in doubt what to choose, click the Name label and a description will appear in a popup window.
  • Existing pages: Existing pages do not have the new form visible, but this is how to add it:
    1. Edit the page.
    2. Click the button Add form which is located below the big text box on the right side.
    3. Choose the form that you want to use. There should only be one form available. Click the button to add the form to the page.
    4. Select appropriate values from the choices in the form. If you are in doubt what to choose, click the Name label and a description will appear in a popup window.
    5. Save the page.

The form is now attached to this page. Repeat for other pages.

-- TorbenGB - 14 Mar 2003

An important tip that I've learned the hard way (see MetaDataBreaksWithNewTopic for more info and resolution): "Forms work only in the current web, e.g. you can't reference forms defined in another web."

If you try to reference a form in another web, any attempt to create a new topic will break and you will get the "oopsnoformdef" message.

-- AmandaSmith - 15 Feb 2006

Doco misses the +multi option. Albeit the code needs to be fixed also, which I did, and submitted to develop branch....

-- ThomasWeigert - 06 Aug 2006

I want to use the BasicForm to handle Categories. I created the BasicForm Site, in which I add all possible Categories with a SEARCH. As I dont want to have the Names shown as "SemesterEinsCategory" I made a short StringCut with the SpreadSheetPlugin so I now have [[SemesterEinsCategory][ SemesterEins ]]. The only problem is that when I edit a page which contains this Form it shows as [[SemesterEinsCategory][ SemesterEins ]] and not as SemesterEins, which I want the User to see. Is there a way to force it to be shown as clickable WikiWord ??

-- MarkusBajones - 11 Aug 2006

Please ask support questions in the Support web; this section is about the documentation of TWiki forms.

-- PeterThoeny - 16 Aug 2006

Unfortunately this document for "Twiki Forms" is a bit bloated and very difficult to understand. (Of course, it's not so easy to describe this kind of behaviour as there is a form template, and instances that use the the template-that is, the actual forms. And furthermore, these "Meta data variables"...which might not be so important to be mentioned to users of the plug-in anyway.)

The "template"-word might be a bit difficult to understand (for the average user....). And to me, the "form template" seems more like a "form definition", which can be reused by the other Wiki topics. If it was a template, it would be altered somehow when taken into use(or "instantiated"), but now it is not.

-- KariNiemi - 03 Feb 2007

I updated this topic with the latest version of TWiki04x01.TWikiForms.

-- PeterThoeny - 24 Mar 2007

What are the different "Attributes" that can be added to the form table? Would be helpful if that is added to this page .

-- RyanLi - 20 Apr 2007

How list users in select of a form

-- AndreMatos - 20 Apr 2007

Please ask support questions in the Support web.

-- PeterThoeny - 20 Apr 2007

I create a page bound to a form "T1Form" then later on I want to change this page to bound to another form "T2Form". How do I change it?

-- TimMac - 26 Oct 2007

That is documented in TWikiForms#Changing_a_form (please ask support questions in the Support web.)

-- PeterThoeny - 27 Oct 2007

How can we create a template with empty values for 'Mandatory' fields? So, If my form has a field "Name" and its attributes is set to 'M' (for Mandatory). Then when I create the template, I will NOT be able to save the template unless I put in a value for this field (which will act as a default value). I donot want to do this, Is there anyway to achieve that?

-- SreekanthNemani - 01 Nov 2007

I also have another question - Can two form fields be placed one beside the other on the same row? This is of importance if you want to create "Date" and "Time". "Time" itself has "hours" and "minutes". It is extremely unworkable I believe to have Date, Hour and Min on three seperate rows.

Any help would be highly appreciated. Thank you.

-- SreekanthNemani - 01 Nov 2007

The mandatory field in template topics is a known issue, Bugs:Item4261.

The second question is a support/dev question, better asked in the Support web. Not possible within form in edit mode, but you could create a custom CommentPlugin template to manipulate form values (as done for Support topics.)

-- PeterThoeny - 02 Nov 2007

I expected this topic to go into detail about each of the five steps listed under "Typical steps to build an application based on TWiki forms". It does a good job on the first three steps, but it's weak on the last two. For instance, I can think of three ways to support the creation of new topics with form data: (1) ask for minimal data up front (perhaps just the topic name) and let the user fill in all the form data on the edit page; (2) ask for all the form data via an HTML form and pass the fields to the edit script; (3) ask for all the form data in an HTML form and pass the fields directly to the save script (does this work?). It would be nice to see some discussion of the alternatives, and perhaps an example. Concerning searches, it's natural to want to search on multiple criteria, involving multiple form fields. I presume this requires nested SEARCH and/or METASEARCH; again an example would be welcome.

-- MillerMaley - 20 Jan 2008

Under "Structure of a Form Template" it says:

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

Does this requirement extend to topics used to store value lists for fields in the form definition?

-- GarySprague - 01 May 2008

Yes, it does.

The view access restriction usually does not matter if you lock down a whole web for view; people who have access to the web can edit topics with forms.

-- PeterThoeny - 01 May 2008

I think I just answered this in the affirmative through some testing with my forms. Perhaps this should be added to the section I quoted above? Also wondering if it makes sense to break out "Form Permissions" into a separate section of this topic. I don't find it particularly intuitive to locate that information as a General Note under Structure of a Form, but maybe that's just me.

-- GarySprague - 01 May 2008

"The view access restriction usually does not matter if you lock down a whole web for view"

In my case, I've set up some "master value lists" in the Main web that are then used by various form definitions in other webs. I was thinking of hiding the Main web from users, which may simply be a bad or unnecessary step, but that is how I came across the issue.

-- GarySprague - 01 May 2008

I noticed that having values that include commas - e.g. "Manager, Operations" - for a select type form field causes the values to be lost when going from View to Edit mode. I don't know if this issue extends to other form field types or not, but I think it would be worth adding a warning to this topic if this is a confirmed issue for TWikiForms in general. The problem makes sense to me given that the options available in the select menu are probably separated by commas in the HTML, such that having a value with a comma causes TWiki to try and look for it as two different values within the select list, e.g. a first value of "Manager", and a second value of "Operations".

-- GarySprague - 16 May 2008

I am not sure if this qualifies as a bug or a obscure feature/limitation. Let's see what other developers have to say.

-- PeterThoeny - 17 May 2008

The support request regarding whether to use forms for restricting formatting on content has been moved to UsingFormsForRestrictedFormatting. Comments in the TWiki web are intended for feedback on documentation.

-- LynnwoodBrown - 02 Jun 2008

Under "Structure of a Form Template" above it says:

Field Value Notes:

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

I've noticed that if I have a radio field, the first item in the list is NOT set as the initial default value when I add that form to a topic. Is this a bug or simply a typo in the documentation?

-- GarySprague - 08 Aug 2008

Oops, just realized my last comment was user error. So the default value for radio buttons works as long as you set the size to 1. Same goes for select lists. If the size is larger than 1, it won't set the first value as the default. I'll add a clarification to this effect in the relevant section above.

-- GarySprague - 08 Aug 2008

Hmmm...After further testing, I'm not convinced that radio fields follow the "first in the value list will be the default value" behavior. I just created a whole bunch of forms with radio fields with two values and a size of 1, and they all initialize with no value selected when I add them to a topic.

-- GarySprague - 14 Aug 2008

Hi everyone. I'm a new Twiki user and I'm triying to create a form as Twiki registration but I don't find any good example. Do you know any link?

-- JustiGlobalngo - 14 Sep 2008

Any solution to the comment made by GarySprague on 01 May 2008 ? Is it possible to change anywhere in the code the "," separator into the ";"?

-- RossellaPastorelli - 2009-11-03

Thanks ScottGutman for adding the how to edit form data only section. I did some more editing and put it into SVN trunk and 5.0 branch for next release.

-- PeterThoeny - 2010-12-03

Any expert know if there a way to create a dropdown menu with values to select without using edittable plugin? When one of the value is selected by the user, is there a way to capture that value and subsequently use it in a %search%?

-- Jay Timber - 2013-08-06

Jay, please ask support questions in the Support web.

-- Peter Thoeny - 2013-08-07

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r94 < r93 < r92 < r91 < r90 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r94 - 2014-12-16 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.