Extension:Semantic Forms

From MediaWiki.org

Manual on MediaWiki Extensions
List of MediaWiki Extensions

Semantic Forms Release status: stable
Implementation	Special page
Description	An extension, based around Semantic MediaWiki, that allows users to create forms for adding and editing pages that use templates to store semantic data. Forms are defined using editable text files, written in a custom markup language, that are then parsed on-the-fly when a form is needed.
Author(s)	Yaron Koren <yaron57@gmail.com>, and others
Version	1.2.6 (July 2008)
MediaWiki	1.11.* or greater
Download	See here
Example	An auto-generated form allowing the user to edit an opinion item
Hooks used	SkinTemplateTabs LanguageGetMagic

[edit] 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, doesn't get ignored when the page is edited with a form; instead, it gets 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.

[edit] Setup

[edit] Download

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

• semantic_forms_1.2.6.tar.gz
• semantic_forms_1.2.6.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/

[edit] 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):

include_once('extensions/SemanticForms/includes/SF_Settings.php');

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':

$sfgNamespaceIndex = 150;

(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.

[edit] Authors

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

[edit] Version

Semantic Forms is currently at version 1.2.6. See the entire version history.

[edit] Languages supported

Semantic Forms has full support for English, Taiwanese Chinese, Mainland Chinese, Dutch, French, German, Persian and Brazilian Portuguese, and partial support for Afrikaans, Arabic, Bengali, Bulgarian, Catalan, Czech, Danish, Esperanto, Finnish, Galician, Greek, Gujarati, Hakka, Hawaiian, Hebrew, Hiligaynon, Hindi, Hungarian, Icelandic, Indonesian, Interlingua, Javanese, Khmer, Kinaray-a, Kotava, Limburgish, Lithuanian, Low German, Luxembourgish, Malayalam, Manx, Marathi, Eastern Mari, Niuean, Norwegian Bokmål, Norwegian Nynorsk, Occitan, Ossetic, Pashto, Polish, Portuguese, Ripuarian, Russian, Seeltersk, Serbian Cyrillic, Silesian, Church Slavonic, Slovak, Northern Sotho, Spanish, Swedish, Tajik, Tarifit, Telugu, Tetum, Turkish, Ukrainian, Upper Sorbian, Vietnamese, Volapük, Yiddish and Zazaki.

[edit] Structure

[edit] 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 three classes - SFForm, SFTemplateInForm and SFFormTemplateField - 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_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_GlobalFunctions.php - functions and constants used by the rest of the Semantic Forms code.
• 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.

/languages

• SF_Language.php - parent class for all language files
• SF_LanguageDe.php - German-language text
• SF_LanguageEn.php - English-language text
• SF_LanguageFa.php - Persian-language text
• SF_LanguageFr.php - French-language text
• SF_LanguageHe.php - Hebrew-language text
• SF_LanguageNl.php - Dutch-language text
• SF_LanguagePt_br.php - Brazilian-Portuguese-language text
• SF_LanguageZh_cn.php - Mainland-Chinese-language text
• SF_LanguageZh_tw.php - Taiwanese-Chinese-language text
• 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_UploadWindown.php - defines the 'UploadWindow' special page

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

[edit] 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.

[edit] 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.

[edit] Example

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

[edit] Defining forms

[edit] 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:

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

• for template - 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=label text - Specifies a label to be placed in a square around the entire set of this template's fields in the form.
  • multiple - 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.
  • chooser=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.
  • chooser caption=caption - Sets the caption in the form's dropdown for adding instances of this template; must be set in conjunction with chooser option.
  • strict - Specifies that only fields in the form that correspond to fields used by the template should get turned into form elements.

• end template - Ends the range of a template. There are no parameters for this tag.

• field - Specifies a field to be placed in a form. It can be either a template field or, if it's the free text field, standalone. The name immediately following the field declaration is the name of the field. Allowed parameters of this tag are:
  • input type=input type - Specifies the type of input this field will have in the form: allowed values are text, textarea, date, datetime, datetime with timezone, radiobutton, checkbox, listbox and checkboxes. If a field corresponds to a semantic property, the form will usually have the correct input type by default; otherwise the default is text.
  • size=size - Used for text entries. Specifies the width of the text entry.
  • maxlength=maximum length - Used for text entries. Specifies the maximum allowed length of the input.
  • rows=num rows - Used for textarea entries. Specifies the number of rows.
  • cols=num cols - Used for textarea entries. Specifies the number of columns.
  • mandatory - Specifies that this field must be filled in by the user.
  • hidden - Specifies that this field will be hidden in the form: used to preserve values in edited pages.
  • restricted - Specifies that this field will be editable only by admins/sysops and disabled for all other users.
  • uploadable - 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.
  • autocomplete - 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".
  • no autocomplete - Disables autocompletion for a field, if it's on by default.
  • autocomplete on property=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.
  • autocomplete on category=category name - Similar to autocomplete on property=, but autocompletes on the names of pages within the specified category (and all its subcategories).
  • autocomplete on namespace=namespace name - Similar to autocomplete on category=, but autocompletes on the names of pages that belong to a certain namespace.
  • remote autocompletion - 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.
  • default=default value - Specifies a default value for this field. For date-related fields, default=now will set the value to the current date and possibly time.
  • values=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.
  • preload=page title - Specifies a page whose contents should be preloaded into this field (used only for free text field).
  • list - Specifies that this field contains a list of values; used for autocompletion.
  • delimiter=delimiter - Specifies the delimiter character or string this field should use, if it represents a list of values; the default is ",".
  • class=class name - Specifies a CSS class that the input for this field should have.

There is one special field a form can contain that is not part of any template:

• free text - A textarea that holds all the text on the page that does not fit into any of the templates specified in the form. Allowed properties for this field are rows, cols, hidden, restricted, default and preload.

• choosers - 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.

• standard input - One of seven inputs that, by default, appear at the bottom of every form. The text immediately after "standard input|" is the name of this input; see Defining the bottom of the form. Allowed parameters for this tag are:
  • label=label name - Specifies the text associated with this input on the form.

[edit] 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:

[edit] 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 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.

[edit] 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:

{{#arraymap:value|delimiter|var|formula|new_delimiter}}

The function splits the value by the delimiter, then, for each one, applies the same mapping that 'new_value' does to 'var', and finally joins all the values again using the new delimiter. ('delimiter' defaults to "," and 'new_delimiter' defaults to ", " if they are not set.) So, 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:

{{#arraymap:{{{author|}}}|,|x|[[Has author::x]]}}

Essentially this function 'maps' the property tag onto each comma-delimited value in the field. 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:

{{#arraymaptemplate:value|template|delimiter|new_delimiter}}

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

[edit] 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).

[edit] 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.

[edit] 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 "{{{standard input|save|label=Save this page}}}", which would place the button where it was defined, with the text on the button reading "Save this page". If no standard input 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.

[edit] Sample form

Here is the source code for the 'Item' form definition page at Discourse DB:

{{{info|add title=Add an opinion item|edit title=Edit an opinion item}}}
{{{for template|Item}}}
{| class="formtable"
! Author:
| {{{field|author|mandatory}}}
|-
! Source:
| {{{field|source|mandatory}}}
|-
! Date:
| {{{field|date}}}
|-
! URL:
| {{{field|url}}}
|-
! Quote:
| {{{field|quote|input type=textarea|}}}
|}
{{{end template}}}

{{{for template|Opinion|label=Opinions for this item|multiple}}}
'''Topic:''' {{{field|1}}}

'''Position:''' {{{field|2|size=55}}}

'''Stance:''' {{{field|3|size=10}}}
{{{end template}}}

{{{for template|Reference|label=Previous opinion items this item refers to|multiple}}}
'''Item name:''' {{{field|1|autocomplete on category=Items}}}
{{{end template}}}

'''Free text:'''
{{{field|free text}}}


{{{standard input|summary}}}

{{{standard input|minor edit}}} {{{standard input|watch}}}

{{{standard input|save}}} {{{standard input|preview}}} {{{standard input|changes}}} {{{standard input|cancel}}}

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.

[edit] Links for adding and editing

[edit] 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.

[edit] The two-step process

There are two ways to let users add data in this way:

• 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 from created by the 'CreateForm' page. Here is the generic call for the tag:

{{#forminput:form_name|size|value|button_text|query_string}}

All arguments are optional. 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), and value is the starting value of the input (default is blank). button_text is the text that will appear on the "submit" button, and query_string is the set of values that you want passed in through the query string to the form.

• 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 no longer recommended.)

[edit] 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".

[edit] 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=Semantic Forms". This will prepend a "current-page-name/" onto the beginning of the page name that the user types in.

[edit] 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
• '<unique number>' - 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:

{{#formlink:form_name|link_text|link_type|query_string}}

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.

[edit] 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" field, 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'.

[edit] The 'edit with form' tab

There are two ways to get the 'edit with form' tab to appear for specific pages. 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 [[Has default form::Form:form-name]]. 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.

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.

[edit] 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:

• $sfgRenameEditTabs - renames the "edit with form" tab to "edit", and the "edit" tab to "edit source" (in whatever language the wiki is being viewed in)
• $wgGroupPermissions[...]['viewedittab'] - 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.

[edit] 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.

[edit] Other topics

[edit] 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 "<headertabs/>" 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.

[edit] Partial forms

You can specify a form to be a partial form by adding the property "partial form" to its {{{info}}} 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".

[edit] 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 edit the file /includes/SF_Settings.php in the Semantic Forms directory, to modify the variable $sfgYUIBase to be the URL of the local YUI library's "build" directory.

[edit] 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.

[edit] Common problems

[edit] 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 "__NOEDITSECTION__" anywhere within that template; this will remove all section-edit links from any page that contains that template.

[edit] 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;"

• If you have a property of type "Page" that is an enumeration, and it generates strange-looking error messages like "'Blue' is not in the list of possible values (Red, Blue, Yellow) for this property" (i.e., a value that is part of the enumeration is not recognized as such), that is due to a bug in old versions of SMW 1.0. If you upgrade your version of SMW, the error message should go away.

• 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.

[edit] Semantic Forms issues

• You can change the way dates are 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).

• 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 "<noinclude>" block, which will make Page A a member of that category but not Page B.

• If you are upgrading your site from SMW 0.7 (or an earlier version) to SMW 1.0, and you have the property "Has default form" defined, make sure that you add to it the type declaration "[[Has type::Page]]".

• If you upgraded your copy of Semantic Forms from one before 0.9 to any afterwards, you may see strange formatting in some or all of your forms; that is because wiki-text parsing was added in version 0.9. You should be able to get rid of the formatting problems in two steps: remove the spaces from the beginning of every line in the form definition, and replace the line that looks like "<fieldset><legend>Description of magazine</legend>", plus the closing "</fieldset>" tag (and any other lines that look like that) with something like "'''Free text:'''"; for some reason, the MediaWiki parser does not like the "fieldset" and "legend" HTML tags. You can also disable wiki-text parsing instead; see the next item.

• 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.

• If you click on the "edit with form" tab for a page and you get a message reading "Error: No form page was found at..", but the form does in fact exist, that is due to a bug in old versions of SMW 1.0. You should upgrade to the latest version of SMW, then re-save the page of any category that has a "Has default form" call linking to such a form; make sure that you make a small change to the category page first, or else it won't really be re-saved.

• If you click on the "edit with form" tab and it just displays the regular page instead of a form, and you have the Halo extension installed, that is due to a bug in older versions of Halo; you can either upgrade your version, or apply the change seen here, to fix this problem.

• 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.

[edit] 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.

[edit] Sites that use Semantic Forms

This is not a comprehensive listing, but here are some sites that use Semantic Forms in conjunction with Semantic MediaWiki, listed by language, and subdivided by type for English-language wikis:

[edit] 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.

[edit] 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.)

• 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.

[edit] Hosting

Currently only one wiki hosting site offers 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.

[edit] Contributing to the project

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] See also

• Simple Forms
• Semantic MediaWiki

Languages:

English  • ‪中文(繁體)‬