Extension:Page Forms/Defining forms

Page Forms provides an entire syntax for defining forms, that makes use of tags contained within triple curly brackets. Pages that contain such syntax should always go in the "Form:" namespace (or, for non-English-language wikis, its equivalent in another language). Such pages are not called forms, but rather "form-definition pages", to distinguish them from the actual corresponding forms that users see.

It is recommended that, when starting out with Page Forms, you should not try creating form-definition pages from scratch, but rather use one of Page Forms' helper pages to create them: Special:CreateClass or Special:CreateForm - or copy from some other example, or use the Page Schemas extension. Later on, to make changes to the form, you will most likely have to edit the form definition directly, unless you make use of Page Schemas; in either case, the following documentation should be helpful.

Form markup language
Forms are defined using a set of tags that specify templates and fields within those templates. Wikitext, and some HTML, can be freely embedded anywhere outside of the tags. The allowed tags are:

'info' tag
The  tag holds special information about the form. This tag is optional, but should be placed at the top of the form if it is present. Allowed parameters of this tag are:

'for template' tag
The  tag specifies a template name, and declares that all of the following fields (until   is reached) will be those of this template. The name immediately following the  declaration is the name of the template. Allowed parameters of this tag are:

'end template' tag
The  tag ends the range of a template. There are no parameters for this tag.

'field' tag
The  tag specifies a field to be placed in a form, corresponding to a template field. The name immediately following the  declaration is the name of the template field. There are a large variety of possible parameters to this tag, some of which can only be used for certain input types.

Parameters that can be applied to any field are:


 * The following parameters are input type-specific:

You can find more information about these input type-specific parameters, and in general for form fields, on the Input types page.

'section' tag
The  tag specifies a textarea to be placed in a form, that corresponds to a page section. The name immediately following "section|" is the name of the section. Allowed parameters of this tag are:

The following parameters, which can also be used for the "textarea" input type and the free text input, can also be used for sections. See "The free text input" section below.



'standard input' tag
The  tag is used for ten different inputs that usually appear at the bottom of every form. The text immediately after "standard input|" is the name of each input. The most notable of these inputs is 'free text', which is a textarea that holds all the non-template, non-section text in a page. The other nine are form elements such as the "Save" and "Preview" buttons; see Defining the bottom of the form for the full list.

The 'free text' input has more elaborate handling than the other standard inputs; see below for its allowed parameters.

For the other standard input types, the allowed parameters are:

In addition, the 'watch' input type can take in the parameter 'checked', which checks the "Watch this page" checkbox by default.

The free text input
The "free text" input sets a textarea that holds all the non-template, non-section text in a page. The following parameters for "textarea" fields can also be used for free text inputs:



In addition, there is one parameter available only for the "free text" input - "preload":


 * page title - Specifies a page whose contents should be preloaded into this field.

If it is left out of the form definition, any free text in a page will be preserved in the form as a hidden field, not viewable or modifiable by the user.

Caching
You can have the set of values used for autocompletion in forms be cached, which may improve performance. To do that, add something like the following to LocalSettings.php:

The timeout value is in seconds; it can take any number.

Multiple values for the same field
Page Forms supports having multiple values within a given field, and some form input types - like "checkboxes" and "listbox" - are specifically geared for fields that contain multiple values. Text and textarea fields can also support autocompletion for multiple values. If a form field is meant to hold multiple values, the corresponding template field should most likely contain a call to either #arraymap or #arraymaptemplate - see "Page Forms and templates#Multiple values for the same field". Regardless of what is contained in the template, though, the fact that a field is meant to hold multiple values can be hard-coded in the form definition by adding the parameter "list" to the tag. The parameter "delimiter=" can also be helpful, if the delimiter between values is meant to be something other than the default (a comma).

The default input type for a field with multiple values is "tokens".

Multiple-instance templates
If you add the 'multiple' parameter to a template, it will allow for multiple (or no) instances of this template in the form, and therefore in the generated page. The sample form below, for the 'Item' form, contains two such templates. If you look at the form that this definition generates, you can see that there are two buttons labeled "Add another". Clicking on either of these will create a new instance of that template and its field(s). Instances can be rearranged, by clicking on the icon on the right-hand side and dragging the instance up or down within the set.

You can rename the "Add another" button to any other text, using the " " parameter. For instance, to change the button to read "Add another occupation" for a template called "Occupation", you could have " ".

You can set the minimum and maximum number of instances users can set for such a template, using the " " and " " parameters, respectively.

To avoid overloading the screen, in a displayed form, if the height of all the instances together (in pixels) is greater than the value defined for  (which by default is 800), then all the instances get "minimized", with each one turned into a bar that then expands into the full instance when clicked on. You can change this height value in LocalSettings.php to whatever number of pixels you want. Or, if you want to disable minimizing altogether, just set it to a negative number, like -1. To name the collapsed bar with field names, use ; see 'for template' tag, above.

If you want to semantically store all the data contained in these multiple-instance templates, it is recommended to use either the Cargo extension, the Semantic Internal Objects extension, or Semantic MediaWiki's subobjects. (If you use subobjects, you should not name them, so that each subobject gets an automatically-assigned name .)

Embedded templates
You can choose to have all instances of a multiple-instance template be stored as the value of a parameter for some other template, so that the calls to that template will not look like:

...but instead like:

In order to accomplish this example, you would just need to:


 * Add a tag like " " within the "Person" template part of the form definition
 * Add " " somewhere inside the page Template:Person, so that it gets displayed in pages
 * Add " " to the " " part of the form definition

There are several advantages to this approach:


 * You have much greater control over where the multiple-instance template goes, in both the form and the resulting pages - so you can have it placed between any two fields in the "main" template.
 * You can easily place special text before and after the multiple-instance template, like a table header and footer, without the need for special header and/or footer templates.
 * No spaces get placed between calls to the template, which may potentially help with formatting.

Note that you cannot embed multiple-instance templates inside other (regular or embedded) multiple-instance templates.

An example of using multiple-instance templates with " " and  " " can be found here.

Spreadsheet-style editing
You can have spreadsheet-style editing of a multiple-instance template, using the Jspreadsheet library. Every template call is displayed as one row in the "spreadsheet". To do that, just add "|display=spreadsheet" to the "for template" tag. The wikitext between the "for template" and "end template" tags will get ignored for this display; only the "field" tags are handled.

With spreadsheet-style editing, the  parameter for fields is handled differently. The default is text, and possible alternate values are,   and. If any set of possible values is defined for this field, the display will be a dropdown.

You can also set the height of the display using the  parameter; the default is 200px.

An example of Spreadsheet-style editing can be found here

Calendar-based editing
With "display=calendar", you can create and edit template calls that contain one or more date/datetime fields, using a calendar interface, via the FullCalendar library. Each template call represents one event.

With calendar editing, selecting or creating an event brings up a popup form to edit the event's fields. The popup form handles the standard input types except for,  ,   and.

You can set the field which holds the title of the event through the "event title field" parameter of the "for template" tag. If events in this calendar have only one date, "event date field" should be used. On the other hand, if events have both start and end dates, "event start date field" and "event end date field" should be used.

Defining the bottom of the form
The user inputs at the bottom of the form can be customized using the "standard input" tag. The layout, inclusion and text of each input can be modified. Each user input is defined as a "standard input" tag with its own value; the allowed values are:


 * "save" (for the "Save page" button)
 * "preview" (for the "Show preview" button)
 * "save and continue" (for the "Save and continue" button - this lets users save the page without leaving the form)
 * "changes" (for the "Show changes" button)
 * "summary" (for the "Summary" text field)
 * "minor edit" (for the "This is a minor edit" checkbox)
 * "watch" (for the "Watch this page" checkbox)
 * "cancel" (for the "Cancel" link)
 * "run query" (for the "Run query" button in query forms)

So, for example, the button for "Save page" could be specified with " ", which would place the button where it was defined, with the text on the button reading "Save this page". If no  tags are included in the form definition, the basic seven inputs ("save", "preview", "changes", "summary", "minor edit", "watch" and "cancel") will appear at the bottom of the form, just as they do for regular "Edit" pages. However, if even one such tag is included, then only those inputs which have been included will be displayed, in the order, and with the wiki-text, that they appear in in the form definition.

Sample form
Here is the source code for the 'Item' form definition page at Discourse DB:



Topic:

Position:

Stance:

Item name:

Free text:

Note the presence of both wiki-text and some limited HTML (the 'div' tag) within the code. This markup is based around the templates Item, Opinion and Reference. You can see the working form at this add data page ; the form itself is created on-the-fly from the form definition file. In the 'Items' category page, if you click on any of the pages, you can see the 'edit with form' tab on the top right-hand side. If you click on that tab, you can see this same form, this time populated with the data contained in that page.

The 'wikiPreview' div tag, by the way, is included so that, when the user hits the "Preview" button, they'll be shown the preview directly within the form page, instead of being taken to another page. It is not necessary, and can be safely removed from any form definition.

The #forminput function
Form-definition pages generated by Page Forms (i.e., by Special:CreateForm or Special:CreateClass) always include a call to the #forminput function, which provides an input for users to reach that form. For information on how to modify the #forminput call, see Linking to forms#The two-step process.
 * 1) forminput is not actually a part of the form-definition syntax, though.

Turning forms into tabbed sections
If you think a form is too long for users to fill out comfortably, you can turn it into sections, with a tab interface to navigate between them, using the Header Tabs extension. If you install this extension, it is very easy to add tabs to a form: just add a top-level section wherever you want a tab to appear, of the form "=Tab 1="; and then add the tag  near the bottom of the form, right above the "standard input" declarations. You can place tab declarations between templates, or within templates, to split up the fields of a template into different tabs. You can see a simple example of a form in tabbed sections here; the form definition used to create it is here.

Such tabs can also be used, in a similar way, to display data pages themselves.

Wizard-style display
Another approach to dealing with a large form is to give it a wizard-style interface, which is similar to having tabs but more sequential, in that users are supposed to go in order from the first screen to the last, with each screen containing some number of form inputs. This can especially be useful when there is a lot of explanation required for the different inputs. To have a wizard-style interface, just put HTML tags that look like  around each successive group of inputs that are meant to go together. The following would define three screens, for example, with the third holding a "Save" button:

Field 1:

Field 2:

Field 3: Field 4:

Field 5:

Field 6:

Note that, if you are giving a form a wizard-style display, every part of the form should be part of some "pf-wizard-screen" div.

Reusing form elements
If you have a set of forms that all contain the same text or sections, you can avoid duplication by creating templates that are used within those forms. Simply place all the text that you want repeated within a template, and call that template within each form. If that template contains form elements (like field definitions), the characters within the form elements simply need to be HTML-escaped - replace '{' with '&amp;#123;', '|' with '&amp;#124;' and '}' with '&amp;#125;'. Or just use &lt;nowiki> around them.

Caching form definitions
When a form is displayed, the form definition is parsed twice - first to turn the wiki-text into HTML, and then to handle the SF-specific tags like "". If a form on your wiki takes a long time to display, it might be due to the first parse, which has been known to take seconds to run. You can have form definitions be cached, so the (mostly) HTML version can be retrieved directly, eliminating the first parse. To do this, add the following line to LocalSettings.php:

$wgPageFormsFormCacheType is set to null by default. If left at null, the parser cache will be used for caching. If set to one of the possible cache types (e.g. CACHE_ANYTHING), the selected cache will be used. This way it is possible to switch off the parser cache (e.g. to force re-evaluation of queries on every page load) and still cache the (rarely changed) form definitions.

Note: if any of your form definitions contain any elements that do dynamic display, such as or , these will not get displayed correctly if forms are cached, so you shouldn't use caching.

Tooltips
You can add tooltips to your form in three different ways:


 * If you have the Semantic MediaWiki extension installed, you can use the  parser function defined by Semantic MediaWiki, e.g.,  . (This parser function is not to be confused with Page Form's "  " tag.) See Help:Adding tooltips for more help.
 * Use the  parser function, defined by the SimpleTooltip extension.
 * If you have "display=table" specified within a " " tag, you can add a "tooltip=" parameter for any field in that template.

Making "context sensitive" Forms and Form Fields
In cases where the form page designer wishes to a create context sensitive content or context sensitive lists of values for a field element based on the context of how the form was called (linked to), Page Forms can be used in conjunction with a few other extensions that will assist in providing the context to the form.

Specifically, page designers can add "context variables" to the a  parser function using the " " formlink parameter. This can add a context parameter to the query string of the URL so that when the user visits the form page from the formlink the context variable is available in the URL for processing by the form.

The extension UrlGetParameter can be used to "get" the context parameter from the URL and then use it to contextualize the form in some way.

If either SemanticMediawiki or Cargo is installed, Form page developers can generate custom value lists for form elements based on the context provided in the URL from the formlink query string. A full example using SMW would be as follows:

Let some non-form page include a #formlink that adds the key-value pair "MyContext=Finance" in its link to edit the page "Finance Group Policy Document 001" with the "Policy Document" form as follows:

...

...

..then, in the "Form:Policy Document" form page the form author can make the form context sensitive by using the "MyContext" parameter from the URL in an inline semantic query from SMW as:

...

...

with the understanding that the SMW query would return the specific set of users who belong to the group "Finance" as the list of possible options to choose from in the dropdown menu field.