3,103
edits
Changes
→Using templates for custom formatting
</blockquote>
</blockquote>
[http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki] includes a simple query language for [http://semantic-mediawiki.org/wiki/Help:Semantic_search semantic search], so that users can directly request certain information from the wiki. Readers who do not wish to learn the query syntax can still profit from this feature: '''inline queries''' dynamically include query results into pages. So queries created by a few editors can be consumed by many readers.
Inline queries are similar to other semantic search features, and can also be restricted on a site in order to ensure sufficient performance. Since inline queries exploit the existing caching mechanisms of [[MediaWiki]], most requests for a page with such dynamic contents can be served without any performance impact whatsoever.
Inline queries are similar to other semantic search features, and can also be restricted on a site in order to ensure sufficient performance. Since inline queries exploit the existing caching mechanisms of [http://mediawiki.org/wiki/MediaWiki | MediaWiki], most requests for a page with such dynamic contents can be served without any performance impact whatsoever.
== Introduction to #ask ==
== Introduction to #ask ==
The basic way of writing an inline query is to use the parser function <tt>#ask</tt>. The query string (See [[Help:Selecting pages|selecting pages]] for syntax) and any [[Help:Displaying information|printout statements]] are directly given as parameter, like in the following example:
The basic way of writing an inline query is to use the parser function <tt>#ask</tt>. The query string (See [http://semantic-mediawiki.org/wiki/Help:Selecting_pages selecting pages] for syntax) and any [http://semantic-mediawiki.org/wiki/Help:Displaying_information|printout statements] are directly given as parameter, like in the following example:
<pre><nowiki>
<pre><nowiki>
}}
}}
It is common to put the query as the first parameter behind <tt>#ask:</tt>. All other parameters are separated by <tt>|</tt>, just like for other [[meta:Help:Parser_function|parser functions]]. The exact formatting of the inline query is not essential, but it is good to use line breaks to make it more readable to other editors. As with all templates, one line per parameter, starting with the <tt>|</tt> is most accepted in practice.
It is common to put the query as the first parameter behind <tt>#ask:</tt>. All other parameters are separated by <tt>|</tt>, just like for other [http://semantic-mediawiki.org/wiki/meta:Help:Parser_function parser functions]. The exact formatting of the inline query is not essential, but it is good to use line breaks to make it more readable to other editors. As with all templates, one line per parameter, starting with the <tt>|</tt> is most accepted in practice.
Note that all the arguments to the #ask: function are ignored by the page parsing, hence the above example does not add a category or a «located in» property annotation to this page. A few more things to note are:
Note that all the arguments to the #ask: function are ignored by the page parsing, hence the above example does not add a category or a «located in» property annotation to this page. A few more things to note are:
* The format of the results display changes when you request display of additional properties. SMW picks an appropriate default format for query results, but you also have detailed control of the appearance of query results.
* The format of the results display changes when you request display of additional properties. SMW picks an appropriate default format for query results, but you also have detailed control of the appearance of query results.
Knowing the basics of [[Help:Selecting pages|query string]] and [[Help:Displaying information|printout statements]] therefore is enough to write many kinds of queries. But there are many cases where the standard table output of a query may not be the best choice, or where further settings are desired (like the maximum number of results that should be displayed). For this purpose, inline queries have a number of other possible parameters that one can use to control their appearance in detail. The general syntax for <tt>#ask</tt> therefore is the following:
Knowing the basics of [http://semantic-mediawiki.org/wiki/Help:Selecting_pages query string] and [http://semantic-mediawiki.org/wiki/Help:Displaying_information printout statements] therefore is enough to write many kinds of queries. But there are many cases where the standard table output of a query may not be the best choice, or where further settings are desired (like the maximum number of results that should be displayed). For this purpose, inline queries have a number of other possible parameters that one can use to control their appearance in detail. The general syntax for <tt>#ask</tt> therefore is the following:
<nowiki>{{</nowiki>#ask: <i>argument 1</i> | <i>argument 2</i> | … <nowiki>}}</nowiki>
<nowiki>{{</nowiki>#ask: <i>argument 1</i> | <i>argument 2</i> | … <nowiki>}}</nowiki>
Most of this page explains the various arguments one may use in inline queries.
Most of this page explains the various arguments one may use in inline queries.
Prior to Semantic MediaWiki 1.0 there was a different syntax for inline queries using an <tt><nowiki><ask></nowiki></tt> tag, which is still enabled on some wikis. Please see the [[Help:Inline queries 0.7|old documentation page]] for details on this feature. It is strongly recommended to use only the new syntax now.
Prior to Semantic MediaWiki 1.0 there was a different syntax for inline queries using an <tt><nowiki><ask></nowiki></tt> tag, which is still enabled on some wikis. Please see the [http://semantic-mediawiki.org/wiki/Help:Inline_queries_0.7 old documentation page] for details on this feature. It is strongly recommended to use only the new syntax now.
== The #show parser function ==
== The #show parser function ==
In general, an inline query is a request to find a number of '''pages''' that satisfy certain requirements. The query must answer three questions:
In general, an inline query is a request to find a number of '''pages''' that satisfy certain requirements. The query must answer three questions:
# Which pages are requested? ([[Help:Selecting pages|query description]])
# Which pages are requested? ([http://semantic-mediawiki.org/wiki/Help:Selecting_pages query description])
# What information should be displayed about those pages? ([[Help:Displaying information|printout statements]])
# What information should be displayed about those pages? ([http://semantic-mediawiki.org/wiki/Help:Displaying_information printout statements])
# How should the results be formatted within the page?
# How should the results be formatted within the page?
| <tt>sort</tt>
| <tt>sort</tt>
| property name or a list of property names separated by ,
| property name or a list of property names separated by ,
| name of properties to use for sorting queries (see [[Help:Selecting pages]])
| name of properties to use for sorting queries (see [http://semantic-mediawiki.org/wiki/Help:Selecting_pages Selecting pages])
|-
|-
| <tt>order</tt>
| <tt>order</tt>
| <tt>ascending</tt>/<tt>asc</tt>, <tt>descending</tt>/<tt>desc</tt>/<tt>reverse</tt>,<br />or a list of those if more than one property is used for sorting
| <tt>ascending</tt>/<tt>asc</tt>, <tt>descending</tt>/<tt>desc</tt>/<tt>reverse</tt>,<br />or a list of those if more than one property is used for sorting
| defines how results should be ordered, only applicable if <tt>sort</tt> is used, <tt>ascending</tt> is the default (see [[Help:Selecting pages]])
| defines how results should be ordered, only applicable if <tt>sort</tt> is used, <tt>ascending</tt> is the default (see [http://semantic-mediawiki.org/wiki/Help:Selecting_pages Selecting pages]])
|-
|-
| <tt>headers</tt>
| <tt>headers</tt>
=== Sorting results ===
=== Sorting results ===
It has been explained in [[Help:Selecting pages]] that query results can be ordered by one or more properties. As explained there, [[Special:Ask]] has additional input fields to specify sort properties and ordering. In inline queries, sort properties are defined with the parameter <tt>sort</tt>, and the order can be set with the parameter <tt>order</tt>. The value of <tt>order</tt> should be «<tt>ascending</tt>» or «<tt>descending</tt>», or one of the short forms «asc» and «desc», or «reverse». You can also set the value to «<tt>random</tt>» (or «<tt>rand</tt>») for ordering results in an essentially random way (this feature can be disabled by the site administrator, see [[Help:Configuration|Configuration]]). An example is the following query for the three largest cities in Germany:
It has been explained in [http://semantic-mediawiki.org/wiki/Help:Selecting_pages selecting pages] that query results can be ordered by one or more properties. As explained there, [[Special:Ask]] has additional input fields to specify sort properties and ordering. In inline queries, sort properties are defined with the parameter <tt>sort</tt>, and the order can be set with the parameter <tt>order</tt>. The value of <tt>order</tt> should be «<tt>ascending</tt>» or «<tt>descending</tt>», or one of the short forms «asc» and «desc», or «reverse». You can also set the value to «<tt>random</tt>» (or «<tt>rand</tt>») for ordering results in an essentially random way (this feature can be disabled by the site administrator, see [http://semantic-mediawiki.org/wiki/Help:Configuration Configuration]). An example is the following query for the three largest cities in Germany:
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
}}</pre>
}}</pre>
As explained in [[Help:Selecting pages]], sorting conditions may impose restrictions on the set of query results. In the above case, only German cities that have a value for population are considered. If more than one property is used for sorting, the parameters <tt>sort</tt> and <tt>order</tt> can be set to lists of property names and orders, repsectively, separated by commas. The following is an example:
As explained in [http://semantic-mediawiki.org/wiki/Help:Selecting_pages Selecting pages], sorting conditions may impose restrictions on the set of query results. In the above case, only German cities that have a value for population are considered. If more than one property is used for sorting, the parameters <tt>sort</tt> and <tt>order</tt> can be set to lists of property names and orders, repsectively, separated by commas. The following is an example:
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
Queries that return more than just the selected articles (e.g. the population in the above example) will display labels that describe the various output fields. By default, the label just displays the name of the requested property, or the text «Category» if categories are displayed. Labels for properties normally display as a link to the respective pages in the Property: namespace.
Queries that return more than just the selected articles (e.g. the population in the above example) will display labels that describe the various output fields. By default, the label just displays the name of the requested property, or the text «Category» if categories are displayed. Labels for properties normally display as a link to the respective pages in the Property: namespace.
In the table format, the labels appear as column headers. In other formats, the labels might appear right before the output fields. The texts used for these labels can be controlled as explained in [[Help:Displaying information]], using the equality symbol after printouts. Example:
In the table format, the labels appear as column headers. In other formats, the labels might appear right before the output fields. The texts used for these labels can be controlled as explained in [http://semantic-mediawiki.org/wiki/Help:Displaying_information Displaying information], using the equality symbol after printouts. Example:
<pre>{{#ask: [[Category:City]]
<pre>{{#ask: [[Category:City]]
== Result formats ==
== Result formats ==
The parameter <tt>format</tt> determines how the results of a query are displayed in the article. If it is omitted, all queries are displayed as tables (format <tt>table</tt>), unless there would be only one column, in which case the results are displayed as a comma-separated list (format <tt>list</tt>). In addition to the formats provided by SMW, [[Help:SMW extensions|extensions]] can provide additional formats; see [http://www.mediawiki.org/wiki/Extension:Semantic_Result_Formats Semantic Result Formats] and [http://www.mediawiki.org/wiki/Extension:Semantic_Maps Semantic Maps] for two such extensions. The following formats are available in SMW by default:
The parameter <tt>format</tt> determines how the results of a query are displayed in the article. If it is omitted, all queries are displayed as tables (format <tt>table</tt>), unless there would be only one column, in which case the results are displayed as a comma-separated list (format <tt>list</tt>). In addition to the formats provided by SMW, [http://semantic-mediawiki.org/wiki/Help:SMW_extensions extensions] can provide additional formats; see [http://www.mediawiki.org/wiki/Extension:Semantic_Result_Formats Semantic Result Formats] and [http://www.mediawiki.org/wiki/Extension:Semantic_Maps Semantic Maps] for two such extensions. The following formats are available in SMW by default:
{| class="smwtable"
{| class="smwtable"
! Additional parameters (usually optional)
! Additional parameters (usually optional)
|-
|-
| [[Help:List format|<tt>list</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:List_format <tt>list</tt>]
| Comma-separated list, with additional outputs shown in parentheses
| Comma-separated list, with additional outputs shown in parentheses
| <tt>sep</tt>, <tt>template</tt>
| <tt>sep</tt>, <tt>template</tt>
|-
|-
| [[Help:List format|<tt>ol</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:List_format <tt>ol</tt>]
| Ordered list, with additional outputs shown in parentheses
| Ordered list, with additional outputs shown in parentheses
| <tt>sep</tt>, <tt>template</tt>
| <tt>sep</tt>, <tt>template</tt>
|-
|-
| [[Help:List format|<tt>ul</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:List_format <tt>ul</tt>]
| Bulleted list, with additional outputs shown in parentheses
| Bulleted list, with additional outputs shown in parentheses
| <tt>sep</tt>, <tt>template</tt>
| <tt>sep</tt>, <tt>template</tt>
|-
|-
| [[Help:Table format|<tt>table</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Table_format <tt>table</tt>]
| Tabular output
| Tabular output
|
|
|-
|-
| [[Help:Table format|<tt>broadtable</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Table_format <tt>broadtable</tt>]
| Tabular output, where the table is as wide as the article.
| Tabular output, where the table is as wide as the article.
|
|
|-
|-
| [[Help:Category format|<tt>category</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Category_format <tt>category</tt>]
| List in columns, with first letters as section headers, in the style of MediaWiki category pages
| List in columns, with first letters as section headers, in the style of MediaWiki category pages
| <tt>sep</tt>, <tt>template</tt>, <tt>delim</tt>, <tt>userparam</tt>, <tt>columns</tt>
| <tt>sep</tt>, <tt>template</tt>, <tt>delim</tt>, <tt>userparam</tt>, <tt>columns</tt>
|-
|-
| [[Help:Embedded format|<tt>embedded</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Embedded_format <tt>embedded</tt>]
| Embed selected articles.
| Embed selected articles.
| <tt>embedonly</tt> (if set, don't show article link), <tt>embedformat</tt> (can be ol, ul, h1, h2 ..., h6)
| <tt>embedonly</tt> (if set, don't show article link), <tt>embedformat</tt> (can be ol, ul, h1, h2 ..., h6)
|-
|-
| [[Help:Template format|<tt>template</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Template_format <tt>template</tt>]
| Print results by passing result fields as parameters to a given template.
| Print results by passing result fields as parameters to a given template.
| <tt>template</tt> (mandatory)
| <tt>template</tt> (mandatory)
|-
|-
| [[Help:Count format|<tt>count</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Count_format <tt>count</tt>]
| Just the number of results (a count of the number of matching pages), instead of the results themselves
| Just the number of results (a count of the number of matching pages), instead of the results themselves
|
|
|-
|-
| [[Help:Debug format|<tt>debug</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Debug_format <tt>debug</tt>]
| Debugging information for analysing problems in query answering.
| Debugging information for analysing problems in query answering.
|
|
|-
|-
| [[Help:RSS format|<tt>rss</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:RSS_format <tt>rss</tt>]
| Print links to RSS feeds for query results.
| Print links to RSS feeds for query results.
| <tt>title</tt>, <tt>description</tt>
| <tt>title</tt>, <tt>description</tt>
|-
|-
| [[Help:CSV format|<tt>csv</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:CSV_format <tt>csv</tt>]
| Export result table as CSV (comma-separated values), ''available since [[SMW 1.2.1]]''
| Export result table as CSV (comma-separated values), ''available since [http://semantic-mediawiki.org/wiki/SMW_1.2.1 SMW_1.2.1]''
| <tt>sep</tt>
| <tt>sep</tt>
|}
|}
== Using templates for custom formatting ==
== Using templates for custom formatting ==
Some of the above result formats support the use of wiki [[meta:Help:Template|template]] to fully control the display of an inline query. This works for the formats <tt>template</tt>, <tt>list</tt>, <tt>ol</tt> and <tt>ul</tt>. 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 <tt>template</tt>, so the query has the following general form:
Some of the above result formats support the use of wiki [http://semantic-mediawiki.org/wiki/meta:Help:Template template] to fully control the display of an inline query. This works for the formats <tt>template</tt>, <tt>list</tt>, <tt>ol</tt> and <tt>ul</tt>. 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 <tt>template</tt>, so the query has the following general form:
<nowiki>{{#ask:</nowiki> ... | format=template/list/ol/ul | template=''templatename'' }}
<nowiki>{{#ask:</nowiki> ... | format=template/list/ol/ul | template=''templatename'' }}
}}
}}
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 <tt>?Area'''#km²'''=Size in km²</tt>, and will similarly respect all given display formats (see [[Help:Displaying information]]).
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 <tt>?Area'''#km²'''=Size in km²</tt>, and will similarly respect all given display formats (see [http://semantic-mediawiki.org/wiki/Help:Displaying_information Displaying information]).
Below is a similar query sorted by population that uses <tt>format=ol</tt> to produce a numbered list.
Below is a similar query sorted by population that uses <tt>format=ol</tt> to produce a numbered list.
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):
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):
* [[semanticweb:Main Page|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.
* [Displaying informationsemanticweb:Main_Page|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.
* [http://korrekt.org/page/Publications Publications on korrekt.org]: all lists on this page are created with templated queries. Conditionals (<tt>#if</tt> and <tt>#ifeq</tt>) are used to change the format of a result depending on its publication type and provided data (majorpublications have bold-faced titles).
* [http://korrekt.org/page/Publications Publications on korrekt.org]: all lists on this page are created with templated queries. Conditionals (<tt>#if</tt> and <tt>#ifeq</tt>) are used to change the format of a result depending on its publication type and provided data (majorpublications have bold-faced titles).