Wikidata/Notes/Inclusion syntax v0.1

Obsolete

This draft is obsolete and only kept for reference. Please refer to Wikidata/Notes/Inclusion_syntax for the current version

This page describes the data inclusion syntax for the Wikibase client, by which the properties of data items can be included and rendered on a wiki page using templates.

Including Items in an Article

Basic syntax:

    {{#data-template:Infobox}}

Infobox

The given template, e.g. Infobox, will be included on the page. The data item associated with the present page is passed to the template as a special template parameter.

Note that items should be cached in memory within a request, so they don't have to be loaded multiple times should a page contain multiple calls to the {{#data-template}} function.

Additional parameters can be used to further control the behavior of the {{#data-template}} function:

    {{#data-template:Infobox
    |data_item=q332211
    |data_param=stuff
    |foo=some value
    |stuff.color=green
    }}

data_item

The data_item parameter can be used to specify the data item to include directly by id. Per default, the item associated with the present article via its article links is used. This implies that the client wiki tracks which page uses which item, to allow the relevant pages to be rerendered when the data item changes in the repository.

data_param

The data_param parameter specifies the template parameter that should be used to pass the data item to the template. So, if data_param was set to stuff, the item would be available as {{{stuff}}} in the template (see below). Per detault, the item will be passed as the {{{data}}} parameter.

foo

Arbitrary parameters such as e.g. foo are passed to the template directly, i.e. {{{foo}}} would evaluate to some value in the template.

stuff.color

If a parameter, e.g. color, is set using the data parameter name as a prefix (in this example, data_param was set to stuff, but per default, it would be data), then the given value in the data item will be overwritten (with a single unqualified, unsourced statement). So, in this example, in the template, {{{stuff.color}}} would evaluate to green because of stuff.color=green, no matter what value the color property of the item was originally.

Accessing Data Fields in a Template

The template can access the item data on several levels of granularity. First off, it can address the entire item:

    {{{data}}}

This would evaluate to the label and description of the item (in the page's content language, using Wikibase's language fallback mechanism), in plain text.

Next, individual properties can be accessed, e.g.:

    {{{data.color}}}

This will return the value of the color property, in the page's content language, as plain text. If there are multiple statements providing values for this property, the statements marked as deprecated are disregarded, and statements marked as default are preferred to statements marked as other, wich are preferred over unsourced statements.

If there are multiple equally strong statements (e.g. multiple default statements, or no default statements but multiple other statements, etc), the values would be combined for display in a manner specific to the properties data type. This would be a (comma separated) list for text values, a range for scalar types, etc. (TBD: detailed description of statement selection and combination)

Individual statements may also be adressed directly, using their citation as an identifier (this only works if there is a source given, and an id is assigned to the reference):

   {{{data.color(ACME_SURVEY_2010)}}}

This would use the value of the statement sourced from ACME_SURVEY_2010 for the color property.

Individual qualifiers may also be accessed:

    {{{data.color:accuracy}}}

Note that in case of a combined value (because of multiple, equally "strong" statements), the qualifiers are combined too, so each can have multiple values, typically rendered as a comma separated list.

Citations are special qualifiers, in that they themselves are complex objects and thus would require a template for appropriate rendering. When addressed as plain wikitext, they evaluate to a numeral representing the number of sources for this value, or the empty string if there are no sources:

    {{{data.color:source}}}

This may be useful as a condition for use with {{#if}}, etc.

Data Types

...TBD...

• localization
• precision
• item references as local links. red links?

Statement Selection and Value Combination

...TBD...

Formatting Functions

Formatting functions provide more control over the way values are rendered. They generate HTML directly, so their output can not easily be used as input to other parser functions like {{#if}}.

{{#data-value}}

This function accesses individual property values:

    {{#data-value:data.color}}

This would yield the value for the color property. The HTML rendering of the value depends on the propertie's data type. The value may be accompanied by additional information or controls, such as source references or warnings about disputes (see below). We will refer to these as "parts" of the output; parts roughly correspond to snaks (or types of snaks) in the data model.

Note that special properties such as label, alias and description, are treated as inheritely unsourced single statement properties.

Keep in mind that multiple (equally "satrong") statements may be selected for display, so their values and qualifiers get combined (see description above; TBD: detailed description of statement selection and combination).

The following parameters can be used to control the function's output:

form

Specifies in what form rendered, that is, in which HTML element the value should be wrapped.

• span: wrap in <span> tags, use <span> tags for parts
• div: wrap in <div> tags, use <span> tags for parts
• li: wrap in <li> tags, use <span> tags for parts
• dd: wrap in <dd> tags, use <span> tags for parts
• dl: wrap in <dl> tags, use <dt> and <dd> tags for parts
• td: don't wrap, use <td> for parts
• tr: wrap in <tr> tags, use <td> for parts
• trs: don't wrap, use <th> and <td> for parts
• plain: plain text with no html tags. Only shows the actual value part by default.
• wikitext: like plain, but may contain wiki markup. This is especially useful for item references, which get turned into local wiki links. Only shows the actual value part by default.
• raw: like plain, text with no html tags, but also with no processing like unit conversion, etc. Only shows the actual value part by default.

the default is inline.

style

CSS styles to apply to the outer-most HTML element.

class

CSS class to apply to the outer-most HTML element.

source

select a specific statement to use by providing a source reference identifier. source=ACME_SURVEY_2010 would select the statement with the reference ACME_SURVEY_2010. This only works if there is a source given, and an id is assigned to the reference.

show

which parts to show, and in which order, as a comma separated list. Part names given here are essentially the names of qualifiers, that is, of snak types, in the data model. Some qualifiers require special treatment, though. Some well known parts/qualifiers are:

• value: the "main" value part
• source: any source references (TBD: terse format? using <ref>? or what?)
• accuracy: the margin of error (for scalar values)
• timestamp: the point in the the value applies to
• preference: preference value(s) for the present statement(s), such as "default", "other", "unsourced" or "deprecated".
• warnings: any warnings associated with this value, using the approrpiate icons and links. This is an automatic ("virtual") part, not based on an actual qualifier/snak in the data. Typical warnings are
  • disputed if there are multiple default values, but the property is not marked as inheritely multi-value.
  • unsourced if an unsourced value is included, but the property is not marked as inheritely unsourced.
  • deprecated if a deprecated value is included
  • unreviewed (for future use with flagged revisions) the value was not yet reviewed by an established editor.
• details-link: link/button to expand the display of the property (e.g. to show a popup with all values/statements). (TBD: how to define/customize the appearance?)
• edit-link: link/button to trigger an edit interface for the given property (should show all values!)

precision

the precision for the output of scalar values, such as "1km" or "1 ounce". If not given, this may be derived based on the unit used for display, and on the value's precision qualifier.

• label: the propertie's label, in the page's content language (or the language given by the language parameter). This is defined on the propertie's description page in the repository. (TBD: use actual <label> tags?)

unit

the unit of measurement for display (implies a precision of 1/10th (TBD?!) of that unit, if the precision isn't given implicitely).

language

the language to prefer for the value, as a fallback list of language codes. Per default, the page's content language is used.

{{#data-values}}

Much like {{#data-value}}, but values are not combined but listed individually, one after the other, on order or preference.

The options are the same as for {{#data-value}}, but there are a few additional options:

max-rows

the maximum number of rows to show.

include

which preference levels to include. Preference levels are:

• default: current, approved value(s) (must be sourced)
• other: approved but not current values (must be sourced)
• unsourced: unsourced values
• deprecated: deprecated values, such as popular mistakes (sourced or unsourced)

Also, the form option is treated slightly differently:

form

Specifies in what form rendered, that is, in which HTML element the value should be wrapped.

• div: use a <div> for each value, and <span> tags for parts
• li: use a <li> for each value, and <span> tags for parts
• dd: use a <dd> for each value, and <span> tags for parts
• tr: use a <tr> for each value, and <td> for parts

the default is li.

{{#data-link}}

The {{#data-link}} function can be used to link to a data item:

    {{#data-link:data|the data item}}

This will link to the wikidata repo page of the item represented locally by the "data" parameter, using "the data item" as the link text. It's also possible to pass an action parameter, e.g. to create an edit link:

    {{#data-link:data|action=edit|the data item}}

The above syntax is useful inside templates that have been called using the {{#data-template}} function. To generate a link to a data item directly on the page corresponding to the item on the client wiki, omit the parameter name:

    {{#data-link:|action=edit|the data item}}

To link to another item using the item id, use the item parameter:

    {{#data-link:item=q332211|other item}}