You are here: CFCL Wiki>Help Web>WikiTut>WikiTutForms (13 Jun 2011, vlb)Edit Attach

Wiki Tutorial : Forms

Note: There are multiple, subtly different, things in Wiki land that are all called "forms"!

  • HTML forms - these are wrapped between <form> ... </form> tags and are described in any competent HTML reference.

  • Comment (template) forms - These use the Comment Plugin to present a text area into which a user can enter a comment.

  • Wiki forms - based on HTML forms, Wiki forms look and act like data base fields. They're defined in tables and attached to pages. Wiki forms are very powerful.

HTML Forms

Wiki supports HTML markup and, therefore, HTML forms.

  <form action=...>
     <input type="text" ...
     ...
     <input type="submit" value="Click Me" /> 
  </form>

Actions

In Wiki, the common actions are often Wiki cgi scripts, e.g.

For example, you might open a page in the Wiki editor, sending various text fields, checkbox values, etc to the page as URL parameters (e.g. variables). This is a popular thing to do when initializing new pages from a template.

  <form action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/"> 
  ...

Examples

  • Example 1 - an HTML form that sends data as URL parameters to another Wiki page.

  • Example 2 - an HTML form that sends data to a Wiki form.
    (Also see WikiTutApp for how everything fits together.)

Search Forms

HTML Forms are often used in Wiki to drive a search.

Example 1

For example, here is a very simple search form, as described in the Wiki "Formatted Search" documentation.

Find Topics:
Result:
Number of topics: 0

The Code
  <form action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
    Find Topics: 
    <input type="text" name="q" size="32" value="%URLPARAM{"q"}%" />
    <input type="submit" value="Search" />
  </form>

Example 2

Search forms can be much more complex. AdvancedSearch turns on regular expression searching, then allows additional configuration by radio buttons, menus, and check boxes. This form uses the "search" action.

<form action="%SCRIPTURLPATH%/search%SCRIPTSUFFIX%/%INTURLENCODE{"%INCLUDINGWEB%"}%/">
    <input type="hidden" name="type" value="regex" /> 
    <input type="hidden" name="regex" value="on" /> 
    <input type="hidden" name="header" value="*Results from:* $web" /> 
    <input type="hidden" name="separator" value="$n<hr>$n" />
   ...
</form>

Example 3

The search form at ProjectTracking combines a Wiki Formatted Search (%SEARCH%) with a "view" action to place the results in a table on the same page.

Screenshot
Screenshot

Comment (Template) Forms

Another type of "form" is the Wiki comment form which uses the Wiki Comment Plugin to generate a textarea box on the page that allows users to type and enter comments. In its simplest incarnation, all you need to add to your page is
   %COMMENT%

The plugin does the rest:
 

See: Wiki Comment tutorial for samples.

Wiki Forms

Another type of form is the Wiki Form. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page.

By adding form-based input to a page, topics can be structured with unlimited, easily searchable data fields. Pages with Wiki forms act like a distributed database, making Wiki "applications" possible. See WikiTutApp for details. Wiki forms are defined in Wiki tables. The table contains the following fields:

Name: Type: Size: Values: Tooltip message: Attributes
           

  • Name, Type, and Size are required.
  • Values are required if Type is "select", "radio", or "checkbox".
  • The Tooltip message is optional.
  • Attributes: H or M (optional)

See WikiTutAppE1Form for an example and additional details.

Enable

Wiki forms must be enabled (attached to a topic) before they can be used.

1.You can add the form to a given topic by including the formtemplate parameter in the URL. To add the form MyForm to this topic, you would use
http://wiki.cfcl.com/bin/edit/Help/WikiTutForms?formtemplate=MyForm

2. Wiki applications can add a form at the same time that a template topic is copied. See WikiTutApp for details of applications and template topics.

3. You can make the form available from the "Add Form" button at the bottom of any "Edit" page
Add form button

by adding its name to the FORMS variable in WebPreferences
    * Set WEBFORMS = WikiTutAppE1Form, ProjectDetailForm, TeamContactForm, ...

Result

In "view" mode, a topic with an attached form will show something like this at the bottom of the page:

sample Wiki form in display mode

Accessing Form values

HTML Forms and Topic Content: URLPARAM

HTML forms send field values in the URL. Topic content accesses these values using URLPARAM{...}%.

%URLPARAM{"Xyz"}% variables match "name=" input fields in an HTML form.

If you have an HTML form with
  <input type="text" name="PropertyName" value="" size="60" />

The name="..." and value are sent in the URL; the result is picked up in URLPARAMs.

For this example:

  • The "name" of a text field is "PropertyName"
  • The "value" depends on what the user enters in the field
  • The name and value will be sent in the URL as something like
          .../view/Help/WikiTutPage?PropertyName=Finance
  • The topic can get this value out of the url using
   %URLPARAM{"PropertyName"}%

Comment Plugin Templates

%URLPARAM{"Xyz"}% variables are also used in the OUTPUT section of a Comment Plugin template definition.

See Comment Plugin customization

Wiki Forms: FORMFIELD

Wiki Forms uses FORMFIELD{...}%.

%FORMFIELD{"Xyz"}% variables match "Name" fields in a Wiki form.

To access the value of the PropertyName field in this Wiki Form:

sample Wiki form in display mode

you would use
   %FORMFIELD{"PropertyName"}%

SEARCH: formfield

Formatted search references Wiki form values using $formfield(...).

e.g.
%SEARCH{search="META:FORM.*?WikiTutAppForm" topic="Project.*" 
  type="regex" nonoise="on"
  format="| $formfield(TProjectName) | $formfield(ProjectedLaunchDate) | $formfield(ProjectClassification) |"
}%


Topic attachments
I Attachment Action Size Date Who Comment
AddForm.jpgjpg AddForm.jpg manage 4 K 27 Feb 2009 - 06:51 VickiBrown Add form button
Search_screenshot.jpgjpg Search_screenshot.jpg manage 94 K 27 Feb 2009 - 06:51 VickiBrown Screenshot
WikiFormExample.jpgjpg WikiFormExample.jpg manage 26 K 27 Feb 2009 - 06:51 VickiBrown sample Wiki form in display mode
Topic revision: r12 - 13 Jun 2011, vlb
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email