Extension:Form

This is the README file for the Form extension for MediaWiki software. The extension is only useful if you've got a MediaWiki installation; it can only be installed by the administrator of the site.

The extension lets users create new articles with a form interface. Administrators configure a "form definition" in the MediaWiki namespace, and the form can be used to create a new article using a particular template.

Typical uses:


 * "New X" interfaces for wiki newbies.

This is a testing version of the extension and it's almost sure to have bugs. See the BUGS section below for info on how to report problems.

License
Copyright 2007 Vinismo, Inc. (http://vinismo.com/)

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

Author
Evan Prodromou 

Pre-requisites
This software was tested with MediaWiki 1.10.0 (which is what Vinismo was running at the time). Current version of the extension requires at least MediaWiki 1.11 or a newer version.

Installation
To install, copy all the files in the archive you downloaded to the SpecialForm subdirectory of the extensions subdirectory of your MediaWiki installation. Note that the software depends on having its code all in the "SpecialForm" sub-directory; naming it "SpecialForm-Test" or "newextension1" or whatever won't work.

In your MediaWiki LocalSettings.php, add the following line some place towards the bottom of the file:

Theoretically it should work out of the box.

Preparing forms
To create a new form, you need to do two things:


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

Form definitions use a special idiosyncratic syntax that may change in the future.

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

There is a sample form definition article in "MediaWiki:Sample-form.wiki" that came with this package, and a corresponding output template in "Template:Sample.wiki".

Form definitions
A form definition article must be named "MediaWiki:Nameofform-form", where "Nameofform" is the name you're going to use for the form. (You can change this pattern by changing MediaWiki:Formpattern, but note that this will affect all of your forms.)

Each line in the form definition file 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 " Results". If the user fills in "2004" and "World Series", the resulting article will be "2004 World Series Results".
 * instructions: wikitext 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
The extension can be seen working with a simple test form such as this, on a page called MediaWiki:Test-form. In the edit box it should look like:

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

You will also need to create a template called Test (to match the "template=" line above). This template will fill the content of the page, using paramaters entered in the form. In this test example, it is simply a short piece of text passed via the "Foobar" parameter. A simple Test template might just contain one sentence: This is simply a test template which uses one parameter.

Then you can go to a Sandbox page and paste the following link: Special:Form/Test

Now you're ready to test the extension. If you click on this link on the Sandbox page, you should see radio buttons labelled "Naming" where you pick Name1, Name2 or Name3. You will then see a box labelled "Foobar" where you enter a piece of 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.

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

Translation
The user interface strings for this extension are configurable through the same Special:Allmessages page as MediaWiki itself. They all start with "form", and they're no more or less cryptic than MediaWiki's.

Translations to other languages besides English are welcome; please send them along.

Bugs and enhancements
Bugs or feature requests can be sent to the author at evan@vinismo.com. The TODO file in this distribution has stuff I think needs to be todone; + marks show things I've already done, and - shows things that are yet to be done.