Extension:Semantic Forms/Defining forms

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

Semantic 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 Semantic Forms, you should not try creating form-definition pages from scratch, but rather use one of Semantic 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[edit | edit source]

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

'info' tag[edit | edit source]

The info 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:

  • partial form - Indicates that this form is a partial form; see "Partial forms", below.
  • create title=title - Sets the title for the 'FormEdit' page, if the form is being used to create a new page
  • edit title=title - Sets the title for the 'FormEdit' page, if the form is being used to edit an existing page
  • query title=title - Sets the title for the 'RunQuery' page
  • page name=formula - Sets a formula for automatic setting of the name of the page being added; see "Linking to forms#The one-step process".
  • query form at top - Places the form at the top, instead of the bottom, for the 'RunQuery' page
  • onlyinclude free text - Indicates that the free text in the page generated by the form should be placed within an "<onlyinclude>" tag, so that pages created by the form can be transcluded in other pages without affecting those other pages' semantic properties.

'for template' tag[edit | edit source]

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

  • label=label text - Specifies a label to be placed in a square around the entire set of this template's fields in the form. This is especially useful if the template can have multiple instances.
  • multiple - Specifies that the user can change the number of instances of this template in the form, allowing multiple (or zero) occurrences; see "Multiple-instance templates", below.
  • minimum instances=number - For multiple-instance templates, sets the minimum number of allowed instances.
  • maximum instances=number - For multiple-instance templates, sets the maximum number of allowed instances.
  • add button text=text - For multiple-instance templates, sets the text in the "Add another" button.
  • strict - Specifies that only fields in the form that correspond to fields used by the template should get turned into form elements.
  • embed in field=template name[field name] - Specifies that the call(s) to this template within the generated pages will get embedded within a field of another template (i.e., "{{main template|some field={{embedded template|...its fields...}} ... }}"). It is used in conjunction with the "holds template" parameter for the 'field' tag (see below). Note that the template to be embedded must appear after the template in which it will be embedded.

'end template' tag[edit | edit source]

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

'field' tag[edit | edit source]

The field tag specifies a field to be placed in a form, corresponding to a template field. The name immediately following the field 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:

  • input type=input type - Specifies the type of input this field will have in the form. If a field corresponds to an SMW property or Cargo field, the form will usually have the correct input type by default; otherwise the default is text. If the corresponding SMW property, or Cargo field, cannot be automatically determined, you can use the parameter "property", or the parameters "cargo table" and "cargo field", to manually specify it (see below). The allowed set of input types is different for every semantic property type; see below for the full list of options.
  • hidden - Specifies that this field will be hidden in the form: used to preserve values in edited pages.
  • mandatory - Specifies that this field must be filled in by the user. Note: mandatory should not be used in conjunction with hidden. Use of both in any field will cause the mandatory check on any field to fail when the form is saved.
  • restricted - Specifies that this field will be editable only by admins/sysops and disabled for all other users. This parameter can also be called as "restricted=group name", which restricts editing of the field to the specified user group.
  • default=default value - Specifies a default value for this field. For date-related fields, default=now will set the value to the current date and possibly time. For text fields, default=current user will set the value to the username of the user adding this page. For the checkbox input type, default=yes will check the checkbox by default. (The "checkboxes" input type, on the other hand, like the "listbox" type, requires specifying the actual values, like default=Value A, Value C.) You can also include templates, parser functions, and magic words within the "default=" value.
  • class=class name - Specifies a CSS class that the input for this field should have.
  • property=property name - Specifies that the field corresponds to a certain Semantic MediaWiki property, and should thus get the corresponding input type, autocompletion, etc.
  • cargo table=table name and cargo field=field name - Collectively used to specify that this form field corresponds to a certain Cargo field, and should thus get the corresponding input type, autocompletion, etc.
  • list - Specifies that this field contains a list of values.
  • delimiter=delimiter - Specifies the delimiter character or string this field should use, if it represents a list of values; the default is ",".
  • holds template - Specifies that this field is meant to hold a multiple-instance template, and does not have its own form input. It is used in conjunction with the "embed in field" parameter for the 'for template' tag (see above).
  • unique - Specifies that the value entered for this field must be unique, i.e. must not be the same as any value for the SMW property (if SMW is being used) or Cargo field (if Cargo is being used) corresponding to this template field.
  • unique for category=category name - Specifies that the value entered for this field must not be the same as the name of any page in the given category.
  • unique for namespace=namespace name - Specifies that the value entered for this field must not be the same as the name of any page in the given namespace.
  • unique for concept=concept name - Specifies that the value entered for this field must not be the same as the name of any page in the given SMW "concept".

Parameters that can only be applied to fields that hold a list of uploaded files are:

  • uploadable - Specifies that a link should be placed next to this field, that opens a popup window to let the user upload a file; see "Uploading files", below.
  • 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.
Semantic Forms support for the WikiEditor extension (in connection with the Header Tabs extension)

Parameters that can only be applied to fields of type 'textarea' are:

  • rows=num rows - Specifies the number of rows.
  • cols=num cols - Specifies the number of columns.
  • 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.

Parameters that can only be applied to inputs that have a set of pre-defined values, either that the user must select from (like the "dropdown" input) or that are suggested (the "autocomplete" and "combobox" inputs):

  • 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 the Semantic MediaWiki property. 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".
  • values from url=URL identifier - Used only for autocompletion. Specifies that autocompletion should be based on the values retrieved from an outside URL; see Autocompleting on outside values for how to do this.
  • values from external data=variable name - Used for autocompletion. You need to have the External Data extension installed to be able to use this parameter. It specifies that autocompletion should be based on the data retrieved from an outside source. A large number of data sources are supported, including web APIs, regular wiki pages, files on the local server, databases and LDAP directories. See Autocompletion using External Data.
  • remote autocompletion - Specifies that autocompletion values should be retrieved dynamically from the server, instead of directly from a list of values hidden in the page's HTML. This parameter is optional; by default, remote autocompletion takes effect automatically when the number of autocompletion values is greater than the global variable $sfgMaxLocalAutocompleteValues. The default value for this variable is 100, but you can override it by adding the following line in LocalSettings.php:
 $sfgMaxLocalAutocompleteValues = <Value>;
  • existing values only - Set a combo box or tokens to only allow the autocomplete values, and not any arbitrary values, thus having it function even more like a dropdown.
  • show on select=value 1=>element ID 1;value 2=>element ID 2;value 3=>element ID 3;etc. - Can be used for inputs of type 'checkbox', 'checkboxes', 'radiobutton', 'dropdown' and 'listbox' to specify that one or more tags with a certain ID 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. 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.
  • values dependent on=template name[field name] - Can be used for inputs of type 'combobox', 'text with autocomplete', 'textarea with autocomplete' and 'tokens'. 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. For example, 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]}}}.
  • 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=.

Other parameters that can be added for certain input types:

  • size=size - Used for text entries, combobox, tokens and listbox. For the first three it specifies the width, in characters; for a listbox it specifies the height.
  • placeholder=placeholder text - Used for the text, textarea, combobox and tokens fields. Specifies help text that is displayed in the input until the user clicks on it.
  • maxlength=maximum length - Used for text and textarea fields. Specifies the maximum allowed length of the input.
  • include timezone - Used for inputs of type 'datetime'; specifies that a time zone field should be included.
  • max values= - Used for input type tokens; specifies the maximum number of values that can be entered in a field that holds multiple values.

'section' tag[edit | edit source]

The section 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:

  • level=level – Specifies the "level" of the section heading; can be 1-6, corresponding to '=' through '======' in wiki markup. See "Sections" for more information.

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.

  • mandatory
  • restricted
  • hidden
  • class
  • rows
  • cols
  • autogrow

'standard input' tag[edit | edit source]

The standard input 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 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:

  • label=label name - Specifies the text associated with this input on the form.
  • class=label name - Specifies the CSS class for this input.
  • style=label name - Specifies the CSS style for this input.

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

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 (includes hours, minutes, seconds and AM/PM indicator), year (year only), 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.

Autocompletion[edit | edit source]

One of the big strengths of Semantic Forms is that it supports autocompletion - you can enable a field to show a dropdown list of possible completions when the user starts typing. Semantic Forms' autocompletion is enabled by two JavaScript libraries: Select2 which is used by "combobox" and "tokens" and jQuery UI Javascript library's Autocomplete plugin which is used by "text with autocomplete" and "textarea with autocomplete".

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 fields representing an SMW property or Cargo field of type "String" or "Text", there is no default autocompletion, but you can achieve this same effect simply by adding "input type=combobox" or "input type=tokens" to the field's definition, depending on whether the field holds one or a list of values. (You can also have "input type=text with autocomplete" or "input type=textarea with autocomplete", although these input types are slightly deprecated.) You can also autocomplete on other sets of values:

  • to autocomplete on all the values of a specific SMW property, add "values from property=property-name" to the field definition
  • to autocomplete on the names of all pages in a category, add "values from category=category-name"
  • to autocomplete on the names of all pages in a namespace (like "File"), add "values from namespace=namespace-name" (if you want to autocomplete on the main namespace, use "values from namespace=Main", or "values from namespace=").
  • to autocomplete on the names of all pages in an SMW "concept", add "values from concept=concept-name"
  • you can also autocomplete based on values outside the wiki, contained in web pages, databases, files, etc. See Autocompleting on outside values for the various ways to do this.

If a field is specified to hold multiple values (see below), 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).

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; this number is defined by the variable $sfgMaxAutocompleteValues, which by default is set to 1000. If you have more than this number of possible values for a field, you may want to use remote autocompletion 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 always returns a comprehensive set of results. You can enable this by adding the "remote autocompletion" parameter to the field's definition.

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.

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

Combobox input[edit | edit source]

Combobox input

For any input that holds a single value, you can set the input to be a combo box by setting input type=combobox in the field definition. This input 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.

You can also set the combo box to only allow the autocomplete values, and not any arbitrary values, thus having it function even more like a dropdown, by adding the additional parameter existing values only to the field tag.

Tokens input[edit | edit source]

Tokens input

The "tokens" input type is the default for a field that holds multiple values of type "Page". You can manually set to this input type by setting input type=tokens in the field tag. It "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.

You can set a field that has the "tokens" input type to hold no more than a certain number of values, by specifying a value for the parameter max values= in the field definition. It also supports the existing values only parameter for disallowing arbitrary values in the field.

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.

Displaying additional data in field autocompletion[edit | edit source]

Icon images associated with autocomplete values

As of version 2.8, SF also supports displaying thumbnail images and description text associated with autocomplete values. In order to do this you need to use values from external data= parameter in the field definition. See Autocompletion using External Data.

Caching[edit | edit source]

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:

$sfgCacheAutocompleteValues = true;
$sfgAutocompleteCacheTimeout = 60 * 60 * 24; // 1 day (in seconds)

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

Multiple values for the same field[edit | edit source]

Semantic 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 "Semantic 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 {{{field}}} 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 field with multiple values is "tokens".

Multiple-instance templates[edit | edit source]

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 "add button text=" parameter. For instance, to change the button to read "Add another occupation" for a template called "Occupation", you could have "{{{for template|Occupation|multiple|add button text=Add another occupation}}}".

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

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 pass in a blank as the first parameter, so that each subobject gets an automatically-assigned name.)

There is a small difference between regular and embedded multiple-instance templates.

  • In the case of regular templates, every new instance of a template starts on a new line after the closing }}.
  • If the template is embedded in another template (see "embed in field" and "holds template"), every new instance directly follows the closing }}. You cannot embed multiple-instance templates inside other (regular or embedded) multiple-instance templates.

An example of using multiple-instance templates with "holds template" and "embed in field" can be found here.

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 "tree" input[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 parameter:

  • 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

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.

The free text input[edit | edit source]

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

  • rows
  • cols
  • hidden
  • restricted
  • default
  • class
  • autogrow
  • editor

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

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

Defining the bottom of the form[edit | edit source]

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 "{{{standard input|save|label=Save this page}}}", which would place the button where it was defined, with the text on the button reading "Save this page". If no standard input 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[edit | edit source]

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

{{{info|add title=Add an opinion item|edit title=Edit an opinion item}}}
<div id="wikiPreview" style="display: none; padding-bottom: 25px; margin-bottom: 25px; border-bottom: 1px solid #AAAAAA;"></div>
{{{for template|Item}}}
{| class="formtable"
! Author:
| {{{field|author|mandatory}}}
! Source:
| {{{field|source|mandatory}}}
! Date:
| {{{field|date}}}
! URL:
| {{{field|url}}}
! Quote:
| {{{field|quote|input type=textarea}}}
{{{end template}}}

{{{for template|Opinion|label=Opinions for this item|multiple}}}
'''Topic:''' {{{field|1}}}

'''Position:''' {{{field|2|size=55}}}

'''Stance:''' {{{field|3|size=10}}}
{{{end template}}}

{{{for template|Reference|label=Previous opinion items this item refers to|multiple}}}
'''Item name:''' {{{field|1|values from category=Items}}}
{{{end template}}}

'''Free text:'''

{{{standard input|free text}}}

{{{standard input|summary}}}

{{{standard input|minor edit}}} {{{standard input|watch}}}

{{{standard input|save}}} {{{standard input|preview}}} {{{standard input|changes}}} {{{standard input|cancel}}}

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

Form-definition pages generated by Semantic 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. #forminput is not actually a part of the form-definition syntax, though. For information on how to modify the #forminput call, see Linking to forms#The two-step process.

Other topics[edit | edit source]

Turning forms into tabbed sections[edit | edit source]

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 "<headertabs/>" 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.

Partial forms[edit | edit source]

You can specify a form to be a partial form by adding the parameter "partial form" to its {{{info}}} tag. This will make the form cover only the single or multiple templates that it contains, and not modify any part of the page before or after these templates.

A partial form is not recommended as a default form for a category or namespace, but rather as a tool to modify parts of pages after they have already been created. You can see an example of a partial form here, and you can see it in action here, by clicking on the link reading "Add or change this opinion item's references".

Reusing form elements[edit | edit source]

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 '&#123;', '|' with '&#124;' and '}' with '&#125;'. Or just use <nowiki> around them.

Caching form definitions[edit | edit source]

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 "{{{field}}}". 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:

$sfgCacheFormDefinitions = true;

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

$sfgFormCacheType = CACHE_ANYTHING;

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

Tooltips[edit | edit source]

You can add tooltips to your form in two different ways:

  • If you have the Semantic MediaWiki extension installed, you can use the #info parser function defined by Semantic MediaWiki, e.g., {{#info:tooltip text}}. (This parser function is not to be confused with Semantic Form's "{{{info}}}" tag.) See Help:Adding tooltips for more help.
  • Use the #tip-info parser function, defined by the SimpleTooltip extension.