Difference: TWikiForms (28 vs. 29)

Revision 292013-03-31 - TWikiContributor

Line: 1 to 1
 

TWiki Forms - Foundation of TWiki Applications

Line: 25 to 25
 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.
Added:
>
>

Tip, idea The name of a Form Template topic must end in 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).
  2. For each field, fill in a new line; for the type of field, select from the list.
Changed:
<
<
  1. Save the topic (you can later choose to enable/disable individual forms).
>
>
  1. Save the topic
 
Example:
Line: 79 to 80
 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.

Changed:
<
<

Enabling Forms by Web

>
>

Adding a Form to a Topic

 
Changed:
<
<
Forms have to be enabled for each individual web. The WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates.
Example:
  • Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm
  • 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.
  • 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.
>
>
  • 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
Line: 105 to 100
 
Changed:
<
<
  • ALERT! 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:
>
>
  • 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>
       
Changed:
<
<
>
>
 
Changed:
<
<
>
>
 
Changed:
<
<
  • ALERT! Note: Initial values will not be set in the form of a new topic if you only use the formtemplate parameter.
>
>
  • Note: Initial values will not be set in the form of a new topic if you only use the formtemplate parameter.
 
Changed:
<
<

Changing a form

>
>

Changing a Form

 
Changed:
<
<
  • 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.
>
>
  • 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.
 
Changed:
<
<
  • 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.
>
>
  • 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.
Line: 200 to 196
 
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
Added:
>
>
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. For example:
| Field 9 | select+values | 3 | One, Two=2, Three=III | Various values formats |
shows
but the values of options Two and Three are 2 and III, respectively.
Line: 228 to 225
 Notes:
  • The Values column must be empty in the referring form definition.

Added:
>
>

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:

Line: 244 to 256
 
  • 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).
Added:
>
>
 

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.

Added:
>
>

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

Changed:
<
<
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, FORMFIELD, SEARCH and METASEARCH variables in TWikiVariables, and TWiki Formatted Search.
>
>
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* |
Changed:
<
<
%SEARCH{"Main.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on"
>
>
%SEARCH{"Main.UserName" scope="text" nosearch="on" nototal="on" sort="modified" reverse="on"
 format="|$topic |$formfield(TopicClassification) |" web="Sandbox"}%
Line: 274 to 303
 

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

Added:
>
>
META FILEATTACHMENT attachment="screenshot-combobox.png" attr="h" comment="" date="1356580739" name="screenshot-combobox.png" path="screenshot-combobox.png" size="11949" user="TWikiContributor" version="1"
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiForms.