Template:Form/doc

Use this template to create forms that can create new pages or add content to existing pages.

Parameters

General

The following parameters control the general behavior of the form:

• template — Required! Name of the template that will process and format the submitted data. If you don't want to use a template (or if you want to use several templates) then you can create a template meant to be substituted and set subst:Your template as the value of this parameter.
• page — Name of the page where the data will be posted. If the page doesn't exist, it will be created. If the page exists, the data will be appended. If omitted, the current page will be used. If the given page name contains a string like "{{{x}}}", it will be replaced with the value of the field named "x". This allows to build page names dynamically by combining predefined text and field values.
• section — Name of the section where the data will be posted. If the section doesn't exist, it will be created. If the section exists, the data will be appended. If omitted, the data will be appended to the page. If the given section name contains a string like "{{{x}}}", it will be replaced with the value of the field named "x". This allows to build section names dynamically by combining predefined text and field values.
• redirect — Set this to any value to redirect the user to the page (and section) where the data was posted. If omitted, then a success message defined by submit-success (see below) will be shown instead.
• group — User group that is allowed to fill out the form, for example 'user' or 'sysop'. If omitted, then all user groups are allowed.

Fields

The following parameters control the form fields:

• fieldN (replacing N for a number from 0 to 99) — Name of the field. This will also be the name of the parameter fed to the template. If you want to use anonymous parameters, just name them using numbers (e.g. field1 = 1). If no fields are defined, then the template will be injected with no parameters.
• fieldN-label — Label of the field.
• fieldN-help — Help text of the field.
• fieldN-value — Default value of the field.
• fieldN-placeholder — Placeholder of the field.
• fieldN-required — Whether the field is required. Any value means yes.
• fieldN-disabled — Whether to disable the field. Any value means yes.
• fieldN-type — Type of the field. Supported values are:
  • text — Use it for plain text inputs. This is the default field type. Use fieldN-values, fieldN-values-from-search to suggest values.
  • textarea — Use it for multi-line text inputs.
  • number — Use it for number inputs. Use fieldN-min and fieldN-max to limit the allowed numbers.
  • checkbox — Use it for multi-checkbox inputs. Use fieldN-values to set the checkboxes. If you only need a single checkbox, consider using boolean instead.
  • dropdown — Use it for dropdown menus. Use fieldN-values to set the allowed values. If fieldN-required is not set, then an additional empty option will be included, using fieldN-placeholder as the label.
  • radio — Use it for radio select inputs. Use fieldN-values to set the allowed values. If fieldN-required is not set, then an additional empty option will be included, using fieldN-placeholder as the label.
  • boolean — Use it for boolean inputs. Boolean inputs render as a single checkbox. If the checkbox is checked, then the value of fieldN-value will be posted, or "1" if no value is set. If the checkbox is not checked, then no value will be posted. Use fieldN-selected to control the initial state of the checkbox.
  • hidden — Use it for hidden inputs.
• fieldN-values — Comma-separated list of values. Relevant for fields of type "text", "checkbox", "dropdown" and "radio".
• fieldN-values-from-search — Search query from which to suggest values. Use %s to represent the value typed by the user and see Help:CirrusSearch for other search options. For example, "incategory:Water" will suggest values in the Category:Water, while "%s incategory:Water" will search the category based on the user input.
• fieldN-min — Minimum value for "number" fields.
• fieldN-max — Maximum value for "number" fields.
• fieldN-selected — Initial state for "boolean" fields.

Messages

The following parameters control the form messages:

• submit — Text of the submit button. Default is "Submit".
• submit-success — Text to show when the data is successfully submitted. Default is "The form was submitted, thanks!"
• submit-error — Text to show if an unknown error occurs when submitting the data. Default is "Something went wrong, sorry!"
• template-error — Text to show if the required template parameter is not set. Default is "The template parameter is required."
• namespace-error — Text to show if a form is submitted in the Template namespace. Default is "Forms don't work in the Template namespace."
• group-error — Text to show if the group parameter is set but the user is not part of the group. Default is "This form is restricted to the '$1' group."

Messages

The following parameters control the form messages:

• submit — Text of the Submit button. Default is "Submit".
• submit-success — Text to show when the data is successfully submitted. Default is "The form was submitted, thanks!"
• submit-error — Text to show if an unknown error occurs when submitting the data. Default is "Something went wrong, sorry!"
• template-error — Text to show if the required template parameter is not set. Default is "The template parameter is required."
• namespace-error — Text to show if a form is submitted in the Template namespace. Default is "Forms don't work in the Template namespace."
• group-error — Text to show if the group parameter is set but the user is not part of the group. Default is "This form is restricted to the '$1' group."

Examples

Simple

The following form would inject a call to Template:Message at the bottom of Sandbox:

{{Form
| template = Message
| page = Sandbox
| field1 = name
| field1-label = Your name
| field2 = text
| field2-label = Your message
| field2-type = textarea
| field2-required = required
}}

Loading...

Advanced

The following form would inject a call to Template:Message at the bottom of the talk page of the page entered in the first field, under the section entered in the second field, and the user would then be redirected to it:

{{Form
| template = Message
| page = Talk:{{{page}}}
| section = {{{topic}}}
| redirect = yes
| field1 = page
| field1-label = Page
| field1-type = page
| field2 = topic
| field2-label = Topic
| field3 = name
| field3-label = Name
| field4 = address
| field4-label = Location
| field4-type = location
| field5 = text
| field5-label = Message
| field5-type = textarea
| field5-required = required
| field6 = terms
| field6-label = I accept the terms and conditions
| field6-type = boolean
| field6-required = required
}}

Loading...

Installation

To install this template in your wiki:

1. Create a template with the following markup. You can choose the template name, parameter names and defaults to suit your wiki.

   <includeonly>{{#invoke:WikiForm|main}}[[Category:Gadget:WikiForm]]</includeonly>
   

2. Create MediaWiki:Gadget-WikiForm.js with the following code:

   /**
    * WikiForm extends Module:WikiForm to produce interactive forms that can create pages or add content to existing pages
    * Documentation: https://www.mediawiki.org/wiki/WikiForm
    * Source code: https://www.mediawiki.org/wiki/MediaWiki:Gadget-Global-WikiForm.js
    */
   mw.loader.load( '//www.mediawiki.org/w/load.php?modules=ext.gadget.Global-WikiForm' );
   

3. Add the following gadget to MediaWiki:Gadgets-definition:

   * WikiForm[ResourceLoader|hidden|default|categories=Gadget:WikiForm]|WikiForm.js
   

Done! Add your template to any page to verify that the installation was successful.

See also

• MediaWiki:Gadget-WikiForm.js - JavaScript of this template
• Category:Gadget:WikiForm - Templates in this category will load WikiForm.js