Template forms

This is the page about the project to enable template calls on MediaWiki pages to be editable by their own forms. This project is distinct from extensions such as Semantic Forms, which allows for editing an entire page using a form; instead, each template call would be editable independently, using a pop-up form in the "edit" page.

The main inspiration for this project is the Vorlagen-Meister (template handler or, literally, "template master") gadget on the German Wikipedia. In that system, each template is responsible for defining its own field structure, in XML form, on the ".../XML" subpage of the template's own page. Here is one example of such an XML file on the German Wikipedia: http://de.wikipedia.org/wiki/Vorlage:Infobox_Band/XML . When a user with this gadget enabled goes to edit a page that includes a call to such a template, they can right-click on the call in order to pop up a form, containing a text entry for each field in the template; if they submit this form, the changes they made in the form show up in the source code. Note that this editing can be done for every template, not just the infobox ones; here, for example, is the XML page for the "internetquelle" template, which looks like the German equivalent of the English "web cite": http://de.wikipedia.org/wiki/Vorlage:Internetquelle/XML.

Under the current plan, the template forms project for Wikimedia would re-use some of the XML structure of the Vorlagen-Meister gadget. There would be a few key differences, however:

the feature would be implemented in PHP and Javascript, not strictly in Javascript
it would be enabled by default for every user
additionally, by default every template call would show up on the edit page as "minimized" in some way; see "Interface for editing template calls", below
the XML definition for templates would be located directly in template pages
additional input types could be defined by other extensions; a map input type, for geographical coordinates, is an obvious candidate for an extension-based type
there would be support for internationalization of the strings used within each form: the label and descriptive text for each field, and, in the case of "enumerated" inputs, i.e. those with a set of recommended values (such as appears with a dropdown input), possibly also those values (not the actual string that would show up in the template call, just what's displayed in the form).

If an XML file does not exist for a given template, or one exists but it is not parseable, a button will still appear in place of the template call; but when the button is pressed, the system will instead either display a simple textbox for editing the template call; or parse the template itself and display a "best-guess" form for editing the call, based on the fields contained in the template. Of these, the former seems more viable, on the theory that it's better to have a cumbersome interface than an incorrect one.

Interface for editing template calls

By default, the textarea in the edit page would be replaced by a Javascript-enabled edit box that (1) did syntax highlighting, and (2) turned template calls into clickable rectangles. The edit box would basically look like a standard Javascript-based source code editor, like CodeMirror or CodePress; see here for an example of CodeMirror in action. The template calls, on the other hand, might look like this example from Wikia; note that the "stub" button at the top of the page represents a call to the "stub" template. Clicking on this button would bring up a window that might contain both a form for editing the call and a way to edit the call's wiki-text directly.

Specification structure

The template specification has to handle translation in one way or another. Since the proposed first usage of this system is on Wikimedia Commons, which is meant to support all languages, this is a very relevant issue. The plan is for as much of the form to be translateable as possible: field labels, field description messages, and possibly values as well, in the case of enumerated fields (like dropdowns).

Here is the proposed XML structure, for a simple template that contains two parameters: "author" and "license" (information that appears on Wikimedia Commons):

<templateinfo>
  <group id="main">
    <param id="author">
      <label>
        <msg language="en">Author</msg>
        ...
      </label>
      <description>
        <msg language="en">The creator of this image; preferably a link to a user page</msg>
        ...
      </description>
    </param>
    <param id="license">
      <label>
        <msg language="en">License</msg>
        ...
      </label>
      <description>
        <msg language="en">The license under which this image will be published</msg>
        ...
      </description>
      <options>
        <option name="CC-by">
          <msg language="en">Creative Commons Attribution</msg>
          ...
        </option>
        <option name="CC-by-sa">
          <msg language="en">Creative Commons Attribution-Share Alike</msg>
          ...
        </option>
      </options>
    </param>
  </group>
</templateinfo>

The presence of ellipses (...) indicates where other language translations could go.

The "<group>" tag is used to specify groupings of fields within the form; this could, for instance, lead to all fields in one group being put into one HTML "fieldset".

Untranslated values

The structure should also support elements in only one language, with no translation provided. There, in place of a series of <msg> tags, there would simply be a string literal. In other words, instead of:

      <description>
        <msg language="en">The license under which this image will be published</msg>
        ...
      </description>

It would simply be:

      <description>The license under which this image will be published</description>

Defining data type

A planned enhancement for this structure is to also allow for defining the data type or class of a specific template parameter. This would be accomplished through a "<type>" tag, enclosed within the "<param>" tag. A simple call to this tag could look like:

      <type name="Number" />

...while a more complex call could look like:

      <type name="Datetime">
        <field name="date format">DD MM YYYY HH MI SS AM</field>
      </type>

Defining the interface and display

The above specification does not allow for defining anything about the display of the form, including which form input types should be used, and specific display settings for both the inputs and the text. For all those, it is proposed that other tools and applications can define additional data, by using the "<data>" tag, which itself is split up via tags called "<field>"; this tag can be defined within three other tags: "<templateinfo>", "<group>" and "<param>", depending on whether they modify the entire form, a field/parameter group, or a single field/parameter. This would allow individual tools and applications, both browser-based and otherwise, to define whatever interface settings they wanted for each parameter/form field. Here, for example, is a theoretical call for the "license" parameter defined above:

      <param id="license">
        ...
        <data app="stevesbot">
          <field name="inputtype">Radiobutton</field>
          <field name="cssclass">spiffy-radiobutton</field>
        </data>
        <data app="AcmeIPhoneApp">
          <field name="widget">Option selector</field>
          <field name="labelColor">Green</field>
        </data>
      </param>

Within the Template Forms code, a hook would be provided to enable tools and applications to modify the display of each field in the form, based on that tool's (or any other's) display settings.

Document Type Definition

Here is the Document Type Definition (DTD), created by Trevor Parscal, for the proposed XML format:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE template [
<!ELEMENT template (description?,params?,data*)>
<!ELEMENT templateinfo (param|group)*>
<!ELEMENT params (param|group)*>
<!ELEMENT param (label?,description?,options?,type?,data*)>
<!ATTLIST param id ID #REQUIRED>
<!ELEMENT group (label?,description?,param*,data*)>
<!ELEMENT label (#PCDATA|msg)*>
<!ELEMENT description (#PCDATA|msg)*>
<!ELEMENT options (option*)>
<!ELEMENT option (#PCDATA|msg)*>
<!ELEMENT type (field*)>
<!ATTLIST type name CDATA #REQUIRED>
<!ELEMENT field (#PCDATA)>
<!ATTLIST field name CDATA #REQUIRED>
<!ELEMENT msg (#PCDATA)>
<!ATTLIST msg lang CDATA #REQUIRED>
<!ELEMENT data (field*)>
<!ATTLIST data app CDATA #REQUIRED>
]>

Technical implementation

The current plan is for this functionality to get implemented in two parts: a new extension, TemplateInfo, and additions to the UsabilityInitiative extension. The TemplateInfo extension is responsible for defining two things, both implemented in PHP:

a tag function, <templateinfo>, that takes in the rest of the XML and handles display, transclusion and usage of it in an appropriate manner.
an additional action for the MediaWiki API so that the XML definition can easily be retrieved via API for a given template; this action will also validate the XML, and return a helpful error message if it's invalid.

The actual display of the form will be handled entirely in Javascript, using the jQuery library, within the UsabilityInitiative code.

Any feedback or questions about this proposal are welcome on the talk page.