Extension:Page Forms/Values, mappings and autocompletion

Page Forms offers many options related to both the setting and display of possible values for inputs, both for input types that offer a finite set of options (such as "dropdown" and "checkboxes") and those that offer free-form data entry ("combobox" and "tokens").

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 dropdown input type), or values that are only meant to serve as a guide to the user (like with combobox, although there too these options can be made mandatory, if you add the existing values only 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:

cargo table= + cargo field=	If you have Cargo installed on the wiki, this set of parameters will be automatically used if the input type uses autocompletion, like combobox does. The code will find the Cargo table and field that this template/form field corresponds to, and use all the values that have been set for that field. Or you can use these parameters to specify any combination of table and field you want.
property=	If you have Semantic MediaWiki installed, this parameter will be automatically used if the input type uses autocompletion. The code will find the relevant property and use all of its values, or you can use this parameter to specify a different property.
values from property=	Functionally, this parameter works the same as property=, above, though it lacks some of the side effects: property= can also impact the size and even input type of the field.
values from category=	Gets its values from the names of all pages belonging to a specific category.
values from namespace=	Gets its values from the names of all pages belonging to one or more specific namespaces. To get values from more than one namespace, separate the names with commas. To get values from the main namespace, use "Main", or just leave it blank.
values from content namespaces	Gets its values from the names of all pages belonging to all namespaces in the $wgContentNamespaces setting.
values from concept=	Gets its values from the names of all pages belonging to a specific SMW concept.
values from query=	Gets its values from a Semantic MediaWiki query that includes the current text within the input. The following substitutions must be made to the standard SMW query syntax: In place of [ and ], use ( and ) In place of |, use % Where the current text would go, place @
values from url=, values from external data=, values from wikidata=	see Autocompleting on outside values, below.
values=	Finally, you can simply manually specify the set of values shown to the user; an example would be values=Red,Yellow,Blue. This set of values should be separated by commas by default, but the delimiter can be modified using the delimiter= parameter.

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:

$wgPageFormsUseDisplayTitle = false;

You can enable other such mappings using the following parameters:

mapping template=template name	Takes in the name of a "mapping template" (a template that takes in a single, unnamed parameter, i.e. {{{1|}}}, and displays a "mapped" string as a result), and uses that template to map every potential value, so that the values' "aliases" appear on the screen, and not the values themselves.
mapping property=property name	Used for fields that select pages with 'combobox', 'tokens', 'listbox', and 'dropdown' input types. For each possible value, displays a SMW property from that page rather than the title of the page, but saves the title of the selected page(s) as the field value. Used in conjunction with the values... parameters to get the list of possible values.
mapping cargo table=table name/mapping cargo field=field name	Similar to mapping property= except it is used for Cargo fields. Used in conjunction with values=, values from namespace=, values from category=, and cargo table=/cargo field=. You can additionally use the mapping cargo value field= parameter, which dictates which field in the table used for mapping should be used as the "value" field (by default it is _pageName).
mapping using translate	If the Translate extension is installed, calls Translate's {{int:}} magic word on each value to get the mapped value.

Example 1: mapping template

A form could contain a field tag like this:

{{{field|status|values=Prospective,Live,Retired|mapping template=StatusLabel }}}

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

{{#switch: {{{1}}} | Retired=Label for Retired |Live=Label for Live | Prospective=Label for Prospective }}

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:

{{StatusLabel|{{{status|}}} }}

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:

{{{field|Project members|input type=tokens|mapping cargo table=Employees|mapping cargo field=Employee_name}}}

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:

{{{field|Project members|input type=tokens|mapping cargo table=Employees|mapping cargo field=Employee_name|mapping cargo value field=Employee_ID}}}

Autocompletion

Four of the input types (tokens, combobox, plus text with autocomplete and textarea with autocomplete 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 "Page", 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 $wgPageFormsMaxAutocompleteValues 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:

$wgPageFormsMaxLocalAutocompleteValues = 200;

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:

$wgPageFormsAutocompleteOnAllChars = true;

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

Autocomplete on characters with accent

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 External Data extension.

From an outside URL

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

• values from url=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 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:

   {"pfautocomplete":[{"title":"Germany"},{"title":"Japan"}]}

   This also makes it easy to autocomplete on the values from another wiki.

2. Decide on a short string to represent this URL.

   For example, the service providing lookups in our list of countries could be called "countryLookup".

3. Add the short string to the array in $wgPageFormsAutocompletionURLs in your LocalSettings.php file to configure Page Forms to use your URL when it sees the string. Put "<substr>" 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 http://example.dom/countryLookup.php via the url parameter "c", we'd put:

   $wgPageFormsAutocompletionURLs['countryLookup'] = 'http://example.dom/countryLookup.php?c=<substr>';
   

4. 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:

   {{{field|country|input type=tokens|values from url=countryLookup}}}

From Wikidata

You can have a form input hold, and autocomplete on, values from Wikidata, using the parameter values from wikidata=. The value for this parameter is structured as a mini-query, like P31=Q860861&P17=Q38 ("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 P31=Q860861&P17=Location[Country], where "Location" is a template, and "Country" is a field, above the current one.

Using the External Data extension

Icon images associated with autocomplete values, using "values from external data"

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:

• values from external data=ED variable name (mandatory)
• image=ED variable name (optional)
• description=ED variable name (optional)

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

{{#get_web_data:url=URL |format=csv with header |data=title_variable_name=external_variable_name1,image_variable_name=external_variable_name2, description_variable_name=external_variable_name3}}

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:

{{{field|...|values from external data=title_variable_name|image=image_variable_name|description=description_variable_name}}}

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 values dependent on=, which has this syntax:

{{{field ... |values dependent on=template name[field name]

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: {{{field|City|input type=combobox|values dependent on=Restaurant[Country]}}}

Parameter show on select

For inputs of type 'checkbox', 'checkboxes', 'radiobutton', 'dropdown' and 'listbox', the parameter show on select= 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:

• show on select=value 1=>element ID 1;value 2=>element ID 2;value 3=>element ID 3;...

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

• show on select=value A=>element ID 1;value B=>element ID 1;value B=>element ID 2;value C=>element ID 3;...

If using show on select together with a mapping template, use the labels defined in the mapping template as values (not the true parameter names).

For inputs of type 'checkbox', simply "show on select=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 this form, and observe what happens when you select different values for the "Publication type" dropdown. You can see how that was implemented in this form definition.