Module:WikidataIB/doc

This module is designed specifically to implement a mechanism which moves control of whether Wikidata values are used in a template from the template coder at the template design level to the editor at the article level. It is only intended to be used inside an infobox or other template.

One of the two sandboxes should be used for testing anything other than trivial amendments.

Test examples for the main module and the two sandboxes are available.

Overview
The module provides these calls specifically for use in infoboxes at present: The obsolete call getSourcedValue has now been removed as it is redundant to getValue which can do the same job using the true parameter (which is set by default). The deprecated call getPreferredValue is still retained, but should be replaced by.
 * 1)   - main call, used to get the value(s) of a given property
 * 2)   - given: (1) a property; (2) its value; (3) a qualifier's propertyID, returns values which match
 * 3)   gets the value of a property which has a qualifier with a given entity value
 * 4)   gets the value of a property which has a qualifier P407("language of work or name") whose value has the given language code
 * 5)   gets the value of a property which has a reference "stated in" (P248) whose value has the given entity-ID
 * 6)   if the value(s) of prop1 are of type "wikibase-item" then it returns the value(s) of prop2 of each of those wikibase-items
 * 7)   if the item has values of P166 (award received), then it examines each of those awards for P2517 (category for recipients of this award) and it returns the corresponding category, with the item's P734 (family name) as sort key, or no sort key if there is no family name
 * 8)   for each value of the prop1 it fetches the value's main category and then each value of prop2, then it returns all of the categories representing the intersection of those properties
 * 9)   scans the property 'has part' (P527) for values matching a list, If the matched values have a qualifier 'quantity' (P1114), those quantities are summed and returned (but zero returns nil)
 * 10)   - gets coordinates and passes them through Template:Coord

There are also these utility calls:
 * 1)   if there is a sitelink to an article on the local Wiki, it returns a link to the article with the Wikidata label as the displayed text. If there is no sitelink, it returns the label as plain text. If there is no label in the local language, it returns the entity-ID
 * 2)   (Article Title) If there is a sitelink to an article on the local Wiki, it returns the sitelink as plain text, otherwise nothing
 * 3)   gets the plain text link to an article on a given wiki
 * 4)   returns the Wikidata label for the local language as plain text. If there is no label in the local language, it returns the entity-ID
 * 5)   fetches the set of labels and formats it for display as wikitext
 * 6)   returns the label with all wikitext removed, or the entity-ID if no label
 * 7)   returns the article description for the Wikidata entity if the local parameter is "Wikidata".
 * 8)   fetches the set of descriptions and formats it for display as wikitext
 * 9)   returns the aliases for the entity in the current or given language
 * 10)   fetches the set of aliases and formats it for display as wikitext
 * 11)   returns the connected Wikidata page id (entity-ID, Q-number) of the current page
 * 12)   takes a datetime of the usual format from mw.wikibase.entity:formatPropertyValues and formats it according to the df (date format) and bc parameters
 * 13)   formats a number according to the supplied language code
 * 14)   returns true if the field is not blacklisted (i.e. allowed)
 * 15)   returns nil if the parameter is just punctuation, whitespace or html tags, otherwise returns the argument unchanged
 * 16)   returns the MediaWiki language code or the full language name of the current content
 * 17)   looks for country (P17), then for that country's official language (P37), and returns its language code (P424)
 * 18)   returns (1) supplied language if valid; or (2) the user's set language; or (3) the language of the current wiki
 * 19)   returns (1) the entity-ID, if supplied; or (2) the entity ID of the "category's main topic (P301)"; or (3) the entity ID associated with the current page; or (4) nothing
 * 20)   given a list of properties, looks for each property in turn and returns the entity-ID of the first value that matches (optionally, returns all entity-IDs that match)
 * 21)   returns the entity-ID of the globe used in P625 (coordinate location), or nil if there isn't one
 * 22)   returns one of the following in order of preference: the Commons sitelink of the linked Wikidata item; the Commons sitelink of the topic's main category of the linked Wikidata item;
 * 23)   returns the root of the globalSiteID, e.g. "en" for "enwiki", "enwikisource", "en-gb", etc.
 * 24)   same as siteID
 * 25)   scans from the current location upwards along the chain of higher-level locations, returning each one until it reaches a country
 * 26)   returns a formatted dump of the given property
 * 27)   takes a parameter that is a proper url and formats it for use in an infobox; it accepts its own output as input
 * 28)   fetches the Official website (P856) and formats it for use in an infobox
 * 29)   looks through a property for a given entity-ID as its value and returns that entity-ID if found; otherwise nil
 * 30)   returns whether the first unnamed parameter represents a valid entity-id
 * 31)   displays the article titles that should not be linked

Examples of calls:

Base parameters

 * getValue can also take a named parameter qid which is the Wikidata ID for an article. This will not normally be used as omitting it defaults to the current article.
 * The property whose value is to be returned is passed in the first unnamed property and is required.
 * The second unnamed parameter, if supplied, will become the returned value and no call to Wikidata will be made.

Whitelist and blacklist

 * The name of the field that this function is called from is passed in the named parameter name, which is first checked against a blacklist of fields that are never to be displayed, (i.e. the call must return nil in all circumstances). If the field is not on the blacklist, it is then checked against a whitelist. If the name of the field matches, the call will return any locally supplied value if it is supplied as the second unnamed parameter, or the Wikidata value otherwise.
 * Specifying ALL is a shortcut to return all fields that are not blacklisted.
 * The name is compulsory when the blacklist or whitelist is used, so the module returns nil if it is not supplied, other than when ALL.
 * The blacklist is passed in the named parameter suppressfields
 * The whitelist is passed in the named parameter fetchwikidata

Sourcing
The getValue function will accept a boolean parameter  which will suppress return of Wikidata values that are unsourced or only sourced to Wikipedia. The absence of the parameter, an empty parameter (onlysourced) and the empty string all default to true (i.e. only referenced values are returned). The values,   and   are treated as false (i.e. all values are returned); any other value is true (although yes/no is recommended for readability).

Link to Wikidata
The getValue function will accept a boolean parameter  which will suppress the trailing "edit at Wikidata" icon and link for cases when the returned value is to be further processed by the infobox (e.g. a url). The absence of the parameter or an empty parameter (noicon) default to false (i.e. the icon is added). The empty string and the values ,   and   are treated as false; any other value is true (although true is recommended for readability).

Dates
In order to handle the requirement for dates in mdy, dmy or just year formats, getValue accepts a named parameter df that may take the values "dmy", "mdy", or "y" - default is "dmy".

As an article may require either of suffixes BC and BCE, getValue accepts a named parameter bc that may take the values "BC", or "BCE" - default is "BCE". Some test cases are shown at Module talk:WikidataIB/testing.

Ranks
The rank parameter, when set to preferred, returns only preferred values; when set to normal, returns only normal values; when set to deprecated, returns only deprecated values. If the parameter is set to best, it returns preferred values if present, otherwise normal values. Any parameter value beginning with "p" is "preferred"; any parameter value beginning with "n" is "normal"; any parameter value beginning with "d" is "deprecated"; any parameter value beginning with "b" is "best". Combinations of values are allowed, e.g. p n returns all the preferred and normal values (which is the default), although "best" overrides any other parameters.

Specific value-type handlers
The module has specific handlers for the following data types: Items that represent other types of data are not handled at present.
 * 1) Items that correspond to an article in some Wikipedia, called "wikibase-items". These will be linked to the corresponding (and disambiguated) article on English Wikipedia where possible.
 * 2) Items that represent dates. These may be centuries, years, years and months, or years, months and days.
 * 3) Items that represent Commons media, urls, external ids, or other sorts of plain text.
 * 4) Items that represent quantities. All of these may have an associated unit, or be dimensionless, and may have a range.
 * 5) Items that represent global coordinates. These will be in degrees of latitude and longitude and will have an associated precision.

The third class of data types may be used with the parameters: If you don't supply at least one of linkprefix or linkpostfix, then just prefix and postfix are used. For example, when getting the in : Use double-quotes to enclose the parameter value if it has leading or trailing spaces (otherwise they are stripped out). If you supply linkprefix or linkpostfix, then all four parameters are used and a link is made for each value like this: That allows multiple links to be made to different sections of a list article, such as List of observatory codes. For example, when getting the in  we can make the links:
 * prefix, postfix, linkprefix, linkpostfix

The parameters prefix, postfix, linkprefix, linkpostfix are also applied to wikibase-items if they are linked.

Formatting multiple returned values

 * <yes is a boolean passed to enable sorting of the values returned. No parameter, or an empty string, or "false", or "no", or "0" disables sorting. It's only a very dumb alphabetical sort and sorts linked values as "[[ ..."
 * sep allows the separator between multiple returned values to be defined. The default is  (comma plus normal space). If the separator has leading or trailing spaces, enclose it in double quotes (e.g. " - "). Any double quotes are stripped from the separator. The pipe character  must be escaped as  . For reasons of accessibility (see MOS:PLIST), do not use &lt;br> for vertical unbulleted lists; use ubl instead.
 * <prose allows multiple returned values to be displayed as a sentence with last two values separated by "and" (prose), a horizontal comma-separated list (cslist, not to be used in prose), a horizontal list (hlist), a vertical unbulleted list (ubl), a vertical bulleted list (blist), or a vertical ordered list (olist). These override the separator and do not display the 'pen icon' linked to "Edit at Wikidata".
 * p-1 displays the last value. Combine with n to display the nth value.

Limiting the returned values
Sometimes a property is expected to have a single value, such as, but may have multiple values on Wikidata. Setting 1 will limit the number of values returned to 1. Any other value is possible and functions as expected, but zero is treated as "no limit".

Unlinking
A returned value that represents an article on the local wiki will be linked by default. This includes redirects, but not dab pages. Sometimes there is a need not to link that returned values and this may be accomplished by setting no.

Unit abbreviations
When the returned value is a quantity, the name of the units in which it is expressed is appended. Infoboxes may wish to use abbreviations instead for common units. This can be done by setting true.

Qualifiers
A parameter qual may be supplied, which will return qualifiers of the required property, if they exist. If the value is set to a punctuation-separated list of property-IDs (e.g. P123, P456), then only the values of qualifiers with that property will be returned. If the value is set to ALL, then all of the qualifier values are returned. If the value is set to DATES then the and the  of the property are returned with a date separator. In each case, any qualifier values returned follow the property value, and are enclosed in parentheses. If multiple qualifier values are returned, they will be separated by commas by default, although the separator can be changed by specifying qsep (which may be enclosed in double-quotes, which are stripped out, so that spaces can be included). Setting the parameter yes will sort the returned qualifier values alphanumerically.

Short form of parameters
Some of the longer parameters may be abbreviated to make infobox designs more compact:

Parameter sets
Generally,  has a set of defaults for its parameters that represent consensus decisions by editors. For example, onlysourced defaults to  so only Wikidata values that are sourced to something better than "Wikipedia" will be returned, and fetchwikidata defaults to   so nothing is returned until it is enabled by setting some field names or "ALL". This represents the fail-safe condition and allows infoboxes to be made Wikidata-capable without changing any article until enabled for that article.

To simplify the use of  in other circumstances, common combinations of parameters can be specified with parameterset or its alias ps for convenience. Two combinations are implemented at present and these are: Other sets could be created if there is a demand.
 * ps=1 : a common set of overrides to get a simple value, linked where possible:
 * rank = "best"
 * fetchwikidata = "ALL"
 * onlysourced = "no"
 * noicon = "true"
 * ps=2 : a sort of raw value in plain text:
 * rank = "best"
 * fetchwikidata = "ALL"
 * onlysourced = "no"
 * noicon = "true"
 * linked = "no"
 * plaindate = "true"

Wrapper template
The template wdib can be used as a convenient wrapper for.

Function getPreferredValue
The getPreferredValue function works exactly like getValue, taking the same parameters, but if any values for a property have the preferred rank set, it will only return those values. This is now deprecated in favour of.

Function getCoords

 * getCoords can also take a named parameter qid which is the Wikidata ID for an article. This will not normally be used as omitting it defaults to the current article.
 * The first unnamed parameter, if supplied, will become the returned value and no call to Wikidata will be made.
 * The coordinates from Wikidata are parsed and passed to Template:Coord which returns the display as if it were called manually.
 * The blacklist of fields that are never to be displayed, and the whitelist are implemented in the same way as for getValue using suppressfields and fetchwikidata

Function getQualifierValue
The getQualifierValue function is for use when we want to fetch the value of a qualifier. We need to know the property and the value of the property that the qualifier relates to. The parameters are:
 * The property ID passed in the unnamed parameter (or 1)
 * The target value for that property in pval
 * The qualifier ID for that target value in qual
 * The same parameters to implement whitelisting and blacklisting of the property as in getValue
 * Optional boolean to specify whether only sourced values of the property are returned (defaults to "no") in onlysourced
 * Optional item ID for arbitrary access in qid
 * The same parameters to format output as in getValue

Example of getQualifierValue
In there is a property, which has a value. That has two qualifiers, and. To get the start date: In South Pole Telescope it returns:

Function getValueByQual
The getValueByQual function returns the value of a property which has a qualifier with a given entity value. The parameters are:
 * The property ID passed in the unnamed parameter (or 1)
 * The property ID for a qualifier (or "ALL" or "DATES") in qualID
 * The Wikibase-entity ID of a value for that qualifier in qvalue
 * The same parameters to implement whitelisting and blacklisting of the property as in getValue
 * Optional boolean to specify whether only sourced values of the property are returned (defaults to "no") in onlysourced
 * Optional item ID for arbitrary access in qid
 * The same parameters to format output as in getValue

Example of getValueByQual
In there is a property  that has multiple values, each of which has a qualifier. We can return the property value whose qualifier has the value

Function getValueByLang
The getValueByLang function returns the value of a property which has a qualifier whose value has the given language code. The parameters are:
 * The property ID passed in the unnamed parameter (or 1)
 * The to match the language whose code is given by xx[-yy]. If no code is supplied, it uses the default language.
 * The same parameters to implement whitelisting and blacklisting of the property as in getValue
 * Optional boolean to specify whether only sourced values of the property are returned (defaults to "no") in onlysourced
 * Optional item ID for arbitrary access in qid
 * The same parameters to format output as in getValue

Example of getValueByLang
In there is a property  that has multiple values, each of which has a qualifier. We can return the property value whose qualifier value (a WD item) itself has the  property that is "ja", i.e, If lang is unspecified, we can obtain the same value with the default language (here that is the  and its  is "en")

Function getLink
getLink has the qid of a Wikidata entity passed as the first unnamed parameter or as |qid=

If there is a sitelink to an article on the local Wiki, it returns a link to the article with the Wikidata label as the displayed text. If there is no sitelink, it returns the label as plain text. If there is no label in the local language, it displays the qid instead.
 * Wikidata: and



Function getLabel
getLabel has the qid of a Wikidata entity passed as the first unnamed parameter or as qid

It returns the Wikidata label in the local language for an item by the given qid. If there is no label in the local language, it returns the qid instead. Note that this is the label given to the Wikidata entry in the same language as the current Wiki, if the label exists.
 * Wikidata: and



Function label
label has the qid of a Wikidata entity passed as the first unnamed parameter or as qid

It returns the Wikidata label in the local language for an item by the given qid or linked to the current page. If there is no label in the local language, it returns an empty string. Note that this is the label given to the Wikidata entry in the same language as the current Wiki, if the label exists.
 * Wikidata: and



Function getAT
getAT has the qid of a Wikidata entity passed as the first unnamed parameter or as |qid=

If there is a sitelink to an article on the local Wiki, it returns the sitelink as plain text, i.e. the article title. If there is no sitelink, it returns nothing. Note that this is the title of the article in the current Wikipedia, if the interlanguage link exists in the Wikidata entry.
 * Wikidata: and



Function getDescription
getDescription has the qid of a Wikidata entity passed as |qid= (it defaults to the associated qid of the current article if omitted). It has a local parameter passed as the first unnamed parameter. Any local parameter passed (other than "Wikidata" or "none") becomes the return value. It returns the article description for the Wikidata entity in plain text if the local parameter is "Wikidata". Nothing is returned if the description doesn't exist or "none" is passed as the local parameter.
 * Wikidata: and



Function formatDate
formatDate accepts a datetime of the usual format from mw.wikibase.entity:formatPropertyValues, like "1 August 30 BCE" as parameter 1 and formats it according to the df (date format) and bc parameters.
 * df = "dmy" / "mdy" / "y" - default is "dmy"
 * bc = "BC" / "BCE" - default is "BCE"
 * df = "dmy" / "mdy" / "y" - default is "dmy"
 * bc = "BC" / "BCE" - default is "BCE"

Function checkBlacklist
checkBlacklist allows a test to check whether a named field is allowed. It returns true if the field is not blacklisted (i.e. allowed) It returns false if the field is blacklisted (i.e. disallowed)

Example:

Function emptyor
emptyor returns nil if its first unnamed argument is just punctuation, whitespace or html tags otherwise it returns the argument unchanged (including leading/trailing space).

If the argument could contain "=", then it must be called explicitly: In that case, leading and trailing spaces are trimmed.

It finds use in infoboxes where it can replace tests like: with a form that uses just a single call to Wikidata:

Function labelorid
labelorid is a public function to expose the output of labelOrId.

The Q-number (entity ID) is passed as |qid= or as an unnamed parameter.

It returns the Wikidata label for that entity or the qid if no label exists.

Function getQid

 * getQid works with the current page and its associated Wikidata entry.
 * It returns qid, if supplied as the first unnamed parameter or as qid;
 * failing that, the Wikidata entity ID of the "category's main topic (P301)", if it exists;
 * failing that, the Wikidata entity ID associated with the current page, if it exists;
 * otherwise, nothing

Function examine
examine provides a dump of the entire property given in the first unnamed parameter (or in pid as a named alias) from the item given by the parameter 'qid', or from the item corresponding to the current page if qid is not supplied. Both parameters may be unnamed and given in any order.

It works in a similar manner to the Dump function, but only loads a single claim, rather than the whole Wikidata entry.
 * Example:

There is a Template:Examine which acts as a wrapper for the call.
 * Example:  →

Function url2
url2 takes a parameter url= that is a proper url and formats it for use in an infobox.

Examples:

Comparison with output of URL:

Coding into an infobox
Typically, the getValue call will be invoked in an infobox definition, using appropriate template parameters. One simple implementation is given as an example in Template:Infobox book/Wikidata/Sandbox. As an illustration, the 'author' field in the infobox is coded like this:  The property to be fetched is the first unnamed parameter. In this case it is.
 * label2 = Author
 * data2 =

The name of the field is passed in name and that name is checked against the blacklist and the whitelist. To always suppress the author field in a particular article, an editor will set author in the infobox. The author field will then never be displayed.

If the field is not blacklisted, then the infobox can be set to display a locally supplied value for author simply by setting George Orwell, for example, in the infobox. It also accepts authors. If the name of the field is on the whitelist, e.g. author; genre; pub_date; pages; dewey; congress, and the local value is not supplied, then the infobox will display the value retrieved from Wikidata. Any separators can be used, except | and {}.

As a shorthand, ALL will fetch all of the fields that are not blacklisted, as long as no local value is already provided in the article for a given field.

Since Wikidata labels are normally lower case, the ucfirst function from Module:String2 can be used to capitalise the first letter of the returned text, e.g.
 * in produces:

Example of calls in an infobox
Basic use of getValue:

Full collection of parameters: Any of the parameters can, of course, be fixed for a given field in an infobox, rather than taking the parameter supplied to the infobox, which will affect all fields. For example, one field may set hlist where a series of short words is expected; whereas another field could use ubl where an unbulleted vertical list of several words on each line is required.

Coordinates
The getCoords call will display the output of Template:Coord when supplied with the coordinates returned from Wikidata. It can be coded like this:  An example is Template:Infobox biosphere reserve 
 * label20 = Coordinates
 * data20 =

Displays coordinates in the usual positions when used in an article where Wikidata has coordinates.

Upgrading existing infoboxes
Since the parameter fetchwikidata is needed for any Wikidata functionality, an existing infobox may be replaced by an infobox incorporating these calls without any change whatsoever to any article. Each article using the new infobox can later be enabled by supplying ALL, or a list of required fields for that article. At that point, the onus is on the editor enabling the functionality to check that no unwanted fields are now being displayed. If so, they can be added to a blacklist for the article by setting suppressfields to the list of unwanted fields.

Verifiability
Where it will always be essential for a particular field to only contain values that are referenced, use, making sure that onlysourced is not set to 'false', '0' or 'no'. By default it will exclude values that are unsourced or only sourced to a Wikipedia, thus making the job of checking easier at the article level. If unsourced data is acceptable (!), set no. As it is beyond my wit to produce an automated mechanism that knows whether an existing source is reliable or not in a given context, that job must still be performed at the article level by an editor familiar with the subject. It should always be done when first enabling Wikidata for that article.

Helper templates

 * Template:If then show : tests whether the first unnamed parameter is not an empty string and returns it if it isn't. Otherwise it returns the second unnamed parameter. Optional third and fourth unnamed parameters provide a prefix and a suffix for the first parameter when returned. Useful when the first parameter is a call to Wikidata.
 * Template:Ifnoteq then show : tests whether the first unnamed parameter is equal to the second unnamed parameter and returns the third unnamed parameter if it does. Otherwise it returns the first unnamed parameter. This is useful when the first parameter is a  of a Lua module that returns a value for which a specific exception is required.
 * Template:If then wikilink : tests whether the first unnamed parameter is not an empty string and if it isn't, it returns the parameter formatted as piped wiki-link using an optional namespace prefix.
 * Template:Formatter link : takes an external identifier code as code and uses a formatter url as url to construct a link to the external resource, which uses the code as display.
 * Template:Emptyor : tests a piece of text to ascertain whether it's effectively empty or contains some text. If the unnamed parameter consists only of html tags, punctuation (e.g. Wiki-markup) and whitespace, then Emptyor returns nothing; otherwise it returns the parameter unchanged. Wrapper for p.emptyor function.

Example of use: Infobox book
This section is taken from Template:Infobox book/Wikidata/Sandbox/doc.

No Wikidata


Works as a non-aware infobox: only locally supplied parameters are displayed. 

The blacklist and whitelist can be omitted if unused

All Wikidata


Fetches the author, publication date, number of pages, Dewey index, and Library of Congress catalogue number values from Wikidata. 

As shorthand, the fetchwikidata parameter can be set to ALL to fetch all available fields. Any field can be suppressed by naming it in suppressfields, or overridden by supplying a local value.

Never display genre


The genre field will always be suppressed, even if a local value is supplied. 

Local override


The genre field is set to display "Political satire", no matter what is stored in Wikidata. 

The genre field is set to display "Novel", no matter what is stored in Wikidata.

Don't fetch genre


The genre field will not be fetched from Wikidata. Only the author, publication date, number of pages, Dewey index, and Library of Congress catalogue number are imported. A local value for genre will display.