Extension:Semantic Forms/Input types

From MediaWiki.org
Jump to: navigation, search
Semantic Forms - navigation (viewTemplate:Semantic Forms navigation)
Basics Main pageExtension:Semantic Forms (talk) · Download and installationExtension:Semantic Forms/Download and installation · Quick start guideExtension:Semantic Forms/Quick start guide · HostingExtension:Semantic Forms/Hosting · Special pagesExtension:Semantic Forms/Special pages
Using Semantic Forms SF and templatesExtension:Semantic Forms/Semantic Forms and templates · Defining formsExtension:Semantic Forms/Defining forms (Input typesExtension:Semantic Forms/Input types) · The "Edit with form" tabExtension:Semantic Forms/The "edit with form" tab · Linking to formsExtension:Semantic Forms/Linking to forms · Creating query formsExtension:Semantic Forms/Creating query forms
Resources for help Common problemsExtension:Semantic Forms/Common problems · Known bugs and planned featuresExtension:Semantic Forms/Known bugs and planned features · Getting supportExtension:Semantic Forms/Getting support · Developers' documentationExtension:Semantic Forms/Developers' documentation · TestingExtension:Semantic Forms/Testing
About Semantic Forms Authors and creditsExtension:Semantic Forms/Authors and credits · Version historyExtension:Semantic Forms/Version history · Sites that use Semantic FormsExtension:Semantic Forms/Sites that use Semantic Forms · Related extensionsExtension:Semantic Forms/Related extensions

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

The input types[edit | edit source]

text[edit | edit source]

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

Special parameters:

  • size=size - Specifies the width of the input, in characters.
  • maxlength=maximum length - Specifies the maximum allowed length of the input.
  • placeholder=placeholder text - Specifies help text that is displayed in the input until the user clicks on it.

textarea[edit | edit source]

Corresponds to the HTML <textarea> tag.

Semantic Forms support for the WikiEditor extension (in connection with the Header Tabs extension)

Special parameters:

  • rows=num rows - Specifies the number of rows.
  • cols=num cols - Specifies the number of columns.
  • maxlength=maximum length - Specifies the maximum allowed length of the input.
  • autogrow - Sets the textarea to "auto-grow" its height to match that of its contents, so that a scrollbar won't be needed.
  • editor=editor type - Adds a Javascript-based editor to the textarea to make editing its contents more user-friendly. Currently only one value is allowed: "wikieditor", for the WikiEditor extension (which must be installed for this to work). Unfortunately only one input within the form can have WikiEditor associated with it, due to a limitation in the WikiEditor extension. If you want to add any additional custom toolbars to WikiEditor, you will need to add them in the Javascript to ('#free_text').wikiEditor, just as they exist for ('#wpTextbox1').wikiEditor.
  • placeholder=placeholder text - Specifies help text that is displayed in the input until the user clicks on it.

text with autocomplete, textarea with autocomplete[edit | edit source]

These two inputs are displayed in the same way as the "text" and "textarea" 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 mapppings" and "Autocompletion" sections below for how to customize the autocompletion.

combobox[edit | edit source]

Combobox input

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 Select2 JavaScript library.

Special parameters:

  • size=size - Specifies the width of the input, in characters.
  • existing values only - Disallows arbitrary values in the field.
  • placeholder=placeholder text - Specifies help text that is displayed in the input until the user clicks on it.

tokens[edit | edit source]

Tokens input

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 Select2 JavaScript library.

Special parameters:

  • size=size - Specifies the width of the input, in characters.
  • max values=max values - Specifies the maximum number of allowed values.
  • existing values only - Disallows arbitrary values in the field.
  • placeholder=placeholder text - Specifies help text that is displayed in the input until the user clicks on it.

radiobutton[edit | edit source]

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[edit | edit source]

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[edit | edit source]

The "checkboxes" input displays checkboxes to let the user choose any number of values.

listbox[edit | edit source]

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.

tree[edit | edit source]

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. This input type replaces two previous input types that became deprecated in version 2.7: "category" and "categories". These input types can both still be used, and are just synonyms for "tree".

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 three that are shown at the beginning. Default is 10.

You can see a sample form that uses this input type here.

For category names[edit | edit source]

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[edit | edit source]

A single checkbox, used for boolean values.

date[edit | edit source]

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

datetime[edit | edit source]

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[edit | edit source]

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

openlayers, googlemaps[edit | edit source]

The "openlayers" and "googlemaps" input types let you display a map to get a coordinate value, using the Google Maps or OpenLayers services, respectively. These input types are only enabled if the Semantic Maps extension is not installed, since that extension provides its own input types with these names.

Allowed input types for data types[edit | edit source]

Each defined data type, when using either Semantic MediaWiki or Cargo, 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:

SMW data type Cargo data type Default input type Default size Other allowed input types
Page Page text with autocomplete 35 text, combobox, dropdown, textarea, textarea with autocomplete, tree
String (SMW < 1.9) N/A text 35 text with autocomplete, combobox, textarea, textarea with autocomplete
Text, String (SMW >= 1.9) Text textarea 5 x 30 text
Code N/A textarea 5 x 30 text
URL N/A text 100 textarea
Number Integer, Float text 10 textarea
Date Date date datetime, year, datepicker
N/A Datetime datetime date, year, datepicker
Enumeration (any SMW property with defined "allowed values") Enumeration (any Cargo field with defined allowed values) dropdown radiobutton
Boolean Boolean checkbox dropdown, radiobutton
Geographic coordinate Coordinates openlayers googlemaps

And here are the default and other allowed input types for delimited lists of a certain data type, enabled by the use of the "#arraymap" function:

SMW data type Cargo date type Default input type Default size Other allowed input types
Page Page tokens 100 text, textarea, text with autocomplete, textarea with autocomplete, tree, checkboxes
String Text text 100 textarea, textarea with autocomplete, text with autocomplete
Enumeration Enumeration checkboxes listbox

With the input type ' regexp' you can fine-tune what values are allowed and what is blocked in your input fields. In addition, several other extensions define additional form input types: most notably, Semantic Forms Inputs defines the additional input types 'timepicker', 'datetimepicker', 'menuselect' and 'two listboxes', while Semantic Maps defines its own versions of the 'googlemaps' and 'openlayers' input types.

Setting values and mappings[edit | edit source]

For inputs that have a pre-determined set of values, whether they are hardcoded (like the "dropdown" input) or suggested (like "combobox"), the values must be defined somewhere. If you are using SMW or Cargo, these values may already be defined outside the form. However, you can always override them within the form - or set them for a field that otherwise has no values defined for it. The following parameters can be used in the "field" tag:

  • values=possible values - Specifies a set of either possible values or autocompletion values (depending on the input type) that this field can have, overriding whatever set of values may have been set from Semantic MediaWiki or Cargo. This set of values is separated by commas by default, but the delimiter can be modified using the delimiter= parameter.
  • values from property=property name - Similar to values=, but gets its values from the the set of all values that a certain SMW property points to. Note that there is no Cargo equivalent for this parameter; in the case of Cargo, the set of all values for the specified Cargo table/field are used when the cargo table= and cargo field= parameters are provided.
  • values from category=category name - Similar to values=, but gets its values from the names of all pages belonging to a specific category.
  • values from namespace=namespace name - Similar to values=, but gets its values from the names of all pages belonging to a specific namespace. (To get values from the main namespace, use "Main" for the namespace name, or just leave it blank.)
  • values from concept=concept name - Similar to values=, but gets its values from the names of all pages belonging to a specific SMW "concept".

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

You can also set "mappings", if you want the set of values displayed to the user to be different from the set of values that actually show up in the page's wikitext. The following parameters enable such mappings:

  • 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=.

Autocompletion[edit | edit source]

Four of the input types ("tokens", "combobox", "text with autocomplete" and "textarea with autocomplete") 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 $sfgMaxAutocompleteValues in LocalSettings.php.

Disabling[edit | edit source]

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[edit | edit source]

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:

$sfgMaxLocalAutocompleteValues = 200;

You can also force remote autocompletion in a field by adding the following parameter to the field's definition:

  • remote autocompletion

Matching on every character[edit | edit source]

By default, Semantic 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:

$sfgAutocompleteOnAllChars = 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[edit | edit source]

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[edit | edit source]

There are two ways to have a field autocomplete using data from outside the wiki - one is from a URL that takes in a substring and returns data in JSON format similar to JSON returned by MediaWiki API and the other is to use External Data extension to fetch data from some external/internal source.

From an outside URL[edit | edit source]

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 autocompletion values; the values should be in JSON format, and look like the JSON returned by the MediaWiki API (see here for an example). This also makes it easy to autocomplete on the values from another wiki.

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

3. Add a line to LocalSettings.php that looks like this:

$sfgAutocompletionURLs['URL-identifier-string'] = 'URL';

The URL in this line should look like a call to that web service, but with the substring replaced by the string "<substr>".

4. Add the parameter "values from url=URL-identifier-string" to the relevant field in the form definition.

Using the External Data extension[edit | edit source]

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.) Then the field tag needs to contain this parameter:

  • values from external data=variable name

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[edit | edit source]

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

The syntax for this parameter is:

  • values dependent on=template name[field name]

Is that confusing? If so, 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]}}}.

Uploading files[edit | edit source]

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 file name will be appended to whatever was there before; otherwise, the file name will overwrite whatever the field contained before.

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.

Using a combination of the "uploadable" feature and the one-step process, you can create a form for users to upload a file and add semantic data to its wiki page at the same time - see "Using Semantic Forms for file pages and uploads".

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.

"show on select"[edit | edit source]

For inputs of type 'checkbox', 'checkboxes', 'radiobutton', 'dropdown' and 'listbox', the parameter show on select= can be used to specify that one or more elements on the page should only be displayed to the user if a certain value (or values) is selected within that input. See here for an example of this feature in use (note what happens when you select different values for the "Publication type" dropdown), and see here for how it was implemented in the form.

The syntax for this parameter is:

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

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.