Extension:页面表单/输入类型

本页面介绍了Page Forms中的各种输入类型，以及可以为其设置的参数和其他自定义设置。

输入类型

text

默认输入类型；对应HTML的“text”输入。

特殊参数：

size=size	设置输入框的宽度，单位为字符。
maxlength=maximum length	设置输入的最大长度。
placeholder=placeholder text	设置在用户输入之前显示在输入框中的帮助文本。
autocapitalize=value	the autocapitalize parameter in the corresponding HTML tag to whatever value is set for this parameter; examples include on, off, sentences, etc.

textarea

对应HTML的 ‎<textarea> 标记。

特殊参数：

rows=num rows	指定行数。
cols=num cols	指定列数。
maxlength=maximum length	设置输入的最大长度。
autogrow	设置文本区“自动增长”其高度以匹配其内容，这样就不需要滚动条。
editor=editor type	将基于JavaScript的编辑器添加到输入框，使编辑更方便。支持以下值： wikieditor - 要使用它，必须先安装 WikiEditor 扩展。 不幸的是，由于WikiEditor扩展的限制，表单中只有一个输入框可以与WikiEditor关联。 如果您想向WikiEditor添加任何额外的custom toolbars ，您需要在JavaScript中将它们添加到('#free_text').wikiEditor，就像在('#wpTextbox1').wikiEditor中一样。 Note that there was a change to the WikiEditor code in the version that corresponds to MediaWiki version 1.34 that broke this functionality. It was restored in the 1.36 version of WikiEditor, with a corresponding change in version 5.1 of Page Forms. If you are using a version somewhere in the middle for WikiEditor, and you don't want to upgrade MediaWiki, you can manually apply the necessary change to the code, which can be found here. You should also upgrade to version 5.1 or later of Page Forms if you are using an older versions; or you can apply the Page Forms patch here. tinymce - 要使用它，必须先安装 TinyMCE 扩展。 This does not work with multiple-instance templates. visualeditor - 要使用它，必须先安装 VisualEditor 扩展和 VEForAll 扩展。 如果您希望工具栏显示在输入框的顶部而不是底部（默认），需要添加|class=toolbarOnTop
max height=maximum height	使用VisualEditor的情况下，这项值可以指定输入框的最大高度（以像素为单位），因为VE的输入框会自动增长。默认值为400。 The default value for this is set by the variable $wgPageFormsVisualEditorMaxHeight, which by default is 400.
placeholder=placeholder text	设置在用户输入之前显示在输入框中的帮助文本。

具有自动输入功能的文本/文本区域 These were formerly real input types, but have been aliases for "combobox" or "tokens" (depending on whether the input holds a list of values, or just one) since version 5.0.

combobox

Combobox输入

“combobox”输入类型提供了一个combobox界面：这个功能类似于常规的自动输入，但有一个额外的向下箭头图标，就像下拉菜单一样，可以让用户一次看到所有可用的值。 它是使用[$url Select2]JavaScript库实现的。

特殊参数：

size=size	设置输入框的宽度，单位为字符。
height=height	Specifies the height of the combo box, in pixels.
existing values only	只允许输入设置的值
placeholder=placeholder text	设置在用户输入之前显示在输入框中的帮助文本。

tokens

Tokens输入

这种输入类型将字段中的值“tokens化”，用一个块包括每个值，使它们成为一个个单元，而不仅仅是一串字符。 这些“tokens”也可以重新排列。 就像combobox一样，它也是使用Select2JavaScript库实现的。

特殊参数：

size=size	设置输入框的宽度，单位为字符。
max values=max values	设置允许的最大值数。
existing values only	只允许输入设置的值
placeholder=placeholder text	设置在用户输入之前显示在输入框中的帮助文本。

默认情况下，“tokens”只显示一行，然后在添加更多值时根据需要垂直展开。 在某些情况下，您可能希望在即将输入时的显示高于一行，以使用户更清楚地看到它的展开。 To do that for a single input, add a class parameter to the field tag, like "|class=ClassName", then add something like the following to MediaWiki:Common.css:

.ClassName, .ClassName .select2-choices {
        min-height:60px;
}

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

#pfForm .select2-container-multi .select2-choices {
        min-height: 60px;
}

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 <select> 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 $wgPageFormsCheckboxesSelectAllMinimum, which by default is 10, though it can be changed in LocalSettings.php.

Special parameters:

hide select all	hide the "Select all" and "Select none" links for this input, regardless of the number of values
show select all	display the "Select all" and "Select none" links for this input, regardless of the number of values

listbox

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

Special parameters:

size=size

Specifies the height of the listbox, by the number of lines shown

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:

• top category= - sets the name of the category at the top of the "tree".
• structure= - 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:

{{{field|Location|input type=tree|structure=*Universe
**Milky Way Galaxy
***Solar system
**Andromeda Galaxy
...etc.
}}}

You can also optionally set these parameters:

• height= - sets the height, in pixels, of the box in which the tree appears.
• width= - sets the width, in pixels, of the box in which the tree appears.
• delimiter= - sets the delimiter when the field can hold a list of values. Default is ','.
• hideroot - hides the name of the top category.
• depth= - 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 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:

{{#arraymap:{{{Categories|}}}|,|x|[[Category:x]] |<nowiki> </nowiki>}}

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

label=

specifies a "label" for this checkbox, which would go into a ‎<label> tag.

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:

include timezone

specifies that a time zone entry should also be included.

year

"year" is a simple text input that is used to get a year-only value for a date field.

datepicker

A datepicker input with calendar opened

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

Special parameters:

date format=	sets a custom date format, used only for the input field. An example would be DD-MM-YYYY.
first date=	sets the first date the user is allowed to select.
last date=	sets the last date the user is allowed to select.

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 yyyy/mm/dd hh:mm. Its set of parameters includes all of those "datepicker" as well as the following:

mintime=	the minimum allowed time
maxtime=	the maximum allowed time
interval=	the interval (in minutes) between options shown to the user

rating

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

Special parameters:

star width	specifies the width (and height) of each star. Default is 24px.
num stars	specifies the number of stars to display. Default is 5.
allow half stars	allow users to select half a star. Default is false; set to 'yes' (or any other value) to make true.

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 Google Maps API key, then set it in LocalSettings.php via the $wgPageFormsGoogleMapsKey setting, for the input to display.

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

height=	sets the height, in pixels, of the map.
width=	sets the width, in pixels, of the map. Both height and width are needed together to set the dimension.
starting bounds=	takes in a pair of coordinates to set the bounds of the map displayed; this parameter only applies if the input does not have a value. (Example value for this parameter: "-20,-15;50,55".)

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

image=

sets the specified image (which must be an image that was uploaded to the wiki) as the background for the map, instead of a geographical map.

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:

$wgPageFormsDisableOutsideServices = true;

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:

Cargo data type	SMW data type	Default input type	Default size	Other allowed input types
Page	Page	combobox	35	text, dropdown, textarea, tree
String	N/A	text	35	combobox, textarea
Text	Text, Code	textarea	5 x 30	text
URL	URL	text	100	textarea
Integer, Float	Number	text	10	textarea
Date, Start date, End date	Date	date		datetime, year, datepicker
Datetime, Start datetime, End datetime	N/A	datetime		datetimepicker, date, year
Boolean	Boolean	checkbox		dropdown, radiobutton
Coordinates	Geographic coordinate	openlayers		googlemaps, leaflet
Rating	N/A	rating
Enumeration (any Cargo field with a list of allowed values)	Enumeration (any SMW property with defined "allowed values")	dropdown		radiobutton
Hierarchy (any Cargo field with a hierarchical set of allowed values)	N/A	tree

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

Cargo data type	SMW date type	Default input type	Default size	Other allowed input types
Page	Page	tokens	100	text, textarea, tree, checkboxes
String	Text	text	100	textarea, tokens
Enumeration	Enumeration	checkboxes		listbox
Hierarchy	N/A	tree

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 "<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 <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 here.

Note that the upload window will not work if $wgBreakFrames is set to true 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:

$wgPageFormsSimpleUpload = true;

The special parameters for uploadable fields are:

• uploadable - Specifies that this is an uploadable field.
• image preview - Specifies that a thumbnail of the uploaded image should be placed under the field in the form.
• default filename=filename - Specifies the default filename for files uploaded with this field.