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.

Other topics

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.

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.

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.

Common problems

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.

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

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

• To have a form include a template that itself has form elements (in other words, a "form template"), you just need to HTML-escape the curly brackets contained within that template - replace '{' with {', and '}' with '}'.

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

Components and Procedures

The following table includes all components and procedures that apply to the software product described on this page.

  Leave a comment to this article

Enter your message (required)

submit

Reported Bugs for this component

warning.pngThe parameter "componentName" is not optional and no default value was provided by the Wiki Web Service Definition.

Add bug for this product