Manual:Forms

From MediaWiki.org
Jump to: navigation, search
Language:Project:Language policy English  • 日本語

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[edit]

Please see the following articles:

Creating/editing articles with structured data[edit]

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 textManual: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#Custom 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. See 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[edit]

A handful of extensions provide frameworks for creating special page based forms. They include:

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

Articles with embedded forms[edit]

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 FormsExtension: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:HTMLetsExtension: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 <htmlet>name</htmlet> where name is htmldir/name.html.

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 action query parameter. When MediaWiki loads a page, it checks the actionManual:Page 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 UnknownActionManual:Hooks/UnknownAction hook.

For more information on programmatically creating or changing page content, please see:

Taking over the editing process[edit]

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.

Emailing structured data[edit]

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:

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.

See also[edit]