Help:Semantic templates
Semantic templates are a method of including (parts of) the additional mark-up that Semantic MediaWikiintroduces into 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,
- since templates also have other functions, such as rendering flashy infoboxes in an article, users are motivated to use them.
For these reasons, we recommend you use semantic templates when introducing semantics into a wiki.
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. Using semantic templates, you can 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²]]
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.
More advanced 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 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.svg
...
Usually the template (in thise case, Template:Infobox Settlement) displays this information in a nicely-formatted table. Obviously 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.
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 infobox template such as the one at 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 must be kept in mind when designing semantic templates.
This is also a major reason why semantic templates are not a suitable replacement for annotations in Semantic MediaWiki. There are cases where existing templates can be evaluated in a quite semantic way, but often 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 templates in general, it is very useful to allow optional parameters. On many articles, users might not want to provide all possible values of a given infobox, and it would be silly to show empty rows in such cases. Even worse, semantic templates would generate warning messages due to the fact that an empty value is annotated in such cases. To prevent this, it is useful to introduce 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. Using this extension is completely independent of Semantic MediaWiki, and you can refer to the original documentation to this extension or further information. Wikipedia contains many examples for parser functions in templates. Using parser functions typically results in difficult-to-read template code, but the simplification for users is substantial.
Annotation in a template
Support for using annotations in templates has to be enabled by the site administrator.
When an annotation tag is added to a template, then on a page that already included the template the factbox is updated, but queries do not yet take the new annotation into account. For that, for the page that includes the template, edit and save has to be applied (purge does not work). After that, also on the page with the query edit and save has to be applied.
A query in a template
A query in a template is possible, and it can contain {{PAGENAME}}, However, a query with a template parameter only works with substitution, and cannot be used in computations.
