Help:Template format

From semantic-mediawiki.org
Jump to: navigation, search
Template format
Uses a specified template to format and display the results
Available languages
deenzh-hans
Further Information
Provided by: Semantic MediaWiki
Added: 0.7
Removed: still supported
Requirements: none
Format name: template
Enabled by default: Indicates whether the result format is enabled by default upon installation of the respective extension. yes
Authors: Markus Krötzsch
Categories: misc
Group:
Table of Contents

INFO

The result format template is used to format the results via a template.

Parameters

Parameter Type Default Description
sep text , The separator for values
template text empty The name of a template with which to display the printouts
named args yes/no no Name the arguments passed to the template
userparam text empty A value passed into each template call, if a template is used
introtemplate text empty The name of a template to display before the query results, if there are any
outrotemplate text empty The name of a template to display after the query results, if there are any

Using templates for custom formatting

Some result formats support the use of wiki template to fully control the display of an inline query. This works for the formats template, list, ol and ul. 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=template/list/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:

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

Result: 783,364 people squeeze into the 219 km²84.556 sqmi of Amsterdam.

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

679,664 people squeeze into the 248.31 km²95.872 sqmi of Frankfurt.

… 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 Help:Displaying information).

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

{{#ask: [[Category:City]] [[Area::+]] [[Population::+]] 
| ?Population
| ?Area#km²
| format=ol
| template=Query output demo
| limit=3
| sort=population
| order=desc
}}
Result:
  1. 7,825,200 people squeeze into the 1,706.8 km²658.995 sqmi of London.
  2. 4,575,532 people squeeze into the 2,058 km²794.594 sqmi of Sydney.
  3. 3,520,061 people squeeze into the 891.85 km²344.343 sqmi of Berlin.
  4. … 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 |?

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

Result: 3,520,061 people squeeze into the 891.85 km²344.343 sqmi of Berlin.


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

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

Result: 3,520,061 people squeeze into the 891.85 km²344.343 sqmi of Berlin.


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

  • Upcoming events on semanticweb.org's main Page: the events section on this page displays only certain major events. Each such event is formatted with a template that uses another inline query to find sub-events (co-located workshops, tutorials, etc.) for a given event.
  • 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

It's possible to add a (single) extra parameter to the query. To this end, you'd add userparam=<value>. In the template, the value given after userparam= would be available as the variable {{{userparam}}}. This allows for extra re-usability for the template: you could create a single template that could be called from different queries with different results, based on the parameter. In the population example, you could decide that you'd like to use different verbs other than just "squeeze"; verbs like "fit", "live", "are located" et cetera:

{{#ask: [[Category:City]] [[Area::+]] [[Population::+]] 
| ?Population=Inhabitants
| ?Area#km²=Size in km²
| format=template
| template=Query output demo
| limit=3
| userparam=have their home
}}

Result: 783,364 people have their home into the 219 km²84.556 sqmi of Amsterdam.

3,520,061 people have their home into the 891.85 km²344.343 sqmi of Berlin.

679,664 people have their home into the 248.31 km²95.872 sqmi of Frankfurt.

… further results

Usage for named args

This parameter allows you to specify that you want named arguments in the template formatting the results (if any) instead of numerical ones.

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!

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

| ?#=somename

Display of the link to further results

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 tabular output with your template you may need to use the special introtemplate and outrotemplate parameters to ensure that 'further results...' works correctly.

Limitations

The template may execute another ask query. By default the number of nested calls with format=template is, however, limited to 2 (see the help page on $maxRecursionDepth for the configuration setting). Example: page A contains an ask query that uses template B, which itself contains an ask query that uses template C. Template C may contain yet another ask query, but not one with format=template.

Examples

Example queries

{{#ask: [[Category:City]] [[Has image::+]]
| ?Has image
| format=template
| headers=show
| link=none
| template=Demo/Template/City/Image
| introtemplate=Demo/Template/City/Image/Intro
| outrotemplate=Demo/Template/City/Image/Outro
| offset=0
| limit=20
}}

The above query will yield a table output containing images of selected cities.

Related tips



This documentation page applies to all SMW versions from 0.7 to the most current version.
      Other languages: dezh-hans

Help:Template format en 0.7