Manual:Forms

Out-of-the-box MediaWiki uses Form-based data entry for a variety of page maintenance and administrative functions. MediaWiki articles themselves are created using free-form wiki-text. Like most other features of MediaWiki, there are numerous customization possibilities available. These include ready-made extensions, various techniques for customizing the default set of forms, and even techniques for creating and installing custom forms.

Customizing built-in forms
Please see the following articles:


 * General:
 * Manual:Interface, Manual:System message - describes how to customize/localize the text that appears on the built-in forms used by MediaWiki.
 * User authentication forms:
 * UserCreateForm hooks - functions attached to this hook can define a replacement for the standard form to create a new user.
 * UserLoginForm hooks - functions attached to this hook can define a replacement for the standard login form.

Creating/editing articles with structured data
Some articles contain a mix of structured data and free form text. For example, an article that holds a description of a marketing contact or a bug report would normally have a set of questions that must always be answered to create a complete article. In this case, a form or an article with some preloaded wiki text might be more appropriate.

MediaWiki has three strategies for handling these kinds of situations:


 * Creating pages with preloaded text: Typically the freeform text includes a template with blank parameter values. The user fills in the template parameters as a kind of form within the wiki-text. The advantage of this approach is that, with the help of a few extensions, it can be easily implemented by end-users with basic wiki text and template knowledge.  The disadvantage is that the forms are in wiki text and can be typed over by a careless user.  For more information on this approach, please see Manual:Creating pages with preloaded text.
 * Special page extensions: A special page is a "virtual" mediawiki article whose page content is generated by PHP code. One method for structured input is to install an extension that generates a form to create or edit an article.  A list of extensions currently available, can be found at Category:Special page extensions.
 * You can also write your own such form. Writing your own extension requires PHP coding skill and comfort with object oriented design and databases also is helpful.  You will also need to know how to use code to create and edit MediaWiki articles. For more information, please see Manual:Special pages and the discussion of Articles with embedded forms below.
 * Articles with embedded forms: Another approach to form based data entry is to create an article whose sole purpose is to define a data entry form. This can be viewed as kind of hard coded special page. The main advantage of this approach over the special forms approach is that one can easily put together an infrastructure that will let users create the data entry forms as part of the normal MediaWiki editing process.  Articles with embedded forms for more information.
 * Intercepting the edit action: A forth approach is to take over all or part of the MediaWiki editing process. When MediaWiki loads a page, it checks the action query parameter and calls one or more hook functions based on its value.  By attaching a function to one of these hooks you can reinvent the entire page editing process.  For more information, please see Intercepting page actions.

Special pages with embedded forms
A handful of extensions provide frameworks for creating special page based forms. They include:
 * Extension:Semantic Forms - provides a special page for adding articles using forms. The extension also includes a framework for designing and storing the forms.
 * Extension:StructuredInput provides special pages for each type of article you want to create. The form associated with each special special page is stored in a function that returns the HTML code that generates the form.

If you would like to write your own special pages from scratch or develop an alternative framework, please see Manual:Special pages.

Articles with embedded forms
Creating an article with an embedded page creation form involves two design steps:


 * 1) Embed the form in an article
 * 2) Edit the page programatically

For security reasons MediaWiki limits the kinds of HTML you can embed directly in wiki text. Plain vanilla MediaWiki won't let you create data entry forms directly in the wiki text. However, a variety extensions exist to allowed the controlled reintroduction of HTML.

Extension:Simple Forms provides provides support for both these steps. HTML forms are embedded into pages using parser functions. The data collected by the form is passed to a javascript that sets query parameters that define what content to insert into the article and where. The extension takes care of the process of interpreting those parameters and editing the article appropriately.

If you wish more control over the page generation process or simply have a better idea for a framework for creating articles with embedded forms, you may wish to consider Extension:HTMLets. This extensions lets one define files containing HTML forms. These files are stored in a subdirectory of the MediaWiki installation (permissions set appropriately to prevent random editing or direct server access), and can be inserted into wiki text using the tag   where name is.

Once you've defined your form file, you'll need to use the data collected by it to create an article. You can do this by having your form generate a URL that contains an  query parameter. When MediaWiki loads a page, it checks the action query parameter and calls one or more hook functions based on its value.

Most of these actions have set meanings, so you won't want to use any of the standard actions. Rather you will want to create your own "autocreate" or "autoedit" action. To do this, you add a function to the UnknownAction hook.

For more information on programmatically creating or changing page content, please see:
 * EditPage.php
 * Manual:Edit token

Taking over the editing process
An alternative to either special pages or forms embedded in articles is to take over the page editing process. This is accomplished by adding a custom function to one or more of the several hooks that get invoked during the course of the editing process.


 * AlternateEdit - is called when action=edit. It gives MediaWiki installations an opportunity to provide an alternate response to the edit action. For an example of an extension that uses this approach to form-based editing, see User:Barrylb/Custom article editing form with fields.
 * EditPage::showEditForm:initial is called when the text window used to enter MediaWiki text is displayed. It gives extension writers the ability to define an alternative to the simple edit box. For a list of extensions that use this hook, see Category:EditPage::showEditForm:initial extensions.

Emailing structured data
Forms on websites are also used to gather structured data and distribute it via email or some other notification system. Several extensions have been designed to facilitate this use of forms. General purpose extensions let you customize the mail message and sender list:


 * Extension:EmailForm, Extension:FormHandler send form by Email - provides a wiki tags that can be embedded in article text. The tag collects data using a form and sends it via email to a list of pre-defined recipients.
 * Extension:FormProc and Extension:FormTools - a framework for defining email contents using PHP code embedded in MediaWiki articles. (Note: embedding PHP code is a potential security risk - please see Extension:Runphp/Extension:Runphp page.)
 * Extension:FormMailer - sends email messages to a predefined list. The content of the email message can be any form(???), including forms created by Extension:Simple Forms.

Extensions that send special purpose emails are also available. They require little design work, but also are more limited in customization possibilities:


 * Extension:Mailman - embeds a simple form within an article. The form generates a simple form for subscribing to a list managed by Mailman.