Help:Templates

From semantic-mediawiki.org

This page describes the parameter |template= that is available in many result formats. The paramater template is used to format the results via a template. Until Semantic MediaWiki 3.0.0Released on 11 October 2018 and compatible with MW 1.27.0 - 1.31.x. there used to be the result format "template"Uses a specified template to format and display the results which has been deprecated 1. The follow up format is result format "plainlist"Flexible new default result format in SMW 3.x replacing template and list formats. with the parameter |template=.

Parameters[edit]

See result format "plainlist"Flexible new default result format in SMW 3.x replacing template and list formats. for a list of parameters. The most important parameters for template usage are described here:

Parameter Comment
template=(text) defines to which template the results will be passed on (no need to use Template: before the name)
introtemplate=(text) (optional) name of a template that is called once before the output of the results (e. g. to define a table header)
outrotemplate=(text) (optional) name of a template that is called once after the output of the results (e. g. to define wiki markup for closing a table)
named args=(yes/no) If not set or no, will pass on the arguments to the templage withoug names. If set to yes, will pass on the arguments with names.
userparam=(text) A value passed into each template call.

Using templates for custom formatting[edit]

Some result formats support the use of wiki template to fully control the display of an inline query. This works for the formats

as well as other formats like

If a template is specified, all result «rows» are formatted using this template. The name of the template (without the initial «Template:») is given in the parameter template, so the query has the following general form:

{{#ask: … | format=plainlist/ol/ul | template=templatename }}

For each result in an inline query, SMW then calls the specified template, where the result and printout values are used as numbered template parameters. So a query that would display three columns when formatted as a table, will set three template parameters. These values can then be used in the template in the normal way writing {{{1}}}, {{{2}}}, etc. Each parameter refers to one "field" or column in the results that would be displayed by the inline query for each selected page. Normally the first field a query displays is the page title (see here), so parameter {{{1}}} is the page title, and {{{2}}}, {{{3}}}, ... are the other properties displayed by the query. A number of examples are given below.

The template feature allows greater flexibility in the display of the query, including:

  • Changing the order in which output is displayed, or omitting or duplicating output;
  • Displaying images depending on query results;
  • Creating links for property values;
  • Using CSS styles to vary font-size, alignment, background-color, etc. by column in tables.

If you do use a template to adjust the appearance of links, you will probably need to set the parameter | link=none | to disable SMW's automatic linking of article names. A similar effect can also be achieved by selecting the plain output format for some or all of the printouts, as described in Displaying information. Your template will then have to add [[ ]] around anything you want to be a link.

To understand how to create a template for formatting some query, it is useful to look at the query with format=table first. For example, queries that refer to a single page only (like the ones one would use with #show) hide the page title of the result page, so that the parameter {{{1}}} refers to the first printout statement. Using the printout statement ? or specifying any value for mainlabel will change this.

The following examples all use Template:Query output demo that basically contains the following wiki text:

{{{2}}} people squeeze into the {{{3}}} of {{{1}}}.

The following queries illustrate the effect of this template:

Query syntax
{{#ask:
 [[Category:City]]
 [[Area::+]]
 [[Population::+]] 
 |?Population=Inhabitants
 |?Area#km²=Size in km²
 |format=plainlist
 |template=Query output demo
 |limit=3
}}
Query result

783,364 people squeeze into the 219.00 km²84.56 sqmi
of Amsterdam. 43,765 people squeeze into the 60.00 km²23.17 sqmi
of Belleville. 3,520,061 people squeeze into the 891.85 km²344.34 sqmi
of Berlin. ... further results

In the above example you can see how the template ignores any header labels specified in the query such as «Size in km²». Yet the values the template displays do use the units specified in ?Area#km²=Size in km², and will similarly respect all given display formats (see Displaying information).

Below is a similar query sorted by population that uses format=ol to produce a numbered list:

Query syntax
{{#ask:
 [[Category:City]]
 [[Area::+]]
 [[Population::+]] 
 |?Population
 |?Area#km²
 |format=ol
 |template=Query output demo
 |limit=3
 |sort=population
 |order=desc
}}
Query result
  1. 7,825,200 people squeeze into the 1,706.80 km²659.00 sqmi
    of London. 
  2. 4,575,532 people squeeze into the 2,058.00 km²794.59 sqmi
    of Sydney. 
  3. 3,520,061 people squeeze into the 891.85 km²344.34 sqmi
    of Berlin. 

... further results

If we directly specify a single page, then normally the query results do not include the page, so to reuse the same template in the query below we must tell the query to display the page title as the first column by adding |?:

Query syntax
{{#ask:
 [[Berlin]]
 |?Population
 |?Area#km²
 |format=plainlist
 |template=Query output demo
}}
Query result

3,520,061 people squeeze into the 891.85 km²344.34 sqmi
of Berlin. 


The same can be accomplished using parser function <show>#show</show> even though this may not be the most typical use of it:

Query syntax
{{#show:
 Berlin
 |?
 |?Population
 |?Area#km²
 |format=plainlist
 |template=Query output demo
}}
Query result

3,520,061 people squeeze into the 891.85 km²344.34 sqmi
of Berlin. 

Templates may also include other parser functions such as conditionals and even queries. Example of complex query formats can be found on the following pages (external links, may change):

  • The publications on korrekt.org : all lists on this page are created with templated queries. Conditionals (#if and #ifeq) are used to change the format of a result depending on its publication type and provided data (major publications have bold-faced titles).

Usage for userparam (user parameters)[edit]

It is also possible to add a (single) extra parameter to the query. See the help page on the userparam parameter for information on how to do this.

Usage for named args (named arguments)[edit]

This parameter allows you to specify that you want named arguments, instead of numerical ones, in the formatting template.

Examples above will fetch template values through notions like {{{1|}}} but in case named args is selected values are recognized by variables names like {{{?Population|}}} or {{{?Area|}}} instead. If you specify an alternative label for the property being requested you can use that as well. Note, the question mark is required, even if you supply an alternate name.

Notes

To access {{{1}}} or {{{1|}}} using "named args=yes" you must name the default output (page name aka {{{1}}}) with:

|?#=somename

or

|?=somename

If clicking on the "further results" yields an empty query because the named args parameter is not reproduced here, you may have to remove the searchlabel parameter.

Usage of import-annotation (full parse)[edit]

Semantic MediaWiki 2.3.1Released on 4 January 2016 and compatible with MW 1.19.0 - 1.25.x. added the import-annotation option2 which is by default set to no. You have to change it to yes when you use templates to create an invert annotation or if you want to import (reuse) annotations depending on the result of your query, e.g. when using a variable with them.34 In short: mainly for annotations to be conditional when inline queries are involved.

Usage of valuesep (value separator)[edit]

Semantic MediaWiki 2.5.0Released on 14 March 2017 and compatible with MW 1.23.0 - 1.29.x. added the valuesep option5 when SMW_RF_TEMPLATE_OUTSEP feature is enabled (default) to avoid ambiguity of the sep parameter semantics. The valuesep option separates several values queried from the property annotated to a subject (pages, subojects) while sep separates values queried from the same property annotated to different subjects (pages, subojects)6. Starting with Semantic MediaWiki 2.5.3Released on 8 July 2017 and compatible with MW 1.23.0 - 1.29.x. the default value for the valuesep option was changed from a space to a comma.7 See also the related configuration parameter $smwgResultFormatsFeaturesSets whether features for some result formats should be extended.

Display of the link to further results[edit]

When using the 'template' parameter, you will only see the 'further results...' link when 'format=template'. i.e. it doesn't seem to work with 'format=ol', for example.

If you are creating a tabular output with your template you may need to use the special introtemplate and outrotemplate parameters to ensure that 'further results...' works correctly.

Limitations[edit]

The template may execute another ask query. By default the number of nested calls with "|template=" is, however, limited to 2 (see the help page on configuration parameter $maxRecursionDepthSets the recursion depth for a template output). Example: page A contains an inline query that uses template B, which itself contains an inline query that uses template C. Template C may contain yet another ask query, but not one using a template i.e. "|template=".

Examples[edit]

Related tips[edit]




This documentation page applies to all SMW versions from 3.0.0 to the most current version.
     

Help:Templates en 3.0.0


References

  1. ^  Semantic MediaWiki: GitHub issue gh:smw:2488
  2. ^  Semantic MediaWiki: GitHub pull request gh:smw:1257
  3. ^  |  Semantic MediaWiki: Sandbox example sb:smw:1255:0
  4. ^  |  Semantic MediaWiki: Sandbox example sb:smw:1255:1
  5. ^  Semantic MediaWiki: GitHub pull request gh:smw:2331
  6. ^  Semantic MediaWiki: Sandbox example sb:smw:2331
  7. ^  |  Semantic MediaWiki: GitHub pull request gh:smw:2522