Difference between revisions of "Help:Semantic Forms"

Revision as of 15:27, 15 April 2010 (view source) Bernhard Zelazny (Talk | contribs) ← Older edit		Revision as of 16:50, 23 April 2010 (view source) LiaVeja (Talk | contribs) Newer edit →
Line 28:		Line 28:
	*'''Defining a table for some data.''' The text starting with "<nowiki>{| border= ...</nowiki>" defines a table to display the fields journal, year, volume, and pages. These are important data which are used to generate the name of the article page.		*'''Defining a table for some data.''' The text starting with "<nowiki>{| border= ...</nowiki>" defines a table to display the fields journal, year, volume, and pages. These are important data which are used to generate the name of the article page.
	*'''Link to [[:Category:Publications]].''' We finally need a link to the special property page assigned to this form.		*'''Link to [[:Category:Publications]].''' We finally need a link to the special property page assigned to this form.
		+
		+	==Creating template, form and category through '''CreateClass command'''==
		+	A better method to create a category, a template in that category and a form for adding data is to use  '''[[[Special:CreateClass]]]''' command.
		+	This command will provide a pre-formed page for inserting the name of the template with fields, form with property and category which will be used afterward. Semantic MediaWiki will create automatic all typed properties, template which will use them and Category for the form and template also, in a single step.
	==Creating the form "Publication in journal"==		==Creating the form "Publication in journal"==

---

Revision as of 16:50, 23 April 2010

Help sections
Contents · Semantic MediaWiki · Semantic Forms
Add Ontology · Semantic links and import/export features · Import external vocabulary
Other SemanticMW extensions · Other extensions

This section gives some guidance on, and provides some examples for using the Semantic Forms extension. For more detailed descriptions see the Semantic Forms website.

Introduction

The Semantic Forms extension is used in connection with the Semantic Mediawiki extension. It is useful for creating forms which can greatly facilitate the entry of data in the semantic system. As an example we explain here the creation of a form for entering data into a semantic literature database, specifically articles published in journals. This system sorts the literature automatically in the respective journal page and allows formatting and displaying the literature in different ways.

Defining properties and data types

As explained in the Semantic Mediawiki help section the data need to be defined as properties and data types. However, you only need properties for the data which you want to call up later in queries. In our example we have created the properties
Property:Publication title
Property:Publication authors
Property:Publication journal
Property:Publication year
Property:Publication volume
Property:Publication pages
However, we do not need to create properties for other elements of the publication pages, like abstracts or external links to the full texts of the articles.

Creating categories for the form and the journals

Each form needs a special category which defines a link to the form. Here we have created the Category:Publications. In the text for this category we provide the link to our form through the following assignment:

[[Has default form::Publication in journal]]

where "Publication in journal" is the name of our form.

We further need the Category:Journals to be able to bring the articles into a structure where they can be found easily.

Creating a template for the form

The Template:Publication in journal provides formatting instructions for the data entered into the form. Each form needs a template and in order to avoid confusion the template should have the same name as the form. In this template the text between the <noinclude> and </noinclude> tags only provide some information on the data fields used by the template which should be later also included in the form. If these data elements have been defined as properties they should be here, of course, referred to with exactly the same spelling. The actual content of the template is enclosed in the <includeonly> and </includeonly> tags. The content consists of the following parts:

• Defining the format in which the data will be displayed in a page created by the form:
  1. For each data field the content to be entered into the form is enclosed in 3 curly braces, e.g. the text - '''Abstract:''' {{{Publication abstract|}}} - defines how and where the abstract of an article will appear in the final page. In this case it will appear after a line stating the journal, volume and page numbers and will be preceded by the bold text "Abstract:".
  2. For data fields like authors, title, journal, volume and page number which have been defined as properties and which we want to call-up later in semantic queries we need to format them as semantic assignments (see Semantic Mediawiki help section). This means we use the format "[[property::value]]". For example in "[[Publication title::{{{Publication title|}}}]]" The first "Publication title" is the property name and the "{{{Publication title|}}}" is what will be entered as title later in the form.
  3. The "{{#if: ....}}" constructions simply make sure none of the formatting instructions are applied if the field is left blank in the form. Note that the abstract field is not enclosed in an "{{#if: ....}}" statement. Therefore the bold text "Abstract:" will appear in the page even if no abstract has been entered, in order to encourage other users to add an abstract at a later stage.
• Defining a table for some data. The text starting with "{| border= ..." defines a table to display the fields journal, year, volume, and pages. These are important data which are used to generate the name of the article page.
• Link to Category:Publications. We finally need a link to the special property page assigned to this form.

Creating template, form and category through CreateClass command

A better method to create a category, a template in that category and a form for adding data is to use [[[Special:CreateClass]]] command. This command will provide a pre-formed page for inserting the name of the template with fields, form with property and category which will be used afterward. Semantic MediaWiki will create automatic all typed properties, template which will use them and Category for the form and template also, in a single step.

Creating the form "Publication in journal"

Often it is helpful to use the page Special:CreateForm to create a new form. However, a new form can be also created like other pages, provided the page name "Form:<form name>" is used. The script in Form:Publication in journal contains the following elements:

• An internal link for creating a new page with this form. This is the text within the <noinclude> and </noinclude> tags.
• A statement for generating the pagename automatically from the data entered. This is the text within the "{{{info|page name= ...}}}" statement. It simply states which fields in which sequence will be used to create the pagename.
• Display of the fields which have been described in the template of the form. This is the text included within the {{{for template|Publication in journal}}} and {{{end template}}} statements (if a form contains additional subforms there may be several such template statements in the form). Here the text for displaying the fields defines a table with the texts preceded by "!" are labels in the table and texts within the "{{{field| ...}}}" statements define the input boxes for each field. For each input box the statement contains the field name and other commands to define the size and function of these boxes. Useful commands for the input boxes are, for example:
  1. mandatory which ensures that this field will contain some text. If such a field is left blank the form cannot be saved and the warning "cannot be blank" appears in red beside the field.
  2. maxlength to specify the maximum number of characters or digits which can be entered into an input box. For example, since the pagename cannot exceed 255 characters, it is useful to limit the length of the fields journal, year, volume and pages (which generate the pagename).
  3. autocomplete on category provides the names of the pages which already exist in the specified category below the input box when the user starts typing; this allows the user to quickly select a given input text for this field. Here this command is used for the input box "Journal".
• Standard inputs. Several standard input boxes (e.g. the summary input box) or commands (e.g. the "preview button" or the "cancel" command) can be defined.

Calling-up the data entered

As explained in the Semantic Mediawiki help section, any data entered as properties can be called-up and reformatted in other pages. In Category:Countries we have given an example of generating a table with data on some European countries. Here we demonstrate how the publication data can be called-up automatically as lists in other pages. Two components are needed for displaying such lists:

• Querying the data. A few journals have been entered into the Category:Journals. Each journal has again a separate page for each year which contains an automatically generated list of the articles entered so far. The list of the articles is generated by a query, an "{{#ask: ... }}" statement. The first line of this statement defines which records should be filtered out by the query. For this the same format is used as for assigning data to a property. In the page Environmental Entomology (2009) this definition has the form "[[Publication journal::Environmental Entomology]][[Publication year::2009]]" and filters out all pages in which the value "Environmental Entomology" has been assigned to the property "Publication journal" and which have the assignment "2009" for the property "Publication year". The next 3 lines (e.g. "|?Publication title") simply state which fields should be displayed and 2 additional lines state that these fields should be formatted as defined in Template:Reference1. The whole query is formatted as a table.
• Defining the type of display in a template. Template:Reference1 has 2 parts:
  1. The text within the <noinclude> and </noinclude> tags are only a reminder which data (parameters) are being called-up by the respective "#ask" statement. The numbers 1 to 4 refer to the sequence of these parameters in the "#ask" statement. Number 1 is the actual filtering command ("[[Publication journal::Environmental Entomology]][[Publication year::2009]]") and is equal to the pagenames (internal links) of the pages which are returned by the query. Number 2 to 4 are equivalent to the lines "|?Publication title", "|?Publication authors", and "|?Publication year#".
  2. The text within the <includeonly> and </includeonly> tags defines a row for the query table. Each row contains only one cell and since no borders are defined the end result has the appearance of a list. The parameter numbers are enclosed in triple curly braces and define in which sequence the retrieved fields are displayed and in which format. An alternate format is defined in Template:Reference2 which is used in the query for the page Environmental Entomology (2008).

Possible problems with forms

Subsequently changing the template for a form can cause problems. E.g. the "edit with form" tab might disappear. In such cases call up the corresponding category page of the template for editing and save it again.

Multiple-valued parameter problems

Into template, using a value constraint on a Property and using a multi-valued parser function #arraymap may cause some problems on forms.

It seems that multi-valued constraint is disabled, because the form shows only a combo-box which allows only to choose one of desirable values.