Help:Semantic Forms

From Edge of Darkness Wiki

Semantic Forms
Jump to: navigation, search
m
m (Text replace - "Category:Help" to "{{PAGENAME}}")
 
Line 597: Line 597:
Translation of Semantic Forms is done through [http://translatewiki.net/wiki/Main_Page translatewiki.net]. The translation for this extension can be found [http://translatewiki.net/w/?title=Special:Translate&group=ext-semanticforms here]. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on [http://translatewiki.net/wiki/Project:Translator 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.
Translation of Semantic Forms is done through [http://translatewiki.net/wiki/Main_Page translatewiki.net]. The translation for this extension can be found [http://translatewiki.net/w/?title=Special:Translate&group=ext-semanticforms here]. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on [http://translatewiki.net/wiki/Project:Translator 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.
-
[[Category:Help]]
+
[[Category:Help|{{PAGENAME}}]]

Latest revision as of 22:18, 11 August 2015

Contents

Description

Semantic Forms is an extension to MediaWiki that allows users to add, edit and query 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 work without it (and you must have version 1.4 or higher of SMW).

Very simply, Semantic Forms allows you to have forms for adding, editing and querying 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.

Portions of the development of this software were funded by ontoprise GmbH and others.

Structure

Code structure

For the complete listing of files in Semantic Forms and a short description of each one, see Extension:Semantic Forms/Code structure.

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

Special pages

The extension defines various "special" MediaWiki pages:

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:

...conversely, instead of creating properties, templates, forms and categories separately, you can create them all at once, using the 'CreateClass' special page (see above). This page does not allow as much flexibility as creating all these pages independently, but it can be run much faster.

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 two-page quick reference guide, or "cheat sheet", for Semantic MediaWiki, Semantic Forms and a variety of other extensions, exists, suitable for printing. It can be found here, in PNG (image), PDF and SVG formats.

Defining forms

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:






For the 'free text' input, the allowed parameters are rows, cols, hidden, restricted, default and preload. The first five work just as they do for field declarations. The new parameter is;
  • preload=page title - Specifies a page whose contents should be preloaded into this field.
For the other standard input types, the only allowed parameters are
  • label=label name - Specifies the text associated with this input on the form.
  • class=label name - Specifies the CSS class for this input.
  • style=label name - Specifies the CSS style for this input.

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:

Data type Default input type Default size Other allowed input types
Page text (with autocompletion) 35 textarea, category
String text 35 textarea
Text textarea 5 x 30 text
Code textarea 5 x 30 text
URL text 100 textarea
Number text 10 textarea
Date date datetime (includes hours, minutes, seconds and AM/PM indicator),
datetime with timezone (includes all of those, and a timezone),
year (year only)
Enumeration (any property with defined "allowed values") dropdown radiobutton
Boolean checkbox

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:

Data type Default input type Default size Other allowed input types
Page text (with multiple-value autocompletion) 100 textarea, categories
String text 100 textarea
Enumeration checkboxes listbox

In addition, several other extensions define additional form input types: most notably, Semantic Maps defines map inputs for properties of type Geographic coordinate, while Semantic Forms Inputs defines a 'combobox' input for enumerations, a 'datepicker' input for dates, and a 'regexp' input for regular strings.

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:

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:

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

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:

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

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:

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

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

For both #arraymap and #arraymaptemplate, the string "\n" in the value of either 'delimiter' or 'new_delimiter' will get converted into a newline. It should be noted that, if you want an actual line break to appear between values, you should have two newlines (i.e, "\n\n") as the delimiter, since MediaWiki requires two newlines in order to display a line break.

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

If you want to semantically store all the data contained in these multiple-instance templates, it is recommended to use the Semantic Internal Objects extension.

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.

For uploadable fields, you can also set the default filename of the uploaded files, by setting the "upload filename=" parameter in the field definition. The value of this parameter can also include the variable "<page name>", which gets substituted with the name of the page being added or edited. So adding to the field definition the parameter "default filename=Image for <page name>", for instance, for a page called "Abc", would set the default name of any uploaded file to "Image for Abc".

You can see a demonstration of file uploading here.

Category inputs

Two input types allow for a category-tree-style input: 'category' and 'categories'. 'category' is used for a single value in a field, and uses radiobuttons; while 'categories' is used for a multiple-value field, and uses checkboxes. Both input types use the code of the MediaWiki CategoryTree extension, so this extension must be installed for these inputs to work. You also need to specify an additional parameter: "top category=...", which sets the name of the category at the top of the "tree". You can also optionally set the parameters "height=" and "width=", to set the dimensions of the box in which the category tree appears.

It should be noted that these two input types print only the names of the categories selected, without the "Category:" namespace before it; so if you want that to show up in the page as well, the template will have to add it.

If the field specifies multiple categories, and the template uses #arraymap to do it, the call to #arraymap should look something like: 

{{#arraymap:{{{Categories}}}|,|x|[[Category:x]] |<nowiki> </nowiki>}}

...in other words, you need to specify the final "delimiter" parameter for #arraymap, and make it a space, blank or something similar, to avoid printing commas between the category tags.

You can see a sample form that uses the 'category' input type 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).

If you are using the FCKeditor, you can remove the links for users to disable it in the form, if you think those links will be distracting; you can do that by adding the following to LocalSettings.php: <source lang="php">$wgDefaultUserOptions['riched_start_disabled'] = false; $wgDefaultUserOptions['riched_use_toggle'] = false;</source>

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:

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.

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}}}
<div id="wikiPreview" style="display: none; padding-bottom: 25px; margin-bottom: 25px; border-bottom: 1px solid #AAAAAA;"></div>
{{{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:'''

{{{standard input|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 both wiki-text and some limited HTML (the 'div' tag) 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.

The 'wikiPreview' div tag, by the way, is included so that, when the user hits the "Preview" button, they'll be shown the preview directly within the form page, instead of being taken to another page.

Links for adding and editing

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:

Form:


All arguments are optional. An explanation of the parameters:
  • form= - 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= - the size of the text input (default is 25).
  • default value= - the starting value of the input (default is blank).
  • button text= - the text that will appear on the "submit" button (default is up to the browser).
  • query string= - 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 "query string=namespace=User&User[Is_employee]=yes".
  • autocomplete on category= - adds autocompletion to the input, using the names of all pages in a specific category.
  • autocomplete on namespace= - adds autocompletion to the input, using the names of all pages in a specific namespace (only one can be used).

2) Use 'FormStart' - the user can go to /Special:FormStart; a form name can optionally be specified in the URL, so it looks like /Special:FormStart/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 'FormStart', you can do so by setting the URL to something like "http://mywiki.com/Special:FormStart/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={{PAGENAME}}". 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:

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:FormEdit/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".

The "start" value can have leading zeroes; a value of "001", for instance, would lead to pages that had the value "001", then "002", etc.

The "page name=" value gets parsed by the MediaWiki parser, so you can also add parser functions, pre-defined variables, etc. into the value.

Note that users must be sent to the page "Special:FormEdit/form-name" for this automatic page-setting to work; if they go instead to the regular form page, or to "Special:FormStart", 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:FormEdit/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 'form=' and 'query string=' arguments work much the same way that their equivalents in "#forminput" work, and 'link text=' works like 'button text=' (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 "post button", it will be a button that sends the query-string value(s) using "POST" instead of via the URL - this is helpful when a lot of data has to be preloaded, and it is more robust with special characters like line breaks in the query string; if it's set to blank or anything else, it will show up as a regular link.

Example:

This will link from the page, via a button, to a form, and specifically the form's "Summary" tab (assuming you've set up tabs in the form using the Header Tabs extension).

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:

The 'edit with form' tab

There are three 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 do the following two steps:

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

2) 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-name]]. You can do this automatically if you create the category using the 'CreateCategory' page.

As an example of this approach,

1) see the "Magazine" template source code on Discourse DB, which defines any page that includes it to be of category "Magazines";

2) Then see the "Magazines" category source code, which specifies the "Magazine" form as the default form for this category.

3) Finally, 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.

Within the page

Pages can set their own form, by including a "Page has default form" property placed either directly within the page or in a template that the page calls, e.g.[[Page has default form::form-name]]. This is especially useful when the category and namespace options aren't possible, such as if pages belong to multiple categories that have different default forms; or for editing category pages themselves.

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:

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 a 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 the article to the wiki using the standard edit form. However, if the red link results from a new value for a semantic property, it can point to the correct Semantic Form to add the page.

You can set either a default form, or alternate forms, or both, for a property; setting the default form can be done directly within the 'CreateProperty' page.

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. If you want to get around this problem you can very easily disable caching (see the instructions here).

Populating red-linked pages automatically

It's nice to have red links point to the right form for creating the page, but this still calls for work on the part of users - they have to click to the form, fill out the fields and save the page. This is especially bothersome when the form contains few or no fields, and/or if there are many such pages to be created. You can instead have such red-linked pages get automatically created by the system. To do this, instead of 'Has default form' or 'Has alternate form', you should add the special property 'Creates pages with form' to the property that you want pointing to those automatically-created pages. For instance, if you have pages that point with the property "Has country" to other pages, and you want those other pages to automatically be created using a form called "Country". You just need to add the following to the "Has country" property's page: 

[[Creates pages with form::Country]]

It should be noted that it may take a while for each page to be created, since page creation is done through MediaWiki "jobs", which can take anywhere from a few seconds to several hours or more to run, depending on the length of the job queue.

Querying data

Forms can also be used for querying, as opposed to adding or editing data. To do so, use the 'Special:RunQuery' page, which displays a form in a manner similar to 'Special:FormEdit', but with no associated 'target page'. Instead, when the user submits the form by hitting the "Run query" button, they see what the template looks like when displayed with the values they entered. The template that the form uses should contain one or more Semantic MediaWiki inline queries, to query data using values the user entered. You can see an example of a query form here.

In case query data need to be pre-loaded, the 'Special:RunQuery' should follow the convention Special:RunQuery/form-name?template-name[item-name]=value as in the example http://discoursedb.org/wiki/Special:RunQuery/Item_query?ItemQuerier[author]=Joe. The construction [item-name] might cause a problem in connection with the wiki markup therefore [ and ] can be replaced with %5B and %5D.

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

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 '&#123;', '|' with '&#124;' and '}' with '&#125;'.

Caching form definitions

When a form is displayed, the form definition is parsed twice - first to turn the wiki-text into HTML, and then to handle the SF-specific tags like "{{{field}}}". If a form on your wiki takes a long time to display, it might be due to the first parse, which has been known to take seconds to run. You can have form definitions be cached, so the (mostly) HTML version can be retrieved directly, eliminating the first parse. To do this, add the following line to LocalSettings.php:

<source lang="php">$sfgCacheFormDefinitions = true;</source>

You then just need to re-save the relevant form page(s).

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:

<source lang="php">$sfgYUIBase=...;</source>

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.

Common problems

MediaWiki issues

Semantic MediaWiki issues

Semantic Forms issues

You can also see other tips and hints for using Semantic Forms in the tips section of the SMW Community Wiki.

Data design issues

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.

Culture:

Politics and government:

Place listings:

Goods and services:

Science and technology:

Individual organizations:

Ontologies:

Environment:

Research:

Mailing list

Please use the Semantic MediaWiki mailing list, semediawiki-user, for any questions, suggestions or bug reports about Semantic Forms; if possible, please add "[SF]" at the beginning of the subject line, to clarify the subject matter.

Until July 2009, Semantic Forms had its own mailing list - you can see the archives here.

Work for hire

A number of people and companies can be hired to set up, or help with the design of, a wiki that uses Semantic Forms - for a listing, see the work for hire page on semantic-mediawiki.org.

Hosting

Currently three wiki hosting sites offer support for Semantic Forms:

Contributing to the project

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 semediawiki-devel mailing list.

Translating

Translation of Semantic Forms is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, 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.

Retrieved from "http://nwod.org/wiki/index.php/Help:Semantic_Forms"
Personal tools
Namespaces
Variants
Actions
Navigation
games
Toolbox