Manual:Extension/Forms/Form elements and settings: Difference between revisions

Back to version history
Browse history interactively
VisualWikitext
Created page with "The '''Forms''' extension allows formatting a wiki page or a user dialog as a form. It is also used in conjunction with the Workflows extension where it provides input forms for workflow data. ==Introduction== To create a checklist as a form, for example, the following steps are necessary: # '''Create the checklist form.''' # '''Create checklist instances.''' Optionally, the styling of the form can be adjusted. As an example, we are creating..."
 
No edit summary
 
Line 1: Line 1:
The '''Forms''' extension allows formatting a wiki page or a user dialog as a form. It is also used in conjunction with the [[Reference:Workflows|Workflows]] extension where it provides input forms for workflow data.
==Introduction==
To create a checklist as a form,  for example, the following steps are necessary:
# '''Create the checklist form.'''
# '''Create checklist instances.'''
Optionally, the styling of the form can be adjusted.
As an example, we are creating the first fields for an event where food-related hygiene information has to be tracked.
[[File:checklist-event-screenshot.png|alt=Event checklist example|center|thumb|550x550px|Event checklist example]]
==Create a checklist form==
# '''Create''' the page ''Checklist Event Hygiene.form''.[[File:Extension Forms create form.png|center|thumb|400x400px|alt=Create-page dialog|Creating a new form]]This opens the Form editor.[[File:Extension Forms form editor.png|alt=elements of the form editor dialog|center|thumb|700x700px|Form editor]]
# '''Add''' a form section:
##'''Select''' the ''Section label'' element under ''Form Elements > Other'' (see screenshot annotation 2) and, holding down the left mouse button, drag it into the interactive form editor field below.
## '''Click''' anywhere in the ''Section label'' line. The field inspector opens.
## '''Enter''' the ''Name''. This is saved as a field ID in the database and should therefore not contain any special characters.
## '''Enter''' the ''Title'' for the section label. This is displayed as the visible label for the text field.[[File:Extension Forms add section header.png|alt=Section label element inspector|center|thumb|700x700px|Adding the first section header]]
# '''Create''' the form fields for the Event section. Here we add a text box as an example.
## '''Drag''' the ''Text'' element from ''Form elements > Inputs'' under the section heading.
## '''Click''' anywhere in the ''text field'' line. The field inspector opens.
## '''Enter''' the ''Name''. This is used as the database ID for this field and should therefore not contain any special characters.
## '''Enter''' the ''Label''. This is displayed as the visible label for the text field.
## '''Add''' more form elements.
# '''Click''' ''Save''. The form is now available in the main namespace as ''EventChecklistHygiene.form''.    [[File:Manual:Checklist-view.png|alt=Saved form|center|thumb|650x650px|Saved form]]<br />To continue editing the form, switch to the editing mode of the page (1).
== Form elements ==
== Form elements ==
It is possible to add the following form fields to your form:
It is possible to add the following form fields to your form:
Line 353: Line 324:
|calls a  function when the event occurs;
|calls a  function when the event occurs;
see the [[Manual:Extension/Forms/Progress bar|progress bar]] example.
see the [[Manual:Extension/Forms/Progress bar|progress bar]] example.
|}
|}{{translation}}
 
__FORCETOC__
==Create a checklist instance==
To create a checklist from the form:
 
enter a target page name.
 
# '''Fill out''' the form fields.
# '''Click''' ''Submit''.
 
The checklist is now saved in the wiki and can be edited further.
==Send email==
The form can also send an Email after being saved:
[[File:Manual:image.png|alt=Email target|center|thumb|650x650px|Email target]]
 
*'''Target type:''' Email
*'''Recipient:''' Possible recipients must have been configured on the server for security reasons. Example:
<syntaxhighlight lang="text">
$wgFormsTargetEMailRecipients = [
 
'Marketing' => "marketing@example.com",
 
'Administration' => 'WikiSysop'
 
];
</syntaxhighlight>
 
* '''Subject:''' Existing form fields can be used as variables here. The value is taken from the form.
 
* '''Content:''' As in the subject, existing form fields can also be used as variables here. The value is taken from the form.
 
 
[[mediawikiwiki:Help:Magic_words#Localisation|Localization messages]] in combination with form fields can also be used as subject or email body:<syntaxhighlight lang="text">
{{int:Mailsubject| {{{name}}}|{{{surname}}} }}
</syntaxhighlight>
 
 
==Adjust the styling==
 
===Common.css===
To style individual elements in the form, go to the styling tab in the options dialog. There, you can enter a css class name. The styling is then defined on the ''MediaWiki:Common.css'' page (admin rights are required).
 
To style the section heading:
 
#'''Open''' the styling tab in the options menu of the Event heading field.
#'''Add''' a new CSS class and enter a selector name (''CSS Classes'' field), e.g. ''frm-sectionhd''.[[File:Manual:forms-css-class-en.png|alt=Add a css class|center|thumb|650x650px|Add a css class]]
#'''Paste''' the following style declarations into the ''MediaWiki:Common.css'' page, e.g.:<syntaxhighlight lang="css">
.frm-sectionhd {
    border-bottom: 1px solid #a6a6a7; 
    background:#f1f3f9;
    padding:6px;
    margin:30px 0;
}
</syntaxhighlight>[[File:Manual:forms-css-class-view-en.png|alt=Section label with customized styling|center|thumb|650x650px|Section label with customized styling]]
 
If you do not have permission to view this page, you can enter style information directly for each element in the form via inline styling.
 
===Inline styling===
Without access to ''MediaWiki:Common.css'', the style information can be entered directly in the form. However, with many recurring style declarations this is not efficient in contrast to the definition of CSS classes in ''MediaWiki:Common.css''.
 
As an example, let's apply the previous section heading example directly as inline styling. To do this, open the options menu of the ''ech-event'' form element again. Enter the following statement in the ''Styling'' field and save the change:<syntaxhighlight lang="css">
border-bottom: 1px solid #a6a6a7;  background:#f1f3f9; padding:6px;margin:30px 0;
</syntaxhighlight>
[[File:Manual:forms-css-inlinestyling-en.png|alt=Inline styling of a form element|center|thumb|650x650px|Inline styling of a form element]]
{{translation}}

Latest revision as of 14:34, 20 May 2026


Form elements[edit | edit source]

It is possible to add the following form fields to your form:

Inputs[edit | edit source]

Field Functionality
Book auto-complete field that finds pages in the namespace "Book"
Text standard text field
Textarea multi-line text field
Wikitext input multi-line text field that expects Wikitext syntax
Category multiselect token field to add one or more categories to the page; values are separated with the enter-key
Checkbox single checkbox
Menu tag multiselect multiple-value input; values are separated with the enter-key
Checkbox multiselect checkbox group (allows selecting multiple values in the group)
Dropdown dropdown list with predefined options
Number integer field
Radio button single radio button (usually not used in a manually completed form)
Radio group radio buttons for toggling a selection (allows selecting only one value in the group)
File chooser selects a file in the wiki
Title input auto-complete field for wiki pages
Combo box combines a text input field and a dropdown list. Users can select a predefined value or type their own.
Password input sets a password with a password and password-repeat field. This is not used in forms for the target types JSON on wikipage, Template or Email, as the password is stored in plain text.
Tag input token field to add multiple values; values are separated with the enter-key
Date same as Date picker
Title input selects page titles in the wiki
User input username that exists in the wiki
Group input group name that exists in the wiki
Group multiselect multiple group names
User multiselect multiple user names
Title multiseslect multiple page titles
Date picker calendar widget
Percent integer value

Other[edit | edit source]

Element Description
Static Wikitext non-editable text
Button triggers an action (requires a defined event listener)
Message banner message that can be shown anywhere in the form;

the type that is set (notice, error, warning, success) provides the visual formatting

Partial form import adds form fields from another form
Icon -
Indicator -
Label -
Progress bar visual representation of the number of completed steps in a form such as a checklist
Section label a heading to a form section
HR a visual separator line

Input field options[edit | edit source]

Each input field has a combination of any of these options:

main
Type Field Functionality
(all) Name field name stored in the database (avoid special characters)
Label text label shown to users
Help creates a tooltip pop-up next to the label
No layout hides the label
Show on mode in which this field is visible
Editable on sets when the field value can be edited
Book Return property ?
styling
Type Field Functionality
(all) CSS Classes add individual CSS-classes for use on MediaWiki:Common.css

- the class is set on the form field itself and does not include the label; multiple classes can be set together or you can add them separately

Style define an inline style that affects only this field. The style is applied to the wrapper and includes the label and the field
Textarea, Wikitext input Number of rows used for textareas
Placeholder text that is displayed before the user is typing a value (has no effect, if there is also a default value set)
Radio group No default value ensures that there is no pre-selected radio-button if a default would not make sense
Radio group, Checkbox multiselect Horizontal layout aligns multiselect checkboxes or radio groups horizontally
Button Icon displays an icon before the text, (e.g. a bootstrap-icon like bi bi-calendar)
Indicator displays an icon after the text (e.g. a bootstrap-icon like bi bi-arrow-right)
Framed when deactivated, the button looks like text only (and can be styled via CSS classes, e.g. btn button-warning)
other
Type Fieldset Field Functionality
(all) Custom widget properties Key
Value
Listeners Event event that is supported by OO.ui widgets, such as change, enter, focus, blur
Callback function that is called when the event occurs (can be declared in MediaWiki:Common.js for example
Default value /

Selected by default

value that is used if the user does not provide a value; field type "checkbox" has option "Selected by default" instead
Required form cannot be submitted without this field having a value
Password Password strength weak:

medium: strong:

Tag Input position inline:

outline:

Allow arbitrary It is possible to add values other than the allowed values (only necessary if allowed values are defined)

Form Settings[edit | edit source]

Appearance[edit | edit source]

Field Functionality
Title display title for the form
Display title shows the form title above each form instance
Display form name displays the name fo the form with label Form used as first form element

Behaviour[edit | edit source]

Field Functionality
Categories adds categories to each form instance; values are separated with the enter-key
Seal after creation form instances cannot be edited after the initial save
Enable intermediate saving form instances show both a Save end a Save & Close button;

the Save button saves the form values and keeps the form in edit-mode.

Infrastructure[edit | edit source]

Field Functionality
Resource loader dependencies
Keep track of revisions
Includable extends form
Abstract
Partial

Target[edit | edit source]

Field Functionality
Target type
Predefined page title for pages created using this form use the field name to insert the value from a form field;

for example: if you have a field with the name company_name, you can use {{company_name}} as page name or part of the page name.

Listeners[edit | edit source]

Field Functionality
Event each listener reacts to one of these events:
  • initCompleteForm: object is initialized
  • parseComplete: JSON/schema/config fully processed
  • renderComplete: UI fully rendered in DOM
  • beforeSubmitData: Right before submission
Callback calls a function when the event occurs;

see the progress bar example.



PDF exclude - start

To submit feedback about this documentation, visit our community forum.

PDF exclude - end

The display title sets a page title that is different from the page name.

It becomes the preferred page label used in many automatically generated page lists. It can be changed with the visual editor (Options > Advanced settings). The source of the wiki page shows the magic word {{DISPLAYTITLE:My display title}}.

Retrieved from "https://en.wiki.bluespice.com/w/index.php?title=Manual:Extension/Forms/Form_elements_and_settings&oldid=14255"