Extension:Page Forms

Description
Semantic Forms is an extension to MediaWiki that allows users to add and edit data using forms. It is heavily tied in with the Semantic MediaWiki extension, and is meant to be used for structured data that has semantic markup. Having Semantic MediaWiki installed is a precondition for the Semantic Forms extension; the code will not fully work without it.

Very simply, Semantic Forms allows you to have forms for adding and editing data on your wiki, without any programming. Forms can be created and edited not just by administrators, but by users themselves.

The main components of Semantic Forms functionality are form definition pages, which exist in a new namespace, 'Form:'. These are pages consisting of markup code which gets parsed when a user goes to add or edit data. Since forms are defined strictly through these definition pages, users can themselves create and edit forms, without the need for any actual programming.

The Semantic Forms extension enforces the use of templates in creating semantic data. It does not support direct semantic markup in data pages; instead, all the semantic markup is meant to be stored indirectly through templates. A form allows a user to populate a pre-defined set of templates for a page (behind the scenes, that data is turned into semantic properties once the page is saved).

Forms can also be used to edit the data in an existing page, and you can enable an 'edit with form' tab to show up on any page; see The 'edit with form' tab.

Semantic Forms also supports autocompletion of fields, so users can easily see what the previously-entered values were for a given field. This greatly helps to avoid issues of naming ambiguity, spelling, etc.

Data in a page that doesn't fit into the form, like a free-form text description of the page's subject, isn't ignored when the page is edited with a form; rather, it is placed into a separate input box called "free text".

Semantic Forms also provides hooks to let outside code easily define new input types; this is useful for, among other things, new extensions to define input types that use code that they provide.

Semantic Forms also provides other features: a form to create semantic properties, a form to create templates, a form to create user forms, pages that list all the templates and all the user forms on the site, and others. This documentation covers all the features, but see especially the Special pages section.

Download
You can download the Semantic Forms code in either one of these two compressed files:


 * semantic_forms_1.5.1.tar.gz
 * semantic_forms_1.5.1.zip

You can also download the code directly via SVN from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticForms/. From a command line, you can call the following:

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticForms/

Installation
Note once again that, before you install Semantic Forms, you must have Semantic MediaWiki installed as well.

After you've created a 'SemanticForms' directory (either by extracting a compressed file or downloading via SVN), place this directory within the main MediaWiki 'extensions' directory. Then, in the file LocalSettings.php in the main MediaWiki directory, add the following line below the calls for the Semantic MediaWiki extension (both the main 'include_once' line and the 'enableSemantics' line):

You may also wish to change the number value for the new "Form" namespace, defined in SF_Settings.php; by default it is set to 106.

Also, if you have any custom namespaces declared, you should add the following declaration before the 'include_once' call in the file 'LocalSettings.php':

(Or, instead of 150, whatever number you want the "Form" namespace set to.)

NOTE: The definition of $sfgNamespaceIndex and the call to SF_Settings.php must be placed after the initialization of any custom namespace definitions in LocalSettings.php. Otherwise, the Form namespace will not initialize.

Authors
Semantic Forms was created, and mostly written by, Yaron Koren, reachable at yaron57 -at- gmail.com. Important code contributions were also made by Daniel Friesen, Eugene Mednikov, Harold Solbrig, Jayson Harshbarger, Jeffrey Stuckman, Louis Gerbarg, Matt Williamson, Nils Opperman, Sergey Chernyshev and wheresmytab.

Version
Semantic Forms is currently at version 1.5.1. See the entire version history.

Languages supported
Semantic Forms has full support for English, Arabic, Taiwanese Chinese, Mainland Chinese, Dutch, French, German, Norwegian Bokmål, Persian and Brazilian Portuguese, and partial support for Afrikaans, Belarusian, Bengali, Bulgarian, Catalan, Croatian, Czech, Danish, Finnish, Greek, Gujarati, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Khmer, Lithuanian, Marathi, Pashto, Polish, Portuguese, Romanian, Russian, Serbian Cyrillic, Slovak, Spanish, Swedish, Tagalog, Tajik, Turkish, Ukrainian, Vietnamese and many other languagues.

Code structure
The following are the directories and files in the Semantic Forms extension:

/includes


 * SF_AutocompleteAPI.php - defines a class, SFAutocompleteAPI, that adds a new action, 'sfautocomplete', to the MediaWiki API, to enable remote setting of autocompletion values.
 * SF_FormClasses.inc - defines two classes, SFForm and SFTemplateInForm, that represent the components of a user-defined form, and handle the creation of a form definition file.
 * SF_FormEditTab.php - a tab that shows up on data pages to let the user edit them with a form, if a default form for this page's category or namespace has been specified.
 * SF_FormField.inc = defines a class, SFFormField, used in displaying user-created forms
 * SF_FormInputs.inc - static functions for Semantic Forms' built-in form inputs.
 * SF_FormPrinter.inc - defines a class, SFFormPrinter, that handles the display and running of a user-created form.
 * SF_FormUtils.inc - utility functions for displaying a form.
 * SF_GlobalFunctions.php - sets hooks and defines constants used by the rest of the Semantic Forms code.
 * SF_LinkUtils.inc - utility functions for linking to pages and forms.
 * SF_ParserFunctions.php - defines parser functions (currently four - 'forminput', 'formlink', 'arraymap' and 'arraymaptemplate')
 * SF_Settings.php - various settings for Semantic Forms.
 * SF_TemplateField.inc - defines a class, SFTemplateField, used in both creating templates and displaying user-created forms.
 * SF_Utils.inc - general utility functions.

/languages


 * SF_Aliases.php - aliases for special-page names for all languages
 * SF_Language.php - parent class for all language files
 * ...various other language files...
 * SF_Messages.php - display messages for all languages

/libs


 * floatbox.js - the Floatbox Javascript library
 * SF_yui_autocompletion.js - helper functions for autocompletion with the Yahoo! User Interface (YUI) library

/skins


 * close.png - "x" image to close the upload window
 * floatbox.css - CSS file for the Floatbox library
 * loading.gif - "window loading" image
 * SF_main.css - main CSS file for Semantic Forms
 * SF_yui_autocompletion.css - CSS file for YUI auto-completion

/specials


 * SF_AddData.php - defines the 'AddData' special page
 * SF_AddPage.php - defines the 'AddPage' special page
 * SF_CreateCategory.php - defines the 'CreateCategory' special page
 * SF_CreateForm.php - defines the 'CreateForm' special page
 * SF_CreateTemplate.php - defines the 'CreateTemplate' special page
 * SF_CreateProperty.php - defines the 'CreateProperty' special page
 * SF_EditData.php - defines the 'EditData' special page
 * SF_Forms.php - defines the 'Forms' special page
 * SF_Templates.php - defines the 'Templates' special page
 * SF_UploadWindow.php - defines the 'UploadWindow' special page

To view the code online, including version history for each file, you can go here.

Special pages
The extension defines eight "special" MediaWiki pages:


 * Special:AddData - lets a user add a page using a user-defined form. (See example of page)
 * Special:AddPage - lets a user specify a page name, to be either added or edited depending on whether it already exists. (See example of page) This page is somewhat deprecated.
 * Special:CreateForm - lets a user create a new form for adding/editing data. (See example of page)
 * Special:CreateTemplate - lets a user create a new template. (See example of page)
 * Special:CreateProperty - lets a user create a new property. (See example of page)
 * Special:CreateCategory - lets a user create a new category. (See example of page)
 * Special:EditData - lets a user edit an existing page using a user-defined form. (See example of page) This page is somewhat deprecated.
 * Special:Forms - lists all form pages on the site. (See example of page)
 * Special:Templates - lists all templates on the site. (See example of page)
 * Special:UploadWindow - lets a user upload a file; very similar to the standard Special:Upload page, but without the skin. (http://discoursedb.org/wiki/Special:UploadWindow See example of page]) This page is called from within a form, and should not be accessed directly by users.

Getting started
So, you've set up all the software on your site. Now what? Now it's time to create the structures to hold, display and enable adding and editing of your data; thankfully all of this can be done simply by creating various wiki pages. You should take the following steps:


 * Figure out your data structure. What types of pages will the site have? What data will be contained on each one? You can change all of this around later, but it's good to have a starting plan.


 * Create properties. The basic building blocks of any semantic site are the connections between data, which in Semantic MediaWiki are known as properties. A property is used to specify a single piece of information about the topic of this page; the value of a property can either be a standalone value, or the name of a page on the wiki. Every property should be defined on your wiki, with a page in the "Property:" namespace. The easiest way to do that is using the 'CreateProperty' special page (see above).


 * Create templates. A template sets the display of the data on a page, holds the markup to turn the data into actual semantic information, and (often) defines the page as being of a certain category, and thus of a certain page type. There will generally be one template per page type, although sometimes a single page type will contain more than one template. A template can also be used for aggregation, by displaying a list of all other pages that have a certain relationship to this page (see the inline queries documentation for much more information on this). The easiest way to create templates is using the 'CreateTemplate' special page (see above).


 * Create forms. Now you can create forms to allow users to easily add and edit pages of various types. There should be one form per page type; a form should populate the template or templates that this page type contains. As before, there's a special page to create new forms: 'CreateForm' (see above). See below for documentation on the special markup language used to define forms. One common request is for these three special pages ('CreateProperty', 'CreateTemplate' and 'CreateForm') to be able to edit existing property/template/form pages, and not just create new ones. However, this is programatically much harder to implement than creating new pages, because it requires parsing. For the foreseeable future, modifying existing properties, templates and forms will have to be done by hand.


 * Create categories. One template in each form should define each article that the form creates as being part of a certain category. You should create a page for each such category, and specify a default form for it so that every article is automatically editable with the same form that created it. The easiest way to do that is using the 'CreateCategory' special page (see above).


 * Enable links to forms. Besides creating categories that have a default form, there are other steps you should take to enable users to access the forms that you have created. These include adding links to add data in the sidebar and elsewhere, and setting default forms and alternate forms on properties, to have red-links to nonexistent pages point to a form for creating them. These actions are all explained further below.


 * Add data. You should also add data to the site, using your new forms, to make sure that forms, templates and categories are working the way you want them to.


 * Add links on sidebar and elsewhere. The sidebar (which, for English-language wikis, can be edited at the page "MediaWiki:Sidebar") should hold links to add each of the data types, and to the categories for each of these data types as well. You can also include such links on the main page and elsewhere.


 * Customize. Once the structure is in place, you can customize all you want - changing the look-and-feel of the entire wiki, of the various templates, and of the forms, adding and changing fields and adding and changing inline queries for queries.

Example
To see this process in action, see the example of how these steps would be followed for an actual wiki.

Quick reference guide
A quick reference guide, or "cheat sheet", for Semantic MediaWiki, Semantic Forms and several other extensions, exists, contained on one page and suitable for printing. It can be found here, in PNG (image), PDF and SVG formats.

Form markup language
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:


 * - 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:
 * - Indicates that this form is a partial form; see "Partial forms", below.
 * title - Sets the title for the 'AddData' page that uses this form definition
 * title - Sets the title for the 'EditData' page that uses this form definition
 * formula - Sets a formula for automatic setting of the name of the page being added; see "The one-step process", below.


 * - 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 text - Specifies a label to be placed in a square around the entire set of this template's fields in the form.
 * - Specifies that the user can change the number of instances of this template in the form, allowing multiple (or zero) occurrences; see "Multiple values for the same field", below.
 * dropdown name - Similar to multiple, but allows for a single dropdown input in the form to add instances of each template labelled as chooser, instead of each such template requiring its own 'Add' button.
 * caption - Sets the caption in the form's dropdown for adding instances of this template; must be set in conjunction with chooser option.
 * - Specifies that only fields in the form that correspond to fields used by the template should get turned into form elements.


 * - Ends the range of a template. There are no parameters for this 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. Allowed parameters of this tag are:
 * input type - Specifies the type of input this field will have in the form: allowed values are text, textarea, date</tt>, datetime</tt>, datetime with timezone</tt>, radiobutton</tt>, checkbox</tt>, listbox</tt> and checkboxes</tt>. If a field corresponds to a semantic property, the form will usually have the correct input type by default; otherwise the default is text</tt>.
 * size - Used for text entries and listbox. Specifies the width of a text entry, or the height of a listbox.
 * maximum length - Used for text and textarea entries. Specifies the maximum allowed length of the input.
 * num rows - Used for textarea entries. Specifies the number of rows.
 * num cols - Used for textarea entries. Specifies the number of columns.
 * - Specifies that this field must be filled in by the user.
 * - Specifies that this field will be hidden in the form: used to preserve values in edited pages.
 * - Specifies that this field will be editable only by admins/sysops and disabled for all other users.
 * - 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.
 * - Specifies that this field will be autocompleted based on previous values entered for the semantic property that it covers. This declaration is not necessary for fields that handle properties of type "Page", since this kind of autocompletion happens for them by default. In practice, this parameter only makes sense for fields of type "String".
 * - Disables autocompletion for a field, if it's on by default.
 * property - Used for text entries. Specifies that autocompletion should use the set of pages or values pointed to by a certain property. This parameter works only for versions of Semantic MediaWiki greater than or equal to 1.0.
 * category name - Similar to , but autocompletes on the names of pages within the specified category (and all its subcategories).
 * concept name - Similar to , but autocompletes on the names of pages within the specified concept.
 * namespace name - Similar to, but autocompletes on the names of pages that belong to a certain namespace.
 * - Specifies that autocompletion values should be retrieved using Ajax calls to the server, instead of directly from a list of values contained in the page.
 * property name - Specifies that the field corresponds to a certain semantic property, and should thus get the corresponding input type, autocompletion, etc.
 * default value - Specifies a default value for this field. For date-related fields, default=now</tt> will set the value to the current date and possibly time. For text fields, default=current user</tt> will set the value to the username of the user adding this page.
 * possible values - Specifies a set of possible values that this field can have, overriding whatever set of values may have been set from the semantic property. If this parameter is added, the field will, by default, show up as a dropdown.
 * category name - Similar to, but gets its values from the names of all pages belonging to a specific category.
 * concept name - Similar to, but gets its values from the names of all pages belonging to a specific concept.
 * - Specifies that this field contains a list of values; used for autocompletion.
 * delimiter - Specifies the delimiter character or string this field should use, if it represents a list of values; the default is ",".
 * class name - Specifies a CSS class that the input for this field should have.


 * - Specifies the input for selecting the 'chooser' fields (see above), if any, for this form. This tag should appear no more than once, if at all, in a form.


 * - One of eight inputs that usually appear in 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 seven are form elements such as the "Save" and "Preview" buttons; see Defining the bottom of the form for the full list.
 * For the 'free text' input, the allowed parameters are rows</tt>, cols</tt>, hidden</tt>, restricted</tt>, default</tt> and preload</tt>. The first five work just as they do for <tt>field</tt> declarations. The new parameter is;
 * page title - Specifies a page whose contents should be preloaded into this field.
 * For the other standard input types, the only allowed parameter is
 * label name - Specifies the text associated with this input on the form.

Allowed input types for data types
Each defined Semantic MediaWiki data type has a default input type, and in some cases 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:

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:

Autocompletion
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 matches the beginning of every word in the set of possible values. It is enabled by the [http://developer.yahoo.com/yui/ Yahoo! User Interface] (YUI) Javascript library.

If a field represents a semantic property 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. For fields representing a semantic property of type "String", there is no default autocompletion, but you can achieve this same effect simply by adding the parameter "autocomplete" to the field's definition. You can also autocomplete on other sets of values: you can change the property on which a field autocompletes by adding the "autocomplete on property=..." parameter to the field definition; you can autocomplete any field on the set of pages in a category by adding the "autocomplete on category=..." parameter, specifying the name of that category; and you can do the same for all pages in a namespace by adding the "autocomplete on namespace=..." parameter (if you want to autocomplete on the main namespace, just add "autocomplete on namespace=").

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 in the SF's "SF_Settings.php" file, as the variable $sfgMaxAutocompleteValues, and by default it 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.

Finally, you can disable autocompletion, if it's enabled by default for a field, by adding the parameter "no autocomplete" to the field's definition.

Multiple values for the same field
There may be fields for which you want the user to be able to enter multiple values. You can allow a single field in a template to hold many values, separated by commas or some other string. To do this, the template should contain the Semantic Forms parser function '#arraymap', which applies a mapping on each section of a delimited string. The generic call for this function is:

<tt> </tt>

The function splits the value by the delimiter, then, for each one, applies the same mapping that 'formula' does to 'var', and finally joins all the values again using the new delimiter. For example, if you have a form that populates the field 'author', and you want the values for that field to be separated by commas and to each get the semantic property 'Has author', you could add the following to the template code, in place of a regular semantic tag:

<tt> </tt>

Essentially this function 'maps' the property tag onto each comma-delimited value in the field. (The 'delimiter' defaults to "," and 'new_delimiter' defaults to ", " if they are not set.) The user can thus enter all the values on the same line, with or without spaces around the commas. (Note, by the way, that the "x" is used here as an internal variable: if the property name itself contains the letter "x", that will lead to problems, and you should replace the letter "x" with some character or string that does not appear in the property name.)

If you use the 'CreateTemplate' page to create a template, an option exists to let you automatically add this parser function in the template for any field that can take more than one value.

There are some kinds of mapping that are complex enough that they cannot be placed in the #arraymap function. For this purpose, you can instead use the similar #arraymaptemplate function. To use this function, create a template that takes in a single field and applies the mapping you would like to that field. Then apply #arraymaptemplate onto the main template field just as you would with #arraymap, using the following format:

<tt> </tt>

...where 'template' is the name of the mapping template in question.

Multiple-instance templates
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).

Uploading files
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 Floatbox 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.

Due to Javascript limitations, this uploading will not work on fields contained in multiple-instance templates.

You can see a demonstration of file uploading here.

The free text input
The 'free text' input sets a textarea that holds all the non-template text in a page. The height, width and CSS style of this field can be set just as they would for any textarea input. 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. It is possible to have a WYSIWYG editor for the free text input: if your wiki has the MediaWiki FCKeditor extension installed, and it shows up correctly in regular 'edit' pages, then it should show up automatically as well for the free text input (currently, this is the only form input for which the FCKeditor can be made to work).

Defining the bottom of the form
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 seven allowed values are "save" (for the "Save page" button), "preview" (for the "Show preview" button), "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) and "cancel" (for the "Cancel" link). So, for example, the button for "Save page" could be specified with " ", which would place the button where it was defined, with the text on the button reading "Save this page". If no  tags are included in the form definition, all six 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
Here is the source code for the 'Item' form definition page at Discourse DB:

Topic:

Position:

Stance:

Item name:

Free text:

Note the presence of wiki-text within the code. This markup was created using the Create Form page, and 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.

Adding data
Adding data is usually structured as a two-step process: first the user inputs a page title, and then he/she is sent to a form for either adding or editing that page, depending on whether or not the page already exists; this ensures that users don't accidentally overwrite existing pages. However, it's also possible to skip the first step, if the form contains a formula for setting the page title based on the user input.

The two-step process
There are two ways to let users add data in this way:

1) Use the 'forminput' parser function - adding this tag to any page will make an input that will let the user specify a title for adding or editing. By default, this input is included in every form created by the 'CreateForm' page. Here is the generic call for the tag:




 * All arguments are optional. An explanation of the parameters:
 * form_name is the name of the SF form to be used; if it is left empty, a dropdown will appear, letting the user choose among all existing forms.
 * size represents the size of the text input (default is 25).
 * value is the starting value of the input (default is blank).
 * button_text is the text that will appear on the "submit" button
 * query_string is the set of values that you want passed in through the query string to the form. It should look like a typical URL query string; an example would be "namespace=User&User[Is_employee]=yes".

2) Use 'AddPage' - the user can go to /Special:AddPage; a form name can optionally be specified in the URL, so it looks like /Special:AddPage/form-name. If no form name is specified, a dropdown of all available forms in the wiki will appear next to the input for the page name, letting the user choose. (This approach is not recommended.)

Adding pages of a specific namespace
You can have a page-input form create pages within a specific namespace (like 'User:') by default, without forcing users to type in that namespace every time. If you're using the 'forminput' tag, the "query_string" value should include 'namespace=namespace-name'. If you're using 'AddPage', you can do so by setting the URL to something like " http://mywiki.com/Special:AddPage/ form-name/Namespace:namespace-name".

Adding sub-pages
In MediaWiki, you can create sub-pages by including a slash in the page name. To have the page that's added automatically be a sub-page, you can add a value for "super_page=" in the query string. To make it a sub-page of the current page, you can set this value to "super_page=". This will prepend a "current-page-name/" onto the beginning of the page name that the user types in.

The one-step process
You can have the name of the page created by the form be created automatically, by adding a "page name" parameter within the form definition's "info" tag. There are two types of "variables" one can include in the value for this field:
 * '< TemplateName[FieldName] >' - gets replaced with the value for the specified field in the specified template
 * ' ' - gets replaced by the lowest number for which the page title that's generated is unique. Normally, this value starts out as blank, then goes to 2, then 3, etc. However, one can manually set the starting number for this value, by adding a "start=" parameter; this number must be 0 or higher. For instance, to have the number start at 1 and go upward, you should set the tag to be " <unique number;start=1> ". Note that the parameter is delimited by a semicolon.

For example, the form described above could have a declaration of "page name=<Item[Author]> opinion item <unique number;start=1>". This would include the author's name in the name of every opinion item, as well as a number to guarantee the uniqueness of every opinion-item page added. A user could then go to the URL " http://discoursedb.org/wiki/Special:AddData/Item " and fill out the form; if they set the author to be "Ernest Hemingway", and no other opinion items in the wiki had him as an author, then hitting the "Save page" button would result in a new page called "Ernest Hemingway opinion item 1".

Note that users must be sent to the page "Special:AddData/form-name" for this automatic page-setting to work; if they go instead to the regular form page, or to "Special:AddPage", they will be prompted for a page name, which will override whatever the automatic page name would be. (Though it should be noted that you can also change the form page to link to "Special:AddData/form-name", in place of having the #forminput input.)

If you want, you can generate this link using the "#formlink" parser function, instead of creating the URL directly. This function is called as:



The first, second and fourth arguments work much the same way that their equivalents in "#forminput" work (see above). The "link_type" argument sets the display of the link: if it's set to "button", the link will show up as a button; if it's set to blank or anything else, it will show up as a regular link.

Preloading data
You may want a form to already contain some data when the user goes to it. (Note that this only applies to adding new data; for editing an existing page, there is no way to set the contents of the form to anything other than the current contents of that page.) There are various ways to do this:


 * Specify a "default" value for whatever fields you want to have a value for in the form.
 * Specify a "preload" page for the "free text" input, which will preload the free text field with the contents of that page.
 * Add 'preload=preload-page-name' to the 'query_string' value in the 'forminput' call; this will preload the entire form with the contents of that page.
 * Similarly, you can add a "preload=..." value to the query string for an 'AddPage' or 'AddData' URL.
 * Add "template-name[field-name]=field-value" to the 'query_string' value in the 'forminput' call, to set the value for a specific field.
 * Similarly, you can add a value for a specific field to the URL query string for 'AddPage' or 'AddData'.
 * Finally, you can create your own custom handling, using the 'sfEditFormPreloadText' hook. If another extension calls this hook, it can preload data however it wants. The function registered with this hook should have a header like "function-name(&$page_contents, $page_title, $form_title)".

The 'edit with form' tab
There are two ways to get the 'edit with form' tab to appear for specific pages:

Based on category
The first, and recommended, way, is to use categories. To enable a page to have a tab in this way, you must first define that page as belonging to a specific category - categories are the standard Semantic MediaWiki approach to defining a page's type. The best way to match pages with a category is to place a 'Category' tag inside the main template that defines this page type; that way, every page that uses this template will become part of this category.

Once you have done that, you should place the semantic property 'Has default form' in the page for that category; the tag should look like <tt> Has default form:: form-name</tt> (if you're using version 1.4 of Semantic MediaWiki or higher) or <tt> Has default form::Form: form-name</tt> (if you're using an earlier version of SMW). You can do this automatically if you create the category using the 'CreateCategory' page.

As an example of this approach, see the "Magazine" template source code on Discourse DB, which defines any page that includes it to be of category "Magazines"; then the "Magazines" category source code, which specifies the "Magazine" form as the default form for this category. Then, see the page for Newsweek magazine, which uses the "Magazine" template, and thus belongs to category "Magazines", and thus gets an "edit with form" tab at the top; this tab then links to editing with the "Magazine" form. And there you have it.

Based on namespace
The second possible way is to match the pages' namespace to a form. You can do that by placing a 'Has default form' property in the page defining that namespace. If, for instance, your wiki is called 'MyWiki', and the namespace you want to associate with a form is 'User', the page in which you need to add the property will probably be called 'MyWiki:User' (you may need to create this page). If the namespace you want a default form for is the main one (i.e., the one with no name, you will need to create and add this property to the page called 'MyWiki:Main', or whatever the main namespace is called in the language of this wiki. Once you've added this property, every page within that namespace will have that form associated with it, unless it already belongs to a category that has an associated form (categories take precedence over namespaces).

If a user is not allowed to edit a page that is form-editable, the tab will show up for them as "view form" instead; clicking on the tab will show the disabled form.

Configuring the editing tabs
For pages that have an "edit with form" tab, you may want the regular "edit" tab to be renamed or even removed altogether. There are flags you can set in either "LocalSettings.php" or "SF_Settings.php" to change the appearance of the editing tabs:
 * - renames the "edit with form" tab to "edit", and the "edit" tab to "edit source" (in whatever language the wiki is being viewed in)
 * - can be set, for different types of viewers, to toggle whether each type will see the regular edit tab. One common modification is to set it to false normally (i.e. for viewer type '*'), and to true for 'sysop' viewers.

If these settings are added to LocalSettings.php, they should be placed in the file after the include of Semantic Forms.

Pointing red links to 'add data' form
On MediaWiki, links to nonexistent pages are called 'red links', because they are usually colored red. By default, these links go to a page for adding this article to the wiki using the standard edit form. However, if such an article is the object of a semantic property, it's possible to get such a link to point to the correct Semantic Forms 'add data' form instead.

This is done in one to three parts:


 * if your version of MediaWiki is older than 1.13, you must make a small modification to a file in the main MediaWiki code - the code change can be found here.


 * you can add the semantic property 'Has default form' (see "The 'edit with form' tab") to the page for the property that such an article is the object of.


 * if it's possible for a property to point to more than one kind of page (i.e., pages that should be created with different forms), you can also add one or more 'Has alternate form' properties to that page, so that the user gets other possibilities when they click on the red link.

You can set either a default form, or alternate forms, or both, for a property.

As an example, see this page. Both the author and the source are red-linked, but the links take you to forms for adding these two pages (please do not actually fill out and submit these forms, because that would ruin the example). When you get to the forms for each page, you can see, at the top, that there are alternative forms that you can select for adding each page. That is enabled by 'Has default form' and 'Has alternate form' properties in the pages for both the properties 'Was written by' and 'Was published by'.

Note also that, if you've made that MediaWiki code change, and you've defined a namespace as having a default form, red-links that go to a page within that namespace will also go to the right 'add data' form, without any extra work needed.

Sometimes, when a page with red links is first created, the red links will point (incorrectly) to the standard edit URL, and not to the form URL; the correct URL will only appear at some point later. That happens because of caching on the wiki. You can very easily disable caching, if you want to get around this problem; see the instructions here.

Turning forms into tabbed sections
If you think a form is too long for users to fill out comfortably, you can turn 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  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
You can specify a form to be a partial form by adding the property "partial form" to its 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
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 '&amp;#123;', '|' with '&amp;#124;' and '}' with '&amp;#125;'.

Hosting the YUI library locally
By default, Semantic Forms retrieves the Yahoo! UI Javascript files it needs directly from yahoo.com. For various reasons, you may not want your wiki to access an external website; if so, you can download the entire library from the YUI homepage, place it on the local web server, and then, in your LocalSettings.php file, below the inclusion of Semantic Forms, add the following line:

where, in place of '...', you should have the URL of the local YUI library's "build" directory; it should include a "/" at the end.

Note that this change applies only to the Semantic Forms extension, and will not affect other extensions, like HeaderTabs, that also make use of the YUI library.

Defining new inputs
You can use hooks to define inputs, for either a new input type or a new semantic type; see Defining new inputs.

MediaWiki issues

 * If you've just set up your wiki and you want the URL of every page to look shorter and more like Wikipedia's, this short URL page explains how.


 * If a template contains section headings (like "==Section 1=="), when the template is displayed on a page each section heading will have its own "Edit" link. Such links are not desirable, since they will take the user to editing the template, rather than the actual page in question. The easiest way to avoid this problem is to place the string "" anywhere within that template; this will remove all section-edit links from any page that contains that template.

Semantic MediaWiki issues

 * If you get an error on any page reading something like "Table 'smw_relations' doesn't exist" or "Table 'smw_attributes' doesn't exist", it means you haven't installed, or haven't finished installing, the Semantic MediaWiki extension. If you've set up the SMW code and added the right lines to LocalSettings.php, probably all you need to do is create the new semantic database tables - go to 'Special:SMWAdmin' and press the button.


 * To get rid of the semantic "factbox" that appears at the bottom of most pages, add the following line to your 'LocalSettings.php' file: "$smwgShowFactbox = SMW_FACTBOX_HIDDEN;"


 * To get rid of the "error" image that appears for property values that are supposedly incorrect, add the following line to your 'LocalSettings.php' file: "$smwgInlineErrors = false;"


 * For versions of Semantic MediaWiki before 1.2, if you change the names of any semantic properties within a template, that data is not refreshed in pages that use that template until those pages are re-saved. This can be fixed by either upgrading to the latest version of SMW, or by adding a simple patch; you can find the code here. This patch should work for any previous version of SMW. After you add this patch, any save of a template will cause the semantic data to be refreshed for all pages that use that template.

Semantic Forms issues

 * You can change the way dates are entered in, and outputted by, the forms by adding the line "$wgAmericanDates = true;" to the main MediaWiki LocalSettings.php file. By default, dates are printed out as "2007/06/20"; making this change will set dates to instead be printed out as "June 20, 2007" (with the month name dependent on the language of the wiki).


 * Similarly, you can change the way times are entered and displayed. If you have a form field with input type 'datetime', by default it will use the 12-hour format, with "AM" and "PM". You can change this to 24-hour format by adding the line "$sfg24HourTime" in your LocalSettings.php file.


 * If a page (which we'll call Page A) gets transcluded in another page (which we'll call Page B), and Page A belongs to a category that's associated with a form, it can have the unfortunate side effect of making Page B a member of that category as well, thus giving Page B an "edit with form" tab at the top, even if such a tab is not appropriate. You can solve this problem by putting the category declaration in Page A within a " " block, which will make Page A a member of that category but not Page B.


 * To disable wiki-text parsing on forms, you can add the line "$sfgDisableWikiTextParsing=true" to your 'LocalSettings.php' file; if you do this, you should prevent regular users from editing forms, by restricting access to the "Form" namespace to a group like 'sysop', using an extension like NamespacePermissions.


 * To have a wiki-link to a form with a query-string value, replace the left and right brackets in the query string with '%5B' and '%5D', respectively, so the query string looks like "template-name%5Bfield-name%5D=value".


 * Semantic Forms only handles forms for adding and editing data in wiki pages. You may want forms for other purposes: fortunately, there are other form extensions you can use. EmailForm allows you to create forms for emailing data, and Simple Forms allows you to create generic forms for a variety of purposes. See also the MediaWiki forms manual for other such extensions.

Data design issues

 * One common issue is how to use categories. The Wikipedia approach is to have many categories on each page, to identify all aspects of that page's subject. Semantic MediaWiki was created in part to eliminate the need for categories, by allowing for semantic properties to represent this data. The general Semantic Forms approach is to only have one category per page, and have this category be set by the main template in the page: in other words, it is recommended that users never enter category declarations directly. Some wikis have users enter category names through forms; when this is done, it is usually for fields that represent a "tag", holding information like the subjects of a book. Even this is not recommended, though: it is better to represent such information as a semantic property like "Has subject" or "Has topic", since it keeps the data structure clean, and using semantic properties offers many built-in advantages.


 * When creating a semantic property connecting any two "classes", or pages represented by different categories, you may be unsure about which way to point the property. Usually such relationships will be of the one-to-many variety, also known as parent-child relationships, in which each page of type A has a relationship to any number of pages of type B, while each page of type B always has a relationship to exactly one page of type A. An example is countries and cities: a country can have many cities, but a city always belongs to exactly one country. In such a case, you may not know whether it should be country pages that have a "Has city" property, or city pages that have a "Belongs to country" property, or even whether both properties should exist. In this situation, it is recommended that you specify the relationship only from the child to the parent, i.e. use a "Belongs to country" property for cities and not the other way around. This is for two reasons: first, it lets you guarantee the rule that every child has exactly one parent, by setting this property through a field within the child's main template; and second, it makes page-name autocompletion more reliable, since parent pages are usually created before their children's pages are.


 * You may not be sure about whether to create one form or many for a set of related page types. For instance, in a wiki about restaurants, should you have a separate form/template/category set for regular restaurants, fast-food restaurants, diners etc., or a single form called "Restaurant", with a corresponding single template and category, that just uses a field to indicate the type of restaurant it is? A good rule of thumb is to look at the set of data that you want to be entered and displayed for each type of page. If it's the same across all the types, then you could probably use a single form/template/category set for all of them. However, if there's even one difference in the set of fields being displayed for any page type, then it probably makes sense to give such a page type its own form, template and category.


 * It is possible to create a different namespace for each page type. Wikisource does this with an "Author:" namespace, for instance, and several SMW-based wikis have one or more namespaces for different page types. Whether you do this on your wiki is up to you, but it is not recommended that you do it unless there is a real possibility of naming ambiguity otherwise. A massive wiki like Wikipedia will have a great deal of pages that require disambiguation, but most small wikis will barely have any, and so having separate namespaces will probably be a needless complication. (Currently the only common example of ambiguity in SMW wikis is "New York", which is the name of both a city and a state in the United States; the simplest solution to this problem may be to have the city be referred to as "New York City".)

Testing the extension
The best place to try out Semantic Forms is on the "Referata scratchpad" wiki, at scratchpad.referata.com. There you can create all the properties, templates, forms, etc. that you want, and see how they all interact. You do not need to register to make edits.

Sites that use Semantic Forms
Here is a small sampling of sites that use Semantic Forms in conjunction with Semantic MediaWiki, subdivided by type. For a more comprehensive listing, see the list of sites that use Semantic Forms on the Semantic MediaWiki Community Wiki, which is itself an SMW-based wiki that contains additional information on each site.

Mailing list
The mailing list for Semantic Forms is on Google Groups, at http://groups.google.com/group/semantic-forms. The list is intended for announcements, discussions about the functionality, ideas for new features, and bug reports. You must be a member to post.

Work for hire
The following people can be hired to set up a wiki that uses Semantic Forms, including the creation of forms and data structure, along with other MediaWiki components. (If you would like to do work for hire, feel free to add yourself to this list.)


 * Yaron Koren, yaron57 -at- gmail.com.
 * Asheesh Laroia, asheesh -at- asheesh.org - set up semantics at Students for Free Culture wiki, is part of the team who maintains Creative Commons Wiki. Skills: Semantic Forms.
 * bredtape -at- gmail.com - set up Wiredtape. Skills: Semantic Forms, custom extension programming, MediaWiki skins.
 * tosfos -at- yahoo.com - set up Mikomos. Skills: Semantic Forms, Semantic Drilldown.
 * DaSch - setting up Semantic MediaWiki with Extensions like Semantic Forms and Semantic Drilldown. Could also be other. Reference Web Community Wiki, look there for contact or at DaSch-Tour.
 * David Peterson, david -at- davidseth.net - Skills: Semantic Mediawiki (of course), Semantic Forms, Semantic Drilldown and all around good guy! Oh, and Semantic Web blogger for SitePoint.
 * Peder Halseide, peder -at- adeft.com - Skills: Semantic Mediawiki, Semantic Forms, Semantic Drilldown, Skinning, Data Migration, csv2wiki.pl.
 * Neoshinji [~Дт~] wikimanga.net - set up Wikimanga.net. Skills: Semantic Mediawiki, Semantic Forms. My prefered form (spanish form).

Hosting
Currently two wiki hosting sites offer support for Semantic Forms:
 * Referata, created and run by Yaron Koren. Wikis on Referata can use Semantic MediaWiki, Semantic Forms and a variety of related extensions; basic usage is free.
 * Wikia. Wikis on Wikia can request Semantic MediaWiki and Semantic Forms to be turned on (they are not enabled by default). Additional SMW-based extensions are currently not available on Wikia.

Bugs and feature requests
You can submit bug reports and requests for new features at MediaWiki's Bugzilla, here.

The current list of known bugs and requested features for Semantic Forms can be found here.

Contributing patches to the project
If you found some bug and fixed it, or if you wrote code for a new feature, please create a patch by going to the main "SemanticForms" directory, and typing:

svn diff >descriptivename.patch

Then go to the relevant bug report in Bugzilla, or create one if one doesn't exist (note, again, that Bugzilla is used for both bugs and feature requests), and attach this patch file to it.

If, for any reason, you don't wish to use Bugzilla, feel free to simply send this patch, with a description, to the Semantic Forms mailing list.

Translating
Translation of Semantic Forms is done through Betawiki. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on Betawiki, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Donate
Semantic Forms was created and is developed on a volunteer basis; all donations are welcome. You can also use donations to "fund" the development of a specific feature you would like to see added to Semantic Forms; to do that, please contact Yaron or the mailing list about it first. You can donate to the project here.