Help:Extension:Form

For technical documentation, see Extension:Form.

Preparing forms

To create a new form do the following two steps:

• Create a "form definition" in the MediaWiki namespace.
• Create an output template that describes the structure of the resulting articles.

Output templates are just regular MediaWiki templates. They should use named parameters rather than numbered parameters.

There is a sample form in "MediaWiki:Sample-form.wiki" and output template, "Template:Sample.wiki" in the form folder, also below

Sample form

title=Ew-nay Ample-say
namePattern={{{topic}}}
instructions=You can use this page to create a new article on a sample topic.
topic|Topic|text|Topic of the article.
purpose|Purpose|select|Purpose of the
article|items=Business;Pleasure;Other
intro|Introduction|textarea|An introductory paragraph about the topic.
color|Color|radio|Color of the article|items=Red;Blue;Green
conclusion|Conclusion|textarea|The conclusions of the topic.

Sample template

The topic is {{{topic}}}.

The purpose is {{{purpose}}}.

== Introduction ==

{{{intro}}}

== Color ==

{{{color}}}

== Conclusion ==

{{{conclusion}}}

Form definitions

A form definition article must be named "MediaWiki:Nameofform-form", where "Nameofform" is the name you are going to use for the form.

Each line in the form page is either a form attribute or a form field definition. Each is described below.

Form attributes

Form attributes define information for the form as a whole. Each attribute line looks like:

name=value

Note that no whitespace is tolerated before and after the name. Typically form attributes appear at the beginning of an article, but they are tolerated anywhere in the article, if you need things that way.

Valid names for form attributes are as follows:

• template: name of the output template (without the namespace prefix) that will be used for creating new articles. If this is not defined, the default name will be "Template:Name", where "name" is the name of the form.
• title: title that's shown on the form. By default, this is "Add New $1", where $1 is the name of the form. You can change the default title pattern with by changing MediaWiki:Formtemplatepattern.
• namePattern: the pattern for new article names. This is based on the fields in the form, and uses MediaWiki template-substitution syntax (badly... only the simplest syntax is now supported). For example, if you are creating articles about sporting events results, and there are two form fields "year" and "event", the name pattern might be "{{{year}}} {{{event}}} Results". If the user fills in "2004" and "World Series", the resulting article will be "2004 World Series Results".
• instructions: Wiki-text instructions for users of the form. Will be shown at the top of the form before any fields.

Form field definitions

Each field in the form has a line defining it in the form definition file. The structure of the field definition lines is:

name|label|type|description|options

The parts of the field definition are separated by pipe ("|") characters and cannot include pipes themselves (even with "escape" characters). The parts of the definition are defined below:

• name: name of the field. It must be unique, and contain only alphabetic or numeric characters or the underscore ("_"). This will be the parameter name used for the output template.
• label: readable name for the field, used for labels. No restrictions, except for the lack of a pipe. No HTML or wikitext allowed (yet).
• type: type of the form field (see below).
• description: a user-readable wikitext description of the purpose and restrictions on the form field. Only shown for 'textarea' fields right now, but will eventually be shown for all fields once I figure out the layout correctly.
• options: optional parameters for the field, mostly dependent on the field type. options always take the form "name=value", and are separated by commas (",").

The description and options parts are optional.

Form field types

The following types of form fields can be created.

• textarea: an HTML textarea, e.g. a big multi-line entry area. These are usually used for lots of paragraphs. The following options are supported:
  • rows: number of rows; defaults to 6.
  • cols: number of columns; defaults to 80.
• text: a one-line text input. Takes these options:
  • size: length of the text input; defaults to 30.
• checkbox: a yes-no, on-off choice for the user. Takes no options.
• radio: a group of radio buttons; exclusive choices. Radio button groups take the following options:
  • items: semicolon-separated (";") list of choices for the user. For example, "Blue;Green;Red" will give the user three radio buttons labeled "Blue", "Green", and "Red".
• select: a drop-down box showing multiple exclusive choices for the user. Select boxes take the following options:
  • items: semicolon-separated (";") list of choices for the user. For example, "Blue;Green;Red" will give the user a drop-down box with three choices, "Blue", "Green", and "Red".

Example

First

Create the page MediaWiki:Test-form and paste the following:

template=Test 
title=Test of Form extension 
namePattern={{{Name}}} 
Name|Naming|radio|description|items=Name1;Name2;Name3 
Foobar|Foobar|text|Enter some text 

Second

Create a Template:Test and add:

This is simply a test template which uses one {{{Foobar}}} parameter.  

This template will fill the content of the page, using information entered in the form. In this test example, it is simply a short piece of text defined in the {{{Foobar}}} parameter.

Special:Form/Test

Third

Go to the page Special:Form/Test you will see the form.

Fourth

On the page Test paste: [[Special:Form/Test]]

Testing the extension

This Test page has three radio buttons l where you pick Name1, Name2 or Name3. You will then see a box labeled "Foobar" where you enter text.

If you type "hello" into the text field, and select the Name2 button, you will create a new page called Name2 which contains the following:

This is simply a test template which uses one hello parameter.

Capitalization matters; if you use foobar in the template, and Foobar in the form, the parameter will not be passed.

Using forms

To show a user a form, use the following special-page format:

Special:Form/Name

Where "Name" is the name of the form. This will load the form definition from "MediaWiki:Name-form", and by default use Template:Name for the output template.

The user can fill in the form fields and hit "save" to save the article. Note that currently no validation is performed; if the user fails to complete a required field, it will be rendered empty.