Extension:Page Forms/Input types

This page covers the various input types available within Page Forms, and the parameters and other customizations that can be set for them.

text
The default input type; corresponds to the HTML "text" input.

 Special parameters: 

textarea
Corresponds to the HTML tag.

 Special parameters: 

text with autocomplete, textarea with autocomplete
These two inputs were turned into aliases for "combobox" and "tokens" in version 5.0. For earlier versions, these are displayed in the same way as the and  input types, and they can be configured in the same way, but they also provide autocompletion - on one or multiple values. See the "Setting values and mappings" and "Autocompletion" sections below for how to customize the autocompletion.

combobox
The "combobox" input type provides a combo box interface: an input that functions like a regular autocomplete field, but has an additional down-arrow icon, like that of a dropdown, to let the user see all the available values at once. It is implemented using the [ http://ivaynberg.github.io/select2/ Select2] JavaScript library.

Special parameters:

tokens
This input type "tokenizes" the values in the field, i.e puts a block around each value to make it a single unit instead of just a string of characters. These "tokens" can then also be rearranged. Like "combobox", this input is implemented using the [ https://select2.github.io/ Select2] JavaScript library.

Special parameters:

By default, "tokens" appears as a single-row input, then expands vertically if necessary as more values are added. In some cases, you may want this input to appear taller than one row when it starts out, to make it clearer to users that it will expand. To do that for a single input, add a parameter to the field tag, like "  ", then add something like the following to MediaWiki:Common.css:

If you want this to apply to all "tokens" inputs in the wiki, add something like this to MediaWiki:Common.css instead:

radiobutton
The "radiobutton" input corresponds to the HTML "radio" input. It shows a set of values from which the user can only choose one.

By default, the first radiobutton value is "None", which lets the user choose a blank value. To prevent "None" from showing up, you must make the field "mandatory", as well as making one of the allowed values the field's "default=" value.

dropdown
The "dropdown" input corresponds to the HTML &lt;select&gt; tag. It shows a dropdown list of values, from which the user can only choose one.

checkboxes
The "checkboxes" input displays checkboxes to let the user choose any number of values. If there are more than a certain number of checkboxes, "Select all" and "Select none" links will automatically appear above the set of checkboxes, allowing users to automatically check all or none of them. This number is dictated by the variable, which by default is 10, though it can be changed in LocalSettings.php.

Special parameters:

listbox
The "listbox" input corresponds to the HTML &lt;select&gt; tag, with the "multiple" attribute added. It shows a vertical list of options, where the user can select any number of values.

Special parameters:

tree
The "tree" input type allows for a hierarchical, tree-style input, where all the values have either radiobuttons or checkboxes next to them, depending on whether the field can hold one item or many. Values can either come from a category tree within the wiki, or be set manually within the form definition.

How does this input know whether it can hold one or multiple values, and should thus display radiobuttons vs. checkboxes? It checks whether the field in the template is defined as holding a list of values (using #arraymap) or not. This check is not perfect, though. If the tree input is showing radiobuttons instead of checkboxes, you just need to add the parameter " |list " to the field tag in the form definition, to establish that this is a list.

Depending on the source of the values, you need to specify one of these two additional parameters:


 * - sets the name of the category at the top of the "tree".
 * - sets the entire tree structure; should use wikitext-style bullets to set the depth level.

If you use the "structure" parameter, it should look something like this:

You can also optionally set these parameters:


 * - sets the height, in pixels, of the box in which the tree appears.
 * - sets the width, in pixels, of the box in which the tree appears.
 * - sets the delimiter when the field can hold a list of values. Default is ','.
 * - hides the name of the top category.
 * - sets the number of levels of the tree that are shown at the beginning. Default is 10.

You can see a sample form that uses this input type [ http://discoursedb.org/wiki/Form:Category_input_test here].

For category names
If you're using the "tree" input type to display a category tree, note that this input will print out only the names of the categories selected, without the "Category:" namespace before it; so if you want that to show up in the page as well, the template will have to add it.

If the field specifies multiple categories, and the template uses #arraymap to do it, the call to #arraymap should look something like:

...in other words, you need to specify the final "delimiter" parameter for #arraymap, and make it a space, blank or something similar, to avoid printing commas between the category tags.

checkbox
A single checkbox, used for boolean values.

Special parameters:

date
This input contains three separate entries, for the year, month and day.

datetime
The " datetime " input is similar to the " date " input, but includes additional entries for hours, minutes, seconds and AM/PM.

Special parameters:

datepicker
" datepicker " lets the user pick a date with the help of a JavaScript-based popup calendar.

Special parameters:

The starting day of the week (e.g., Saturday, Sunday or Monday) is set based on the language of the wiki; it unfortunately cannot be set independently of the language. If your wiki is in English and you would like weeks in the calendar input to start on Monday instead of Sunday (which is the default), you can do that by setting your wiki's language to be " en-gb " instead of " en ".

datetimepicker
" datetimepicker " is a JavaScript-based input type very similar to " datepicker ", but it includes popups for selecting both the date and time. It defaults to. Its set of parameters includes all of those " datepicker " as well as the following:

rating
The " rating " input type displays a set of stars to let the user enter a rating.

Special parameters:

googlemaps, leaflet, openlayers
The " googlemaps ", " leaflet " and " openlayers " input types let you display a map to get a coordinate value, using the Google Maps, Leaflet or OpenLayers services, respectively.

If you are using the "googlemaps" input, you may need to get a [ https://developers.google.com/maps/ Google Maps API key], then set it in LocalSettings.php via the setting, for the input to display.

You can also optionally set these parameters for these input types:

The "leaflet" input type also allows one additional parameter:

All of the map inputs lets you enter an address to locate the coordinates more easily. But if the form already contains one or more fields to enter the address, then the user may have to enter it twice - once to actually store the data, and the second to locate the coordinates. To avoid users having to do this double work, you can have the address field(s) feed their values directly to the map when locating the point. You can do that using the "feeds to map=" parameter - look for "feeds to map" here.

All of these formats, by default, rely on external JavaScript code. However, you can have the "openlayers" format use local JavaScript code instead, by just installing the OpenLayers extension.

Disabling
Note that these input types all send your wiki's data (that is, the data contained in the query results) to external services. They are the only part of the Page Forms code that sends data externally, other than autocompleting on outside values, though that one requires additional configuration to run. If you have a private wiki and are very concerned about no data getting out, you may want to add the following to LocalSettings.php:

This will disallow the use of any outside services by Page Forms - which at the moment means disabling these three input types.

regexp
The " regexp " input type is not a true input type, but rather the ability to display another input (most often "text") with additional, regular-expression-based validation. See here for a more detailed explanation of this input type and its parameters.

Allowed input types for data types
Each defined data type, when using either Cargo or Semantic MediaWiki, has a default input type, and, when applicable, a default input size as well. Additionally, some data types have special handling if the field holds a delimited list of values, instead of just a single value.

Here are the defaults and the other allowed input types for each data type, for single values:

And here are the default and other allowed input types for delimited lists of a certain data type:

Setting values and mappings
Some input types provide the user with pre-defined values. These can be values that the user is required to choose among (like with the input type), or values that are only meant to serve as a guide to the user (like with , although there too these options can be made mandatory, if you add the  parameter).

For both cases, the set of parameters for specifying the values shown to the user is nearly the same. Here are the parameters for the "field" tag that can be used in all cases:

There are several more options for the autocompletion-based inputs; see "Autocompletion", below.

Mapping
You can have the set of values displayed to the user be different from the set of values that actually show up in the page's wikitext. If the values are page names, and those pages have a "display title" set that is different from their real page name, then by default the form will display the display title instead of the page name. If you want, you can have the page name itself displayed, by adding the following to LocalSettings.php :

You can enable other such mappings using the following parameters:

Example 1: mapping template
A form could contain a field tag like this:

The template at Template:StatusLabel could then contain something like:

You could then use that same " mapping template " to display the label of the value on regular, non-form pages. Within the template that contains the field "status", you could have the following:

Example 2: Cargo-based mapping
Let's say that, in a company, every employee is assigned an employee ID. In the wiki, the page about each employee has as its name the employee ID. There are also pages about projects, and within each project page is a "Project members" field, which holds a list of employee IDs. In the "Project" form, in the "Project members" input, you want people to enter in employees' actual names, but have the employee IDs show up on the page. You could do that with the following field tag:

Now, what if the name of each employee page is not the employee ID (nor their real name) but rather a randomly-assigned name, like "Employee 12345"? Then you could do the mapping using the additional "mapping cargo value field" parameter, like this:

Autocompletion
Four of the input types (,  , plus   and   for versions before 5.0) use autocompletion — as the user starts typing, the input shows a dropdown list of possible completions.

If a field represents a Semantic MediaWiki property, or Cargo field, of type " ", autocompletion will be enabled by default — the field will autocomplete on the names of all pages that are already pointed to by that property or field. For any other type, there is no default autocompletion, but you can achieve this same effect simply by setting the input type to one of the four types that have autocompletion.

You can manually set a field to autocomplete on the set of values from an SMW property, a Cargo field, a category, a namespace, a "concept", or a manually-set list, by using one of the "values ..." parameters - see "Setting values and mappings", above.

You can also autocomplete based on values outside the wiki, contained in web pages, databases, files, etc.; see "Autocompleting on outside values" below for the various ways to do this.

If a field is specified to hold multiple values, autocompletion will, by default, support multiple values: after a value is entered, and a delimiter placed, a new autocompletion will start for the next value. You can manually specify that a field should have multiple-value autocompletion, by adding the " list " parameter to the field's definition. You can also specify the delimiter for this list of values, using the " delimiter=... " parameter (the default is a comma).

By default, the maximum number of autocompletion possibilities that a field will offer is 1,000; this is for performance reasons. To change this number, change the value of in LocalSettings.php.

Disabling
You can disable autocompletion, if it's enabled by default for a field, by setting the input type to be simply " text " or " textarea ".

Remote autocompletion
The set of a field's possible values for autocompletion is, by default, contained right within the form's HTML page, in a JavaScript declaration. For performance reasons, there is a limit to how many values can be placed in the page; by default the limit is set to 100. After that number is reached, remote autocompletion is done instead, where autocompletion happens through an Ajax call to the server, based on what the user has typed. This type of autocompletion is slower, but allows for many more autocompletion results.

You can change the default by adding something like the following to LocalSettings.php :

Matching on every character
By default, Page Forms autocompletion matches on the beginning of every word in the set of possible values. However, you can change autocompletion to instead match on every character, by adding the following line to LocalSettings.php :

This feature is especially important for wikis that have values with non-ASCII characters, such as wikis in languages with non-Roman alphabets; since the default, word-based autocompletion doesn't yet work with non-ASCII characters.

Autocompletion on characters with accents


Flexible autocompletion for characters with accents is supported by the combobox and tokens input type.

Accent-folding has its limitations but it can help make some important yet overlooked user interactions work better. An accent-folding function essentially maps Unicode characters to ASCII equivalents. With accent-folding, it doesn’t matter whether users search for cafe, café or even çåFé; the results will be the same.

Autocompleting on outside values
There are some ways to have a field autocomplete using data from outside the wiki:


 * from an API-like URL that takes in a substring and returns data in the necessary JSON format
 * from Wikidata
 * from any external source, using the extension.

From an outside URL
You can have a field autocomplete on values from outside the wiki, using the following parameter:


 * URL identifier

To do so, take the following steps:


 * 1) Create a page/web service that takes in a substring via the query string, and displays a set of completion values.   Page Forms expects to get a JSON format response with a toplevel key of " pfautocomplete " and an array of objects with the " title " key marking the values of possible completions.  You can see a brief example of this [ https://www.semantic-mediawiki.org/w/api.php?action=pfautocomplete&substr=an&property=Country&format=json from this API call on semantic-mediawiki.org].
 * For example, if you had a list of three countries -- Uruguay, Germany , and Japan -- and were asked for a list of possible completions for " an ", you would return:
 * This also makes it easy to autocomplete on the values from another wiki.
 * 1) Decide on a short string to represent this URL.
 * For example, the service providing lookups in our list of countries could be called " ".
 * 1) Add the short string to the array in  in your LocalSettings.php file to configure Page Forms to use your URL when it sees the string.  Put "  " where you want the user's input will go.
 * In our example, if we want Page Forms to feed the user's keystrokes to the url via the url parameter "  ", we'd put:
 * 1) Add the parameter " values from url= URL-identifier-string" to the relevant field in the form definition.
 * For our country example, we might have a field that looks like:
 * 1) Add the parameter " values from url= URL-identifier-string" to the relevant field in the form definition.
 * For our country example, we might have a field that looks like:

From Wikidata
You can have a form input hold, and autocomplete on, values from Wikidata, using the parameter. The value for this parameter is structured as a mini-query, like  ("instance of" = "sculpture", "country" = "Italy"). The "Q" values can also be replaced by field names, to enable a Wikidata-based version of "show on select", for example, where "Location" is a template, and "Country" is a field, above the current one.

Using the External Data extension


The External Data extension (ED) supports retrieving data from a number of sources which include external URLs, regular wiki pages, uploaded files, files on the local server, databases and LDAP directories.

To autocomplete using ED, you need to first call any of ED's " #get_..._data " parser functions within the form definition (preferably at the bottom of the form definition, to avoid unnecessary line breaks). This will fetch data that can then be used in the field tags. (See the External Data documentation for how to call these.) The field tag may then use these parameters:


 * ED variable name (mandatory)
 * ED variable name (optional)
 * ED variable name (optional)

Here is a sample call to #get_web_data to fetch data from some URL:

Assuming a form definition contains a call like that, a field tag can then use the values retrieved for autocompletion - not just to set the autocomplete values themselves, but also, if the input type is " combobox " or " tokens ", to set a corresponding thumbnail image and description for each one.

Assuming our External Data call retrieved three "columns" of values, as the one above does, the field tag using this data could look like:

Dependent autocompletion
You can set a field's autocompletion values to be based on the value a user has already set of another field in the form. This is done with the parameter, which has this syntax:

It specifies that the current set of allowed values for this field are all the values taken by this same field from pages where 'field name'  is equal to the value selected for  'field name'  in the current form.

Is that confusing?

Well, this example may help: if a template is called " Restaurant " and it has template fields (not properties) named " Country " and " City ", and you want the set of cities that are used for autocompletion to be only those cities in the country that the user selected, then the field tag for the City field should look something like:

Uploading files
If a field in the form is meant to hold the name of an uploaded file (say, an image), you can allow users to upload this file directly through the form. This is done simply by adding the parameter "uploadable" to that field's declaration in the form definition. This will add a link reading "Upload file" next to this field in the form; if the user clicks on this link, it will pop up a "lightbox"-style window (using the FancyBox JavaScript library) that lets the user upload a file. Once the user has done so, the window will close, and the field will contain the name of the uploaded file. If the field is configured to contain a list of values, the new filename will be appended to whatever was there before; otherwise, the filename will overwrite whatever the field contained before.

Note that the " uploadable " parameter can only be used in fields of type " text ", " text with autocomplete", " combobox " or " tokens ".

For uploadable fields, you can also set the default filename of the uploaded files, by setting the " default filename= " parameter in the field definition. The value of this parameter can include parser functions, magic words and the like. It can also include the variable " &lt;page name> ", which gets substituted with the name of the page being added or edited. So adding to the field definition the parameter " default filename=Image for &lt;page name> ", for instance, for a page called " Abc ", would set the default name of any uploaded file to " Image for Abc ". Note that if you simply want to specify a default file to use such as " Imageneeded.png " the regular " default=Imageneeded.png " parameter will do.

You can see a demonstration of file uploading [ http://discoursedb.org/wiki/Form:Images_test here].

Note that the upload window will not work if is set to  in your LocalSettings.php file.

You can also set uploadable fields to use the operating system's own uploading directly, instead of using MediaWiki's uploading system - this gives the user fewer options, but it is a simpler process, and on mobile devices it can present some interesting options, like uploading photos right after they are taken. To do this, add the following line to LocalSettings.php file:

The special parameters for uploadable fields are:
 * - Specifies that this is an uploadable field.
 * - Specifies that a thumbnail of the uploaded image should be placed under the field in the form.
 * filename - Specifies the default filename for files uploaded with this field.

Parameter show on select
For inputs of type ' checkbox ', ' checkboxes ', ' radiobutton ', ' dropdown ' and ' listbox ', the parameter specifies that one or more elements on the page should only be displayed if and when certain value(s) are selected within that input.

The syntax for this parameter is:



A value can be provided with more than one element-id:



For inputs of type ' checkbox ', simply " element ID" should be used. Note that the element IDs cannot contain spaces and/or multibyte characters and cannot start with a number.

For an example of this feature in use, see [ http://discoursedb.org/w/index.php?title=The_New_York_Times&action=formedit this form], and observe what happens when you select different values for the " Publication type " dropdown. You can see how that was implemented in [ http://discoursedb.org/w/index.php?title=Form:Source&action=edit this form definition].