Please remember to make use of the Manual of Style and Code of Conduct during your stay.

 Actions

Help

Extension - Page Forms

From Dragon Mania Legends (DML) Wiki

This page is a help page for wiki Dragon Mania Legends Wiki:Staff who use the Page Forms extension. This guide is incomplete, and currently a draft.

Introduction[edit]

Note: This documentation was adapted from: Edutech Wiki.

Page Forms, formerly called Semantic Forms is an MediaWiki (MW) extension to create forms-based input based on templates. It can work together with the Semantic MediaWiki extension or mw:Extension:Cargo allowing to create forms that bundle "semantic" properties and values, or it can work on its own. Page Forms also help users to create forms and pages with preloaded text, or perform queries in combination with other exensions like DynamicPageList3.

Page Forms can be used on its own (Forms) with Templates and Categories. See also:

According to Semantic MediaWiki on SEQansers, in the Page Form model, a MW Category is equivalent to a database Table and a MW Page in that category is equivalent to a Row in that Table. Finally, SMW Properties are the columns of the Table. i.e. each Page in the Category should carry the same set of Properties. This is all achieved by the use of a Template with an associated Category. For convenience each 'Table' (Template + Category) has an associated Form. See: Comparison Cargo vs Semantic Mediawiki & Wikibase See also:

TBD - information will be added for Cargo as it is determined. In the meantime see: Cargo and SMW Compared See also:

Principles[edit]

According to Semantic MediaWiki on SEQansers, in the Page Form model, a MW Category is equivalent to a database Table and a MW Page in that category is equivalent to a Row in that Table. Finally, SMW Properties are the columns of the Table. i.e. each Page in the Category should carry the same set of Properties. This is all achieved by the use of a Template with an associated Category. For convenience each 'Table' (Template + Category) has an associated Form. These items can also be bundled together automatically without Semantic Mediawiki, by creating a 'Class' through the use of Special:CreateClass.

For a simple Page Form, one should define (a) properties (or parameters, including data type definitions), (b) a template definition (shortcut to set/pull together a set of properties and that displays property/values to users) and (c) a form that will provide the user interface for creating or editing a template (b). A form can embed other forms and populate more than one template. Again, users should ensure items in the same category carry the same standardized properties/parameters for data querying and display purposes to be semantic.

Manual Work-flow for creating a page that includes a "Page Form"[edit]

The easiest way of creating properties, templates and forms from scratch is using the Special:CreateClass page. It's an all-in-one solution using a form that allows to create and define the template (property names), the category for which completed and saved forms will be auto-categorized under (if not using a query), and the form (and associated form field names, property types, and allowed values). It also includes a checkbox for creating code for multiple value input for forms. When creating a class, all 3 items are created after the class creation form is completed (it creates the form, template, category) and it associates them all together automatically, so they don't have to be associated manually. Essentially creating a class creates the bundle for you, and then each can be separately edited.

Note: Administrators of MediaWiki should make sure that the wiki has enough Shell Memory shell memory, since this CreateClass action will use the Wiki's job queue.

Otherwise these items must be created manually.

(1) Define properties

Recall that the concept of "class" is defined as bundle of properties. In Semantic Mediawiki, properties are used that will represent the data structure of a "class". Remember that each Page in the Category should carry the same set of Properties, and consider how the data may need to be queried or displayed in the future.

(2) Create content/display templates

Think of a template as a property/value list or as a function call that will define the values of a set of properties. The end user then can define property/value pairs either through using the form (edit with form) or through hand-coding template parameters (edit page). A template defines (1) a shortcut for defining properties and values and (2) also defines the visual layout of an instance (of specific form contents) to the reader. In other words, the visual output of a page plus the data-structure of its class are defined by the template. In the context of "Page Forms" a template should be associated with at least one form for input (see the next item). However, templates are a generic mediawiki feature and also could be used without forms.

(3) Create a form definition page

Forms define the logical structure of the input form, i.e. in particular how it is made up from user-input fields plus optional "free text input". It also defines the user input interface, i.e. what you see when you click on edit with form on top of the page. The form definition is tied to one or more templates. Page Forms provides an entire syntax for defining forms, that makes use of named parameters {{{element1}}} passed to templates. Form pages show only the form view when its page is viewed, however editing the form page shows the syntax used, and their display as a form is created when they are placed in the "Form:" namespace. Such pages are technically "form-definition pages", to distinguish them from the actual corresponding forms that users see. See: mw:Extension:Page Forms/Defining forms Defining forms.

(4) Create categories

  • Typically, each template is associated with a MediaWiki category that represents the "class" from a browsing perspective.

(5) Make forms work with pages

(6) Add data using forms

  • You could insert a template inside an existing wiki page or create a new page. Using a template will create an instance, i.e. will allow end-user to edit contents using the form.
  • Use Special:FormStart

Usually, the same name is used for the (a) category page, (a) the form-definition page and (b) the content/display template. All of these sit in different namespaces. Below are 2 examples that illustrate form creation and use explain some of these "devices" in more detail.

Automatic Simple Content/Display Template[edit]

The template definition page for defining a related set of properties/values can be created through the Special:CreateTemplate page or using the all-in-one solution offered in the Special:CreateClass to create the template, form and category all at once and associate them together. This is what is the Create a Class feature generally outputs when used:

Note: There are 4 formats to choose from for template output, which can be changed or edited just like any other template:

  • Table
  • Side Infobox
  • Plain Text
  • Sections

<noinclude>
This is the "DummyExample" template.
It should be called in the following format:
<!-- pre -->
{{DummyExample
|param1=
|param2=
|param3=
}}
<!-- /pre -->
Edit the page to see the template text.
</noinclude><includeonly>{| class="wikitable"
! param1 (single value set)
| {{{param1|}}}
|-
! param2 (List of values, comma separated)
| {{#arraymap:{{{param2|}}}|,|x|[[x]]}}
|-
! param3 (single value set)
| {{{param3|}}}
|}
[[Category:DummyExample]]
</includeonly>

<noinclude>
This is the "InfoboxDummyExample" template.
It should be called in the following format:
<!-- pre -->
{{InfoboxDummyExample
|Single allowed value=
|Multiple allowed values=
|List of values, comma separated=
}}
<!--/pre -->
Edit the page to see the template text.
</noinclude><includeonly>{| style="width: 30em; font-size: 90%; border: 1px solid #aaaaaa; background-color: #f9f9f9; color: black; margin-bottom: 0.5em; margin-left: 1em; padding: 0.2em; float: right; clear: right; text-align:left;"
! style="text-align: center; background-color:#ccccff;" colspan="2" |<span style="font-size: larger;">{{PAGENAME}}</span>
|-
! Single allowed value
| {{{Single allowed value|}}}
|-
! Multiple allowed values
| {{{Multiple allowed values|}}}
|-
! List of values, comma separated
| {{#arraymap:{{{List of values, comma separated|}}}|,|x|[[x]]}}
|}
[[Category:InfoboxDummyExample]]
</includeonly>

<noinclude>
This is the "PlainDummyExample" template.
It should be called in the following format:
<!-- pre -->
{{PlainDummyExample
|singleallowedvalue=
|multipleallowedvalues=
|listofvalues=
}}
<!-- /pre -->
Edit the page to see the template text.
</noinclude><includeonly>
'''singleallowedvalue:''' {{{singleallowedvalue|}}}

'''multipleallowedvalues:''' {{{multipleallowedvalues|}}}

'''listofvalues:''' {{#arraymap:{{{listofvalues|}}}|,|x|[[x]]}}

[[Category:PlainDummyExample]]
</includeonly>

<noinclude>
This is the "SectionDummyExample" template.
It should be called in the following format:
<!-- pre -->
{{SectionDummyExample
|singleallowedvalue=
|multipleallowedvalues=
|listofvalues=
}}
<!-- /pre -->
Edit the page to see the template text.
</noinclude><includeonly>
==singleallowedvalue==
{{{singleallowedvalue|}}}

==multipleallowedvalues==
{{{multipleallowedvalues|}}}

==listofvalues==
{{#arraymap:{{{listofvalues|}}}|,|x|[[x]]}}

[[Category:SectionDummyExample]]
</includeonly>


Basically speaking, the template above defines shortcuts. It allows you to enter structured information in a very concise way. The form definition page will use such a template, i.e. call it with the values that the user will fill in. The template itself doesn't know about the form. In the case of Semantic MediaWiki, f you think of a template as a macro function, the value of a template parameter becomes the value of a semantic MediaWiki property.

As we mentioned before, templates are a standard feature of Mediawikis. Technically speaking, templates are standard wiki pages whose content is designed to be transcluded (embedded) inside other pages.

  • A template is defined by creating a page in the Template namespace, e.g. Template:TemplateName
  • You can insert all sorts of wiki and html code and contents in templates, e.g. in this wiki we use templates to create simple banners. Such a simple static template is called using double curly braces like this: {{template_name}}.
  • Elements in triple curly braces {{{....}}} refer to named parameters. There are three sorts of parameters, anonymous, numbered and named ones. With Page Forms, you should used named parameters like in the example shown above.

Read more about templates in Templates chapter of the Mediawiki manual.

Example 1 - Software information below presents a detailed case of (fairly) simple form and template use.

Defining simple data input forms[edit]

Input forms - what you see when you "edit with form" - are defined by "form-definition pages". The latter define the data input interface with fields that contain information. This information is then used as parameters for one or more templates. These field values usually will become values of semantic properties.

The markup language uses the MediaWiki templates syntax. 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.

Forms must be created within the Form: namespace. As we explained above, initial forms can be either created through the all-in-one Special:CreateClass form or by using the Special:CreateForm page. A very minimal input form definition usually has three parts as detailed below:

  1. A line that says that some form:form_name page, is a form definition page
  2. Definition of fields and input types for at least one template
  3. Definition of free text functionality

Notice the placement of:

  • {{#forminput:form=DummyExample}}
  • {{{for template|DummyExample}}}
  • {{{end template}}}

Example:

<noinclude>
This is the "DummyExample" form.
To create a page with this form, enter the page name below;
if a page with that name already exists, you will be sent to a form to edit that page.
{{#forminput:form=DummyExample}}

</noinclude><includeonly>
<div id="wikiPreview" style="display: none; padding-bottom: 25px; margin-bottom: 25px; border-bottom: 1px solid #AAAAAA;"></div>
{{{for template|DummyExample}}}
{| class="formtable"
! param1: 
| {{{field|param1}}}
|-
! param2: 
| {{{field|param2}}}
|-
! param3: 
| {{{field|param3}}}
|}
{{{end template}}}
'''Free text:'''
{{{standard input|free text|rows=10}}}
{{{standard input|summary}}}
{{{standard input|minor edit}}} {{{standard input|watch}}}
{{{standard input|save}}} {{{standard input|preview}}} {{{standard input|changes}}} {{{standard input|cancel}}}
</includeonly>


Define the input form[edit]

The {{#forminput:form=DummyExample}} defines (1) the bulk of a simple form template, (2) identifies a template that will use the field values that sit between the "for" and the "end" and (3) the fields.

  • {{{for template...}}} and {{{end template}}} define start and end of the form definition for a given template.
  • Therefore, param1, param2, and param3 must match the parameter names used in the content/display template.

Define the free text functionality[edit]

In addition, one can allow the user to enter free text through the form interface (v.s. editing the page in normal wiki edit mode), make a summary and save, etc.

{{{standard input|free text}}}
{{{standard input|watch}}}
{{{standard input|save}}} 
{{{standard input|preview}}}
{{{standard input|changes}}}
{{{standard input|cancel}}}


Notice that you should call a #forminput in the noinclude section, that will help users create and find forms. It plays a single input for users to enter the name of a page; if they enter such a name and click the button, they are sent to a form to create that page - unless a page with that name already exists, in which case they are sent to a form for editing the existing page.

Getting the "edit with form" to work[edit]

There are three methods:

(1) Using a category:

In the template, make sure to assign a category to the page that is reserved for pages using this form.

{{#default_form:DummyExample}}

(2) Use a namespace:

You can assign a form to a whole namespace.

(3) Within a page:

When the category and namespace options aren't possible (e.g. when pages belong to multiple categories that have different default forms you could add a default form to single pages by inputting the same on the page itself.

 {{#default_form:DummyExample}}

Of course, you can insert this line into the template that defines the display of the form.


Read more details in the official manual Page Forms

Page Forms Parser Functions[edit]

Page forms add extra features to the MediaWiki language through parser functions/extensions. We already encountered {{#forminput:form=DummyExample}}. The other extensions allow for rich and complex forms, e.g. #arraymap is used to allow for entering multiple values in a field as we shall see later.

{{#arraymap:value|delimiter|var|formula|new_delimiter}}
{{#arraymaptemplate:value|template|delimiter|new_delimiter}}
{{#forminput:form=|size=|default value=|button text=|query string=|autocomplete on category=|autocomplete on namespace=|placeholder=|popup|query string parameters}}
{{#formlink:form=|link text=|link type=|query string=|target=|tooltip=|popup|new window|query string parameters}}
{{#queryformlink:form=|link text=|link type=|query string=|tooltip=|popup|new window|query string parameters}}
{{#autoedit:form=|target=|link text=|link type=|query string=|reload|query string parameters}}

What we could call the overall form markup language, i.e. the use of semantic mediawiki properites, use of templates for both defining templates and forms, parser extensions, etc. is quite complex.

In addition, at some point, you should learn how to use extended MediaWiki [[mw:Help:Extension:ParserFunctions Parser Functions] in order to write conditionals and to perform string manipulations.

Related Extensions[edit]

See Related Etensions

Customizing Page Forms[edit]

Important:

  • After changing the form and the template definition pages, we strongly suggest editing a form and saving it. Otherwise, the new version may not display as it should. For example, if your form instance includes a value that no longer exists it will still show since it is in the page. Change it to a new legal value and the form will show ok.

Understanding the field in form pages[edit]

By default, when for example you create forms with the Special:CreateForm page, field definitions are fairly simple. E.g. the following defines a title field + its "visual environment", i.e. a table cell plus a label.

|-
! Title:
| {{{field|title}}}

You can customize fields in several ways. Some of the simpler options are:

  • Defining input formats for given data types. For each data type - e.g. text, URL, page - input can be made in different ways.
  • Constrain the user to select from certain values
  • Making input mandatory
  • Define default values

Field parameters[edit]

Field can take eleven global parameters plus additional ones that only can be used with certain input/value types. We will partially document some parameters below. See the [[mw:Extension:Page_Forms/Defining forms|manual for details].

Syntax
{{{field|name_of_field|parameter1|parameter2|...}}} 
input type = ''input_type''
Defines the input type for the user interface. If the field corresponds to a semantic property, it will determine input type from value type of the property. Otherwise, the default input type is text. That being said, you can customize user input widgets. See the table below.
Example (including size of textarea):
{{{field|abstract|input type=textarea|rows=15|cols=90}}}
Example (including mandatory and values):
{{{field|ref type|input type=dropdown|mandatory|values=bachelor's thesis,book,book chapter,conference paper,....}}}
rows= , cols=, autogrow
These three parameters work with the textarea binput type
Example: See input type above
mandatory
Specifies that the user must fill in this field
Example see input type above
hidden
hide fields, in order to preserve values (e.g. stuff that was inserted automatically)
Example:
{{{field|creation_date|hidden}}}
default = value
Defines a default value for a field. There are some special use cases, e.g.
default=now
used with date-related fiels, will set current time/date
default=current
will set the user name
default=yes
Used with checkboxes (or radiobuttons ?), will tick
property = property name
Defines the associated semantic property. This is not necessary for simple cases where the template links a field name to a property name.
values = possible values
Allows to specify either a set of possible values or autocompletion values depending on the input type.
By default values are separated by commas, but you can change that using the delimiter = parameter.
Example:
{{{field|type|input type=dropdown|mandatory|values=book,book chapter,conference paper,...}}}
Notice: This will override default values that may have been set from the semantic property. In other words, you also can define a list of possible input values by editing a property: page.
values from thing =
Semantic Forms can retrieve values from several "things", i.e. properties, categories, concepts and namespaces:
values from property=property name
User can select from all values that a given property points to
values from category=category name
User can select from page names in the given category
Example:
{{{field|keywords|values from category=Glossary|size=60}}}
values from concept=concept name
User can select from page names in the given concept (Concepts are predefined semantic mediaqueries that return a list of pages)
values from namespace=namespace name
User can select from page names in the given namespace, e.g. from all help pages.
uploadable
Allows pictures upload and of other files
Usually (?) pictures are not associated with a semantic property. E.g in the associate definition/display template you would use something like [[Image:{{{logo|Placeholder.png}}}|{{{imagesize|135}}}px]], i.e Image: as opposed to Image::.
Example:
{{{field|logo|uploadable}}}

Form input types[edit]

The following table defines various input types you could use in form definition page. It also includes a somewhat shaky list of related parameters that will further parametrize user input. One could dinguish three types of related parameters: (a) Those that work for each input type (e.g. mandatory), (b) those who work with most input types (e.g. values=), and (c) those who are very specific (e.g. show on select). The whole table needs to be tested and completed (as of July 2013).

Recall that input types are not semantic data types. The only relation is that for each data type a default input type is defined, usually a text field or a dropdown menu for lists as we shall explain further down.

Input type = Description Related parameters Comments Example(s)
Work with most input types default=, mandatory, property=, list, delimiter=,
text An input field size=, placeholder=, maxlength=, values=, placeholder Autocompletion, which is a typical feature of semantic forms will be disabled if it was enabled by default (e.g. because the associated property is of type "page")
 {{{field| field_text| size=40| placeholder=Texte par défaut| maxlength=65|}}}
text with autocomplete An input field. same as above, plus optionally some type of values from xxxx= Autocomplete is automatic if the field represents a "page" property. Therefore, typical use of this is either for simple "string" properties in combination with values from that allows to autocomplete from other sets of values, e.g. from categories.
{{{field| field_text_autocomplete| input type=text with autocomplete| mandatory|size=80| values from property=Is developed by}}} 
textarea Text field rows=, cols=, autogrow=, wikieditor, preload, maxlength=,
{{{field|field_textarea| input type=textarea|rows=2|cols=80}}} 
textarea with autocomplete Text field Same as above plus
 ...
category User can pick a category from a tree top category=, height=, width=, depth, hideroot, use dropdown The CategoryTree extension must be installed and its configuration is mission critical
 {{{field|field_category| input type=category|top category=Contents}}}
categories User can pick categories from a tree top category=, height=, width=, depth, hideroot, use dropdown The CategoryTree extension must be installed and have the right configuration magic. If you want make the categories clickable, modify in addition the Template page, e.g. like this:
{{#arraymap:{{{field_categories}}}|,|x|[[:Category:x]] | }}
{{{field|field_categories| input type=categories| top category=Technologies| height=200|hideroot=on|depth=1}}} 
dropdown show on select=, values=
{{{field|field_dropdown| input type=dropdown|values = hot, cold, medium}}} 
combobox Works like an autocomplete field, but adds a down-arrow dropdown menu values=, existing values only= With autocomplete values it behaves more like a dropdown menu, i.e. they user can't type random strings
{{{field|field_combobox| input type=combobox| values = Coffee, Computer gaming, Loud Rock Music, Coca Cola}}} 
radiobutton values=, show on select=, By default, SF adds a "none" button to the list. If you set the field to mandatory and set a default this does not happen. In that case you probably should add some "N/A", "unknown" or "not appropriate" option.
{{{field|field_radiobutton| input type=radiobutton| values = Windows, Linux, MacOS, Android, Solaris, Other}}} 
{{{field|field_cs_subject_areas|mandatory|input type=radiobutton|values=N/A, conservation, environment, geography, history, medicine, space, wildlife, other|default=N/A}}} 
checkbox Single checkbox values=, show on select=
{{{field|field_checkbox| input type=checkbox}}} 
checkboxes Multiple checkboxes values=, show on select= field_checkboxes
datetime Date/time selection include timezone
listbox Multiple selection box show on select=, values=, size= field_listbox
datepicker Date picker widget default=, values=, date format=, first date, last date, and more field_datepicker
timepicker Time picker widget mintime=, maxtime=, interval=, and more field_timepicker
datetimepicker data + time picker like above field_datetimepicker
menuselect Hierarchical menu structure= field_menuselect
two listboxes Same functionality as listbox but easier to use. Left listbox contains possible values and selected values are shown to the right values= field_two_listboxes</syntaxhighlight>
regexp regexp=, message=, and more field_regexp </syntaxhighlight>

Allowed input types for data types[edit]

Page Forms can be used without referring to semantic properties. Of course, non-semantic contents then could not be queried. In both cases (semantic or not semantic), you can override default input types.

The table below summarizes some combinations of data and input types.

Data type Default input type Default size Other allowed input types Semantic Forms Inputs
Page text with autocomplete 35 text, combobox, dropdown, textarea, textarea with autocomplete, category menuselect, regexp
Text text 35 text with autocomplete, combobox, textarea, textarea with autocomplete menuselect, regexp
Code textarea 5 x 30 text regexp
URL text 100 textarea menuselect, regexp
Number text 10 textarea menuselect, regexp
Date date datetime (includes hours, minutes, seconds and AM/PM indicator), year (year only) datepicker
Enumeration
(any property with "Allows value") defined
dropdown radiobutton menuselect, regexp
Boolean checkbox dropdown, radiobutton

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:

Data type Default input type Default size Other allowed input types Semantic Forms Inputs
Page text with autocomplete 100 text, textarea, textarea with autocomplete, categories, checkboxes regexp
String text 100 text with autocomplete, textarea, textarea with autocomplete regexp
Enumeration checkboxes listbox two listboxes

Using multiple forms and templates[edit]

Semantic Form definition pages can include more than one template. In addition, each template can be used more than once.

Within a form definition you can use the {{{for template...}}} {{{end template}}} pattern more than once. Notice the label and multiple parameters:

{{#forminput|form_1}}

{{{for template|template_1}}}
Enter something here: {{{field|f_one}}}
{{{end template}}}

{{{for template|template_2|label=Please enter publications|multiple}}}
Enter something here: {{{field|f_publication}}}
{{{end template}}}

See examples at: Edutech Wiki


Query forms[edit]

Page Forms also can be used to create query forms. One procedure is:

  • Create a provisional template (that you later can modify). It should contain all the form fields
  • Create the form, using the Special:CreateForm page.
  • Then, use the form, e.g. through Special:RunQuery page, for example [[Special:RunQuery/Your_query_form]]
  • Finally, create a button that allows the user to enter the query form.

Live example: