Help:Semantic templates

Semantic templates are templates containing Semantic MediaWiki markup. Such use of SMW markup confers several advantages:


 * Editors specify annotations without learning any new syntax.
 * Annotations are used consistently, i.e. editors do not have to look for the right properties or categories whenever they edit a page.
 * Since templates also have other functions, such as rendering flashy infoboxes in an article, editors are easily motivated to use them.

For these reasons, editors having advanced knowledge of template building are strongly encouraged to include SMW markup--within reason! A template that, for example, includes a property of Type:URL can clutter a factbox with a hundred nearly indecipherable external links if an editor uses it a hundred times in an article.

In the CreationWiki, semantic templates are available by default. The administration has tested semantic markup within templates, and it works.

Simple semantic templates – an example
Templates, with or without semantics, can have a very simple form. For example, when writing the Admin Contact email address on the Community Portal, we originally used the code

[mailto:admin@creationwiki.net Admin Contact]

to get "[mailto:admin@creationwiki.net Admin Contact]" as a result. The text after the space is used for display, so that the "mailto:" is hidden. To annotate emails, a semantic property of type Email is appropriate. On CreationWiki, this property is already called Property:Email_to. As an example of its use, we have rewritten the above code:

Admin Contact

which now displays simply as "Admin Contact" in the portal.

But we can achieve the same result with semantic templates, and obviate the need to remember semantic-annotation syntax. We might create a template called Template:Email that would hide the markup and allows users to write

admin@creationwiki.net@Admin Contact

which is much more readable. To achieve this, we could code the template as follows:

Email to::.

Note that the "email to::" property assignment does not annotate the template page, and takes effect only on inclusion. This is the default setting when installing Semantic MediaWiki. But to make sure of this, you should include the template code into tags to prevent it from being annotated itself. Likewise, you use text in tags to provide some user documentation on the template page.

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, you should annotate the melting point of a chemical element with a property of type Temperature. But in an infobox template the entry supplied for any given property might not be a single number, or even a set of numbers! Instead it might have mutliple numbers and textual explanations of their meaning. Such special cases must be kept in mind when designing semantic templates.

Furthermore, in some cases existing templates can be evaluated semantically, but often the user must still add semantic mark-up to make the data machine-processable. Suppose, for example, a template developer decided to leave "melting point" a normal text-entry (to accommodate chemical compounds that never melt at all, but rather decompose when heated), and leave it to the user to specify Melting point::... where appropriate in this text.

Optional entries and conditionals
Optional parameters are very useful in templates. On many articles, users might not want to provide all possible values of a given infobox or other template, and showing empty rows in such cases would be silly. Worse yet, semantic templates would generate warning messages because an empty value is annotated in such cases. To prevent this, a template developer should introduce conditionals into the template code, which include a row (and its annotation) only if a non-empty value was provided.

CreationWiki has the ParserFunctions extension installed. ParserFunctions supports multiple conditional and switching functions. The list of supported functions is in fact available on Special:Version under the heading of "Extension Functions."

For an example of the use of parser functions to handle optional entries and semantic annotation of parameter values, see Template:Infobox Planet and pages like Earth that use it.

Annotation in a template
Support for using annotations in templates is enabled and has been tested and proved.

When an annotation tag is added to a template, then on a page that already includes the template the factbox will update, but such pages will not browse or lend themselves to queries. The pages will browse, however, after their next edit and save. (The purge action will not serve for this.)