SemanticForms

From BC$ MobileTV Wiki
Jump to: navigation, search

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 (with Semantic MediaWiki 1.0) or relations and attributes (with previous versions of SMW) 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/attribute/relations, 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.


Getting started

  • Create properties, or attributes and relations. The basic building blocks of any semantic site are the connections between data, which in Semantic MediaWiki 1.0 are known as properties, and in older versions of SMW are known as attributes and relations. A property/attribute/relation is used to specify a single piece of information about the topic of this page. In the case of pre-1.0 versions of SMW, an attribute is a standalone field, while a relation represents another page on the wiki; in SMW 1.0, a property can be either, depending on whether its type is "page" or something else. Every property, attribute or relation used should be defined separately on your wiki, in either the "Property:", "Attribute:" or "Relation:" 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 have more than one template, especially if certain fields can have more than one value (see "Multiple values for the same field" below). 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 relations/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.


For more information, see the example of how these steps would be followed for an actual wiki.

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


  • 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 properties 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 - 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 properties 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 page title or free text field, standalone. The name immediately following the field declaration is the name of the field. Allowed properties 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, attribute or relation, 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.
    • 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 a field must be filled in by the user.
    • hidden - Specifies that a field will be hidden in the form: used to preserve values in edited pages.
    • restricted - Specifies that a field will be editable only by admins/sysops and disabled for all other users.
    • autocomplete on=category name - Used for text entries. Specifies that there should be Javascript "autocompletion" on this input, using a list of the pages within the specified category (and all its subcategories). Autocompletion is on by default for fields that correspond to relations; if autocomplete on is included but category name is left blank, autocompletion is disabled.
    • autocomplete on namespace=namespace name - Similar to autocomplete on=, but gets all the pages that belong to a certain namespace.
    • 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.
    • preload=page title - Specifies a page whose contents should be preloaded into this field (used only for free text field).
    • 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 are two special fields a form can contain that are not part of any templates:
  • page title - Not a form element, but is translated into a text string of the title of the page being created or edited.
  • 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 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 - the six 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). Additional properties that can be set for this tag are:
    • label=label name - Specifies the text associated with this input on the form.
So, for example, the button for "Save page" would be specified with "{{{standard input|save}}}". 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.

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
Relation text (with autocompletion) 35 textarea
String text 35 textarea
Text (SMW 1.0-only) textarea 5 x 30 text
URL text 100 textarea
Integer, Float, 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)
Enumeration (or, with SMW 1.0, 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
String textarea 5 x 30 text
Enumeration checkboxes listbox

Example

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|Additional author|label=Additional authors|multiple}}}
'''Author:''' {{{field|1|autocomplete on=Authors}}}
{{{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=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, Additional author, 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.




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.

Version

Semantic Forms is currently at version 0.9.2.