Difference between revisions of "Help:Semantic Forms"

Revision as of 16:13, 25 January 2015

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

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

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.

Overview of form settings

Defintions

                                                  │
    ┌─────────────────────────────────────────────┘
    ├ default value= …
    ├ button text= …
    ├ autocompletion ─┬ autocomplete on category=
    │                 ├ autocomplete on property=
    │                 ├ autocomplete on namespace=
    │                 └ remote autocompletion
    ├ query string=namespace=File (creates pages as “File:…”!)
    ├ popup
    └ size= 50

               │
 ┌─────────────┘
 ├ partial form - Indicates that this form is a partial form; see "Partial forms", below.
 ├ create title=title - Sets the title for the 'FormEdit' page, if the form is being used to create a new page
 ├ edit title=title - Sets the title for the 'FormEdit' page, if the form is being used to edit an existing page
 ├ query title=title - Sets the title for the 'RunQuery' page
 ├ page name=Formula <template-name[field-name]> … <unique number> - Sets a formula for automatic setting of the name of the page being added; see "Linking to forms#The one-step process".
 ├ query form at top - Places the form at the top, instead of the bottom, for the 'RunQuery' page
 └ onlyinclude free text - Indicates that the free text in the page generated by the form should be placed within an "<onlyinclude>" tag, so that pages created by the form can be transcluded in other pages without affecting those other pages' semantic properties

                        │
 ┌──────────────────────┘
 ├ template name → mandatory!!!
 ├ label= - Specifies a label to be placed in a square around the entire set of this template's fields in the form. This is especially useful if the template can have multiple instances.
 ├ add button text= - For multiple-instance templates, sets the text in the "Add another" button.
 ├ embed in field= template name[field name] - Specifies that the call(s) to this template within the generated pages will get embedded within a field of another template (i.e., "{{main template|some field={{embedded template|...its fields...}} ... }}"). It is used in conjunction with the "holds template" parameter for the 'field' tag (see below). Note that the template to be embedded must appear after the template in which it will be embedded.
 ├ multiple     → allows one template repeating multiple times on a page 
 └ strict       → use strictly template parameters

                                  │
    ┌─────────────────────────────┘
    ├ default= a default value (wiki variables don't work!)
    ├ mandatory (has to be filled by the user → CSS-class mandatoryField)
    ├ autocompletion ─┬ values from category=category
    │                 ├ values from concept=
    │                 ├ values from url=URL identifier - Used only for autocompletion. Specifies that autocompletion should be based on the values retrieved from an outside URL; see Autocompleting on outside values for how to do this.
    │                 ├ values from namespace=namespace name
    │                 ├ values from property=
    │                 └ remote autocompletion
    ├ size= 50 (length of the box in #characters)
    ├ maxlength= 60 (maximal length of the box in #characters)
    ├ class= CSS-class
    ├ hidden
    ├ placeholder=placeholder text
    ├ input type=  ─┬ textarea [with autocomplete] (+ optional: | cols= … | rows= … | autogrow)
    │               ├ text [with autocomplete] (+ optional: | size= 50)
    │               ├─┬ category - used for single value
    │               │ └ categories - used for multiple values
    │               │     └ + optionally: | height = | widht = | delimiter = | hideroot = | depth = (10 default)
    │               │
    │               ├ combobox
    │               │
    │               ├ hidden
    │               │
    │               ├ date
    │               ├ datetime (+ optional: … | include timezone | …)
    │               ├ year
    │               │
    │               ├ dropdown + values= selct1, select2, select3, select4
    │               ├ listbox + values= selct1, select2, select3, select4 (is larger)
    │               ├ checkbox
    │               └ radiobutton
    ├ list + optional: | delimiter= ; (default is , comma)
    ├ specific values: | values = one; two; three; (cannot use #ask here!!! "| values from concept= …" may be a workaround)
    │ (e.g. one; two; three;)
    │
    ├ values dependent on=template name[field name] - Can be used for inputs of type 'combobox', 'text with autocomplete' and 'textarea with autocomplete'. Specifies that the current set of allowed values for this field depends on the values a user selected, or will select, for another field in the form.
    └ show on select=selection1=>HTML-ID1 of a <div>-container;selection2=>HTML-ID2 of a <div>-container;

-------8<-- text snippets -->8----------

{{{field|TemplateParameter|input type=textarea|cols=98|rows=3|autogrow}}}

<div class="floating-form-parts">Full URI <span class="comment-gray font-weight-normal"><!-- comments --></span><br/>
{{{field|Full URI|mandatory}}}</div>

Tooltips

End of form

                   │
    ┌──────────────┘
   rows= 30
   cols= 50
   preload= a page name (only when new)
   hidden
   restricted
   editor - use the wiki editor
   autogrow
   default=

                        │
    ┌───────────────────┘
   summary     ┐
   minor edit  ┤
   watch       ┤
   save        ┤
   preview     ┤
   changes     ┤
   cancel      ┤
               + label= explicit description text
               + style= CSS style
               + style= CSS class

Setup

[[Has default form::form-name]] e.g. on a category page, namespace-definition page or ?property page
[[Has alternate form::form-name]] ?override default form
[[Page has default form::form-name]] on a page itself

Form links

                  │
    ┌─────────────┘
   form=          form name
   link text=     text of the link
   link type=     link or button or post button
   query string=  e.g.:
                  → normal form
                  template name[field name 1]=field-value-1&template name[field name 2]=field value 2
                  → multiple form
                  template name[1][field name 1]=field value 1&template name[1][field name 2]=field value 2
   target=        target page
   tooltip=       show tooltip text

Automatic editing

This needs a template and a corresponding form. Parserfunction {{#autoedit: | … }}

             │
    ┌────────┘
   link text=     text of the link
   link type=     link or button
   query string=  e.g. template-name[field-name-1]=field-value-1&template-name[field-name-2]=field-value-2
   form=          form name
   target=        target page
   reload         reload the whole page