By MW in article — 04 Nov 2024

How to Configure and Use the Page Forms Extension in MediaWiki

MediaWiki’s core editing interface works well for free‑form text, but many wikis need a structured way to collect and query data – for example, a catalog of books, a project tracker, or a directory of staff. The Page Forms extension (formerly Semantic Forms) fills that gap. It lets you define forms that create and edit pages based on templates, and it integrates with Semantic MediaWiki or Cargo when those extensions are present.

1. Installing Page Forms

Page Forms can be added to any MediaWiki installation that runs version 1.40 or newer. There are three common installation methods:

Git clone (recommended for development)
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageForms.git Place the resulting PageForms directory inside extensions/.
Composer
Add the requirement to composer.local.json:
{
"require": {
"mediawiki/page-forms": "^6.0"
}
}
Run composer update.
ZIP download
Download the zip from the extension’s GitHub mirror, extract it to extensions/PageForms.

After the code is in place, enable the extension by adding a single line to LocalSettings.php:

wfLoadExtension( 'PageForms' );

Save the file and reload your wiki. If the installation succeeded you will see a new Special:FormEdit page and a set of helper special pages (e.g., Special:CreateForm, Special:CreateClass).

2. Core Concepts

Page Forms works with three types of wiki pages:

Templates – define how data is stored and displayed. They usually live in the Template: namespace and contain calls to semantic properties (if SMW/Cargo is used) or plain parameters.
Form definition pages – live in the Form: namespace. They contain a custom markup language that describes which template(s) the form will edit and what fields appear to the user.
Categories – act as the bridge between a page and its default form. Adding a #default_form call to a category page tells MediaWiki which form to load when a user clicks “Edit with form”.

When a form is submitted, Page Forms writes the values into the target page’s template calls, preserving any free‑text that does not belong to a template.

3. Quick Start – Using the Helper Pages

If you are new to Page Forms, the fastest way to get a working data structure is to use the built‑in helper pages. They generate the necessary properties, templates, forms and categories in one go.

3.1 Special:CreateClass

Navigate to Special:CreateClass. The page asks for:

Class name – a human‑readable label (e.g., “Book”).
Template name – the name of the template that will hold the data (usually the same as the class).
Category name – the category that groups all pages of this type.
Fields – for each field you specify the label, the property name (if using SMW/Cargo), the input type, and optional values or defaults.

When you submit the form, MediaWiki creates:

A Property: page for every field (if SMW is installed).
A Template: that stores the data and displays it.
A Form: definition that matches the template.
A Category: with a #default_form call pointing to the new form.

From that point on, any page placed in the category automatically gets an “Edit with form” tab.

3.2 Individual helpers (optional)

If you already have templates or categories, you can create the missing pieces individually:

Special:CreateProperty – adds a new SMW property.
Special:CreateTemplate – scaffolds a template with the appropriate #arraymap calls for list fields.
Special:CreateForm – opens a blank form definition page where you can fine‑tune the layout.
Special:CreateCategory – creates a category and inserts the #default_form call.

4. Writing a Form Definition by Hand

While the helpers are convenient, many wikis need custom layouts, multiple‑instance templates, or embedded forms. The syntax lives inside triple curly braces ({{{ … }}}) and is split into three main tags.

4.1 The `info` tag (optional)

{{{info|create title=Add a new book}}}

Sets the title of the “Create” page. You can also specify a page name formula to generate page titles automatically (e.g., page name=<Title> – <unique number>).

4.2 The `for template` … `end template` block

{{{for template|Book}}}
{| class="formtable"
! Title || {{{field|Title|input type=text|mandatory}}}
! Author || {{{field|Author|input type=combobox|values from category=Authors}}}
! Year || {{{field|Year|input type=year}}}
! Genres || {{{field|Genres|input type=checkboxes|values=Fiction,Non‑fiction,Poetry}}}
|}
{{{end template}}}

The block tells Page Forms which template to populate (Book) and lists the fields that appear to the user. Each field tag can include parameters:

input type – one of the many supported types (text, textarea, dropdown, combobox, tokens, datepicker, etc.).
mandatory – forces the user to fill the field.
default – a pre‑filled value (e.g., default=now for dates).
values, values from category, values from property – define the list of allowed values or enable autocompletion.
list – marks the field as a list; Page Forms will add a delimiter (default comma) and generate the necessary #arraymap call in the template.

4.3 The `standard input` tag

At the bottom of every form you can customise the buttons and auxiliary inputs. The default set includes “Save”, “Preview”, “Summary”, “Watch”, and “Cancel”. If you add any standard input tags, only the ones you list will appear, in the order you place them.

{{{standard input|summary|label=Edit summary}}}
{{{standard input|save|label=Save page}}}
{{{standard input|preview|label=Show preview}}}

5. Connecting Templates and Forms

For the form to work, the template must expose the same field names used in the form. A minimal Template:Book could look like:

{{#if:{{{Title|}}}|[[Has title::{{{Title}}}]]}}
{{#if:{{{Author|}}}|[[Has author::{{{Author}}}]]}}
{{#if:{{{Year|}}}|[[Has year::{{{Year}}}]]}}
{{#if:{{{Genres|}}}|{{#arraymap:{{{Genres}}}|,|g|[[Has genre::g]]}}}}

The #arraymap call turns a comma‑separated list of genres into separate Has genre statements, which is essential for multi‑value fields.

6. Enabling the “Edit with form” Tab

There are three ways to make the tab appear on a page:

Category based (recommended) – Add #default_form: Form:Book to the category page that groups all book pages. Every page in that category automatically receives the tab.
Namespace based – Add a #default_form call to a MediaWiki:Namespace page (e.g., MediaWiki:Book) to affect all pages in that namespace.
Per‑page – Insert #default_form: Form:Book directly on a page if it belongs to multiple categories with different forms.

If you want the tab to read simply “Edit” and hide the classic edit tab, set the following in LocalSettings.php:

$wgPageFormsRenameEditTabs = true; // rename “Edit with form” to “Edit”
$wgPageFormsRenameMainEditTab = false; // keep the source edit tab hidden

You can also control visibility per user group with the viewedittab right:

$wgGroupPermissions['*']['viewedittab'] = false;
$wgGroupPermissions['sysop']['viewedittab'] = true;

7. Linking to Forms

Page Forms provides several parser functions that turn a plain link into a form workflow.

#forminput – the two‑step process. Shows a small textbox where the user types a page name, then redirects to the appropriate form. Example:{{#forminput:form=Book|button text=Add a book}}
#formlink – the one‑step process. Directly opens the form for a new page, optionally pre‑loading fields via a query string. Example:{{#formlink:form=Book|link text=New book|query string=Book[Author]={{PAGENAME}}}}
#formredlink – replaces a red link (to a non‑existent page) with a link to the form that will create that page. Useful inside templates.{{#formredlink:target={{{Author|}}}|form=Author}}
#autoedit – performs the edit silently in the background (often used for voting or quick toggles). It respects the same query‑string syntax as #formlink.

All of these functions accept the same query string syntax used by the form itself, allowing you to pre‑populate fields, set defaults, or even specify a target page for a redirect after save.

8. Creating Query Forms

When you need a search interface rather than a data‑entry interface, use a query form. The workflow is:

Create a template that contains an #ask query. The query should reference the fields the user will fill in (e.g., ?Has author, ?Has year).
Create a form (via Special:CreateForm or manually) that uses the same field names as the query template.
Visit Special:RunQuery and select your query form. The form will appear, and after submission the same page will display the query results.

Because the query template lives in the Template: namespace, you can embed it anywhere with {{Special:RunQuery/YourFormName}} or link to it via #queryformlink.

9. Advanced Features

Multiple‑instance templates – add the multiple parameter to a for template block. Users can click “Add another” to insert additional copies of that template. You can control the minimum/maximum instances and the button label.
Embedded templates – use embed in field=TemplateName[Field] to store multiple‑instance data inside a parent template, keeping the page markup tidy.
File uploads – add the uploadable parameter to a field. Page Forms will show an “Upload file” link next to the input and store the filename in the field.
Autocompletion from external sources – define a URL in $wgPageFormsAutocompletionURLs['myservice'] = 'https://example.com/api?term='; and then use values from url=myservice on a field.
Conditional display – the show on select parameter lets you hide or reveal other page elements based on a field’s value.

10. Common Pitfalls and Troubleshooting

Missing #default_form call – the edit‑with‑form tab will not appear. Verify that the category page contains #default_form: Form:YourForm (or the namespace/page variant).
Field name mismatch – the field name in the form must exactly match the parameter name used in the template. A typo results in data not being saved.
List fields without #arraymap – if you forget to add list to a field, multiple values will be stored as a single comma‑separated string, breaking queries.
Permission errors – the four rights (createclass, editrestrictedfields, multipageedit, viewedittab) are granted to user or sysop by default. Adjust them in LocalSettings.php if you need tighter control.
Autocomplete limits – by default Page Forms caps autocomplete suggestions at 1,000 entries. Change $wgPageFormsMaxAutocompleteValues if you need more.
Version incompatibility – Page Forms follows MediaWiki’s compatibility policy. Always use a release that matches your MediaWiki version (e.g., 6.0.x for MediaWiki 1.40+).

11. Testing Your Setup

After you have created a form, a template, and a category, perform a quick sanity check:

Navigate to the category page and click the “Add a new …” link generated by the #default_form call.
Fill in the form fields and click “Save”.
Verify that the new page contains the expected template call and that the displayed output matches the template’s layout.
Use Special:RunQuery with a query form (if you created one) to ensure that the data is searchable.

If anything looks off, check the page source for missing parameters, and review the #arraymap calls in the template.

12. Maintaining Forms Over Time

Because forms are ordinary wiki pages, you can edit them directly to add new fields, change input types, or adjust layout. After editing a form, it is a good practice to edit one of its existing pages and click “Save” – this forces Page Forms to regenerate any automatically inserted #arraymap code that may have changed.

When you need to rename a field, update the field tag, the corresponding template parameter, and any #arraymap calls. Existing pages will retain the old data until you manually migrate it (e.g., via a bot or the #autoedit function).

13. Summary

The Page Forms extension turns MediaWiki into a lightweight data‑entry platform without requiring any programming. By installing the extension, defining templates, creating form pages, and linking those forms to categories, you gain:

Structured data entry via user‑friendly forms.
Automatic “Edit with form” tabs for seamless editing.
Powerful autocompletion and list handling.
Query forms that let users search the wiki’s data.
Fine‑grained permission control and customization options.

With the steps outlined above you can get a simple catalog up and running in minutes, then evolve it into a full‑featured data management system as your wiki grows.

For the most up‑to‑date reference, always consult the official documentation on mediawiki.org.