Help:Semantic templates
From Edge of Darkness Wiki
|
Semantic templates |
Semantic templates are a method of including the markup that Semantic MediaWiki introduces through MediaWiki templates. This has several advantages:
- users specify annotations without learning any new syntax
- annotations are used consistently, i.e. users do not have to look for the right properties or categories when editing a page
- infobox-style templates provide data structure, by defining which values belong in which pages
- infobox-style templates also often provide a nice display for the data
For these reasons, semantic templates are a very popular way of handling semantic annotations; in many wikis, semantic data is contained only in templates.
Contents |
Simple semantic templates – an example
Templates, with or without semantics, can have a very simple form. For example, when giving the value for surface area of an astronomical object in a wiki page, you might want it to display as
- 6.088 × 1018 m²
which you can achieve by writing
6.088 × 10<sup>18</sup> m²
This is cumbersome to write, so you might develop a Template:Surface_area for areas so that editors can simply write
{{surface area|6.088|18}}
and the template expands to your desired markup.
Thus MediaWiki templates have immense value for normalizing and simplifying (once users understand the template syntax in general and particular) display in any wiki.
With the introduction of Semantic MediaWiki, you would probably want values for surface area to become semantic annotations so that they appear in the factbox and you can query them. So you might create a semantic property named Property:Surface area that uses or reuses a custom datatype Type:Area. Obviously you would like to have both the annotation and the visual appearance. You could write the following:
[[Surface area::6.088e18 m²|6.088 × 10<sup>18</sup> m²]]
the semantic annotation uses the scientific format for a number that Semantic MediaWiki can parse, and the alternate text after the pipe '|' symbol is the complex display you want.
But this is even less user friendly, and highly error-prone. Instead, you could write or adapt the Surface_area template to hide the complicated markup and perform the semantic annotation. Then, just as before editors can write
{{surface area|6.088|18}}
which is much more readable. To achieve this, Template:Surface area is coded as follows:
[[Surface area::{{{1}}}e{{{2}}} m²|{{{1}}} × 10<sup>{{{2}}}</sup> m²]]
See the sample page Sol and view its source to see this semantic template in use.
Note that the "surface area::" property in the template does not annotate the template article itself; it takes effect only on inclusion. This is because the default setting when installing Semantic MediaWiki is that SMW does not parse pages in the Template: namespace for semantic annotations . If this setting was changed (by the site admin) then you should surround the template code with <includeonly> tags to prevent the template's article itself from being annotated. As with a regular MediaWiki template, you can add text within <noinclude> tags to provide some user documentation on the template page.
Infobox-style semantic templates
Many MediaWiki sites make use of more complicated templates to present standard information. For example, Wikipedia articles on cities and villages use standard templates in which editors specify common items of information, such as this (from wikipedia:San Diego, California):
{{Infobox Settlement
|image_skyline = Sandiego_skyline_at_night.JPG
|imagesize =
|image_caption = San Diego Skyline | March 31, 2007
|official_name = City of San Diego
|settlement_type = [[City]]
|nickname = America's Finest City
|motto = Semper Vigilans ([[Latin]]: Ever Vigilant)
|image_flag = Flag of San Diego, California.png
...
Usually the template (in this case, wikipedia:Template:Infobox Settlement) displays this information in a nicely-formatted table. Such regular templatized items of information are ideal to be mapped into properties in Semantic MediaWiki, so that articles using the template will acquire semantic annotations without any changes to their pages.
The sample page California shows a simple "infobox" display template adapted to make semantic annotations.
Using semantic templates correctly
While the above pattern allows you to create all kinds of semantic templates of arbitrary complexity, there are some issues to consider.
Automatic annotation requires strict formats
You can annotate template fields automatically, but in this case the supplied values must adhere to the expected format. For example, it is a good idea to annotate the population of a city with a property of type number. However, in an infobox template such as the one at wikipedia:France, the entry supplied for population is not a single number, or even a set of numbers! Instead, there are multiple numbers and textual explanations of their meaning. Such special cases should be kept in mind when designing semantic templates.
Also, there are cases where existing templates can be evaluated in a quite semantic way, but the user still has to add semantic mark-up to make the data machine-processable. E.g. in the case of France, one might decide to leave "population" a normal text-entry, and leave it to the user to specify [[population::...]] where appropriate in this text.
Optional entries and conditionals
In the normal course of operating a wiki, most pages will probably not have their infoboxes completely filled, and you might not want to show empty rows in such cases. Blank rows can also lead to warning messages appearing on the screen, due to the fact that an empty value is annotated in such cases (although you can get around this by setting $smwgInlineErrors to 'false'). To remove rows with blank values, you can add conditionals into the template code, which include a row (and its annotation) only if a non-empty value was provided.
This can be achieved with the help of the ParserFunctions extension to MediaWiki. This extension is independent of Semantic MediaWiki, and you can refer to the original documentation to this extension or further information. Wikipedia contains many examples of parser functions in templates, as for instance in wikipedia:Template:Taxobox. Using parser functions typically results in difficult-to-read template code, but the simplification for users can be substantial.
Queries in templates
Inline queries are often added to templates as well, and they almost always contain the {{PAGENAME}} variable; see e.g. ow:Template:Ask. Such queries are often used to aggregate a set of pages that have some property pointing to the page in question, such as the template for a country page using query to show a list of each country's cities.
Annotation in a template
You can also add annotations directly to templates, i.e. assign them semantic properties. Though this is not recommended, since templates don't represent a real-world entity, it can be done, if the site administrator enables it.
Editing templates
A popular extension, Semantic Forms, lets users add and edit the contents of templates using forms. See also the list of extensions to SMW.
