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 wikitext. 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 four 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 pages: A special page is a "virtual" mediawiki article whose page content is generated by PHP or Javascript code (i.e. it's not saved as a wiki article in the database). They can be used to provide forms for structured input. For information on adding your own special page, see Manual:Special_pages.
 * 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 fourth 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 special pages for adding and editing articles using forms. The extension also includes a framework for designing and storing such forms.
 * Extension:StructuredInput provides special pages for each type of article you want to create. The form associated with each 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 of extensions exist to allow the controlled reintroduction of HTML.

Extension:Simple Forms 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 extension 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.
 * 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.