Content deleted Content added
lang parameter |
update first part of documentation |
||
Line 1:
<noinclude>For documenting developments not yet in the main module.
</noinclude>
This module is designed specifically to implement a mechanism which moves control of whether Wikidata values are used in an infobox from the template coder at the infobox design level to the editor at the article level. It is only intended to be used inside an infobox.
One of the three sandboxes at [[Module:WikidataIB/sandbox]], [[Module:WikidataIB/sandbox1]] or [[Module:WikidataIB/sandbox2]] should be used for testing anything other than trivial amendments.
Test cases for the main module can be found at [[Module talk:WikidataIB/testing]]. Test cases for two of the sandboxes are at [[Module talk:WikidataIB/sandbox/testing]] and [[Module talk:WikidataIB/sandbox1/testing]].
== Overview ==
The module provides these calls specifically for use in infoboxes at present:
# <code>getValue</code>
# <s><code>getPreferredValue</code></s> - obsoleted: use <code>getValue|rank=best</code> instead.
# <s><code>getNormalValue</code></s> - obsoleted: use <code>getValue|rank=normal</code> instead.
# <code>getCoords</code>
# <code>getQualifierValue</code>
# <code>getValueByQual</code>
# <code>getValueByLang</code>
The obsolete call getSourcedValue has now been removed as it is redundant to getValue which can do the same job using the {{para|onlysourced|true}} parameter (which is set by default).
There are also these utility calls:
# <code>getLink</code>
# <code>getLabel</code>
# <code>getAT</code>
# <code>getDescription</code>
# <code>pageId</code>
# <code>formatDate</code>
# <code>checkBlacklist</code>
# <code>emptyor</code>
# <code>labelorid</code>
# <code>getLang</code>
# <code>getQid</code>
Example form of each call:
<nowiki>{{#invoke:WikidataIB |getValue |<PropertyID> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |onlysourced=<yes/no> |noicon=<yes/no> |df=<dmy/mdy/y> |bc=<BC/BCE> |qual=<ALL/DATES/P999> |list=<ubl/hlist/prose> |linked=<yes/no> |<local parameter>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getCoords |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |<local parameter>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getQualifierValue |<PropertyID> |pval=<ID of target value for the property> |qual=<qualifier ID for that target value> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |onlysourced=<yes/no>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getValueByQual |<PropertyID> |qualID=<qualifier property ID to match> |qvalue=<QID of target value for the qualifier property> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |onlysourced=<yes/no>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getValueByLang |<PropertyID> |lang=<language code to match> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |onlysourced=<yes/no>}}</nowiki>
== Function getValue ==
=== Parameters to getValue ===
{| class ="wikitable"
|-
! scope="col" | Name
Line 145 ⟶ 190:
| local language
|}
* getValue can also take a named parameter {{para|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 to be returned is passed in the first unnamed property and is required.
* The name of the field that this function is called from is passed in the named parameter {{para|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.
* The name is compulsory when the blacklist or whitelist is used, so the module returns nil if it is not supplied, other than when {{para|fetchwikidata|ALL}}.
* The blacklist is passed in the named parameter {{para|suppressfields}}
* The whitelist is passed in the named parameter {{para|fetchwikidata}}
The getValue function will accept a boolean parameter <code>onlysourced</code> which will suppress return of Wikidata values that are unsourced or only sourced to Wikipedia. The absence of the parameter, an empty parameter ({{para|onlysourced}}) and the empty string (<code>""</code>) all default to true (i.e. only referenced values are returned). The values <code>no</code>, <code>false</code> and <code>0</code> are treated as false (i.e. all values are returned); any other value is true (although {{para|onlysourced|yes/no}} is recommended for readability).
The getValue function will accept a boolean parameter <code>noicon</code> which will suppress the trailing "edit at Wikidata" icon for 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 ({{para|noicon}}) default to false (i.e. the icon is added). The empty string (<code>""</code>) and the values <code>no</code>, <code>false</code> and <code>0</code> are treated as false; any other value is true (although {{para|noicon|true}} is recommended for readability).
In order to handle the requirement for dates in mdy, dmy or just year formats, getValue accepts a named parameter {{para|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 {{para|bc}} that may take the values "BC", or "BCE" - default is "BCE". Some test cases are shown at [[Module talk:WikidataIB/testing #Calls to getValue for dates]].
The {{para|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. {{para|rank|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 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.
# Items that represent dates.
# Items that represent Commons media, urls, external ids, or other sorts of plain text.
Items that represent other types of data are returned using the mwdiawiki library call formatPropertyValues().
The third class of data types may be used with the parameters:
* {{para|prefix}}, {{para|postfix}}, {{para|linkprefix}}, {{para|linkpostfix}}
If you don't supply {{para|linkprefix}}, then just {{para|prefix}} and {{para|postfix}} are used. For example, when getting the {{Q|P717}} in {{Q|Q532127|}}:
* <code><nowiki>{{#invoke:WikidataIB/sandbox|getValue|P717|fetchwikidata=ALL|onlysourced=no |prefix="before " |postfix=" after" |qid=Q532127}}</nowiki></code> → {{#invoke:WikidataIB/sandbox |getValue |P717 |fetchwikidata=ALL|onlysourced=no |prefix="before " |postfix=" after" |qid=Q532127}}
Use double-quotes to enclose the parameter value if it has leading or trailing spaces (otherwise they are stripped out). If you supply {{para|linkprefix}}, then all four parameters are used and a link is made for each value like this:
* <code><nowiki>[[ linkprefix WikidataValue1 linkpostfix | prefix WikidataValue1 postfix]], [[ linkprefix WikidataValue2 linkpostfix | prefix WikidataValue2 postfix]], etc.</nowiki></code>
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 {{Q|P717}} in {{Q|Q532127|}} we can make the links:
*<code><nowiki>{{#invoke:WikidataIB/sandbox|getValue|P717|fetchwikidata=ALL|onlysourced=no |prefix= |postfix= |linkprefix="List of observatory codes#" |linkpostfix= |qid=Q532127}}</nowiki></code> → {{#invoke:WikidataIB/sandbox|getValue|P717|fetchwikidata=ALL|onlysourced=no |prefix= |postfix= |linkprefix="List of observatory codes#" |linkpostfix= |qid=Q532127}}
==== Formatting multiple returned values ====
<!-- needs more detail and examples -->
* {{para|sorted|<yes{{!}}no>}} 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 "[[ ..."
* {{para|sep|<separator characters>}} allows the separator between multiple returned values to be defined. The default is <code>", "</code> (comma plus normal space). If the separator has leading or trailing spaces, enclose it in double quotes (e.g. {{para|sep|" - "}}). Any double quotes are stripped from the separator. The pipe character (<code>|</code>) must be escaped as <code><nowiki>{{!}}</nowiki></code>. For reasons of accessibility (see [[MOS:PLIST]]), do not use {{para|sep|<br>}} for vertical unbulleted lists; use {{para|list|ubl}} instead.
* {{para|list|<hlist{{!}}ubl>}} allows multiple returned values to be displayed as a horizontal list ({{para|list|hlist}}), or a vertical unbulleted list ({{para|list|ubl}}). These override the separator and do not display the 'pen icon' linked to "Edit at Wikidata"
== Other function details ==
=== 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.
=== Function getNormalValue ===
The getNormalValue function complements getPreferredValue, taking the same parameters, but if any values for a property have the normal rank set, it will only return those values.
If a property has a mixture of preferred and normal ranks set, these functions will separate them.
==== Comparison example ====
Fetching the name(s) of the {{Q|P170}} from {{Q|Q29016906}}:
* <code><nowiki>{{#invoke:WikidataIB |getValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}</nowiki></code> → {{#invoke:WikidataIB |getValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}
* <code><nowiki>{{#invoke:WikidataIB |getPreferredValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}</nowiki></code> → {{#invoke:WikidataIB |getPreferredValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}
* <code><nowiki>{{#invoke:WikidataIB |getNormalValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}</nowiki></code> → {{#invoke:WikidataIB |getNormalValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}
=== Function getCoords ===
* getCoords can also take a named parameter {{para|qid}} which is the Wikidata ID for the article. This will not normally be used but is available for testing, although it makes the call ''expensive''.
* The coordinates from Wikidata are parsed and passed to [[Template:Coord]] which returns the display as if it were called manually.
* The name of the field that this function is called from is passed in the named parameter {{para|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 unnamed parameter, or the Wikidata value otherwise.
* The name is compulsory when the blacklist or whitelist is used, so the module returns nil if it is not supplied.
* The blacklist is passed in the named parameter {{para|suppressfields}}
* The whitelist is passed in the named parameter {{para|fetchwikidata}}
=== Function getQualifierValue ===
The getQualifierValue 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 it qualifies. The parameters are:
* The property ID passed in the unnamed parameter (or {{para|1}})
* The target value for that property in {{para|pval}}
* The qualifier ID for that target value in {{para|qual}}
* The name of the field where its called from to implement whitelisting and blacklisting of the property in
* The list of fields to be fetched ("whitelist") in {{para|fetchwikidata}} - accepts {{para|fetchwikidata|ALL}} to fetch all fields
* Optional list of fields not to be displayed ("blacklist") in {{para|suppressfields}}
* Optional boolean to specify whether only sourced values of the property are returned (defaults to "no") in {{para|onlysourced}}
* Optional item ID for arbitrary access (expensive call!) in {{para|qid}}
==== Example of getQualifierValue ====
In {{Q|Q1513315}} there is a property {{Q|P793}}, which has a value {{Q|Q385378}}. That has two qualifiers, {{Q|P580}} and {{Q|P582}}. To get the start date:
* <code><nowiki>{{#invoke:WikidataIB |getQualifierValue |P793 |pval=Q385378 |qual=P580 |name=xyz |fetchwikidata=ALL }}</nowiki></code>
In [[South Pole Telescope]] it returns:
* {{#invoke:WikidataIB |getQualifierValue |P793 |pval=Q385378 |qual=P580 |name=xyz |fetchwikidata=ALL |qid=Q1513315}}
=== Function getLink ===
getLink returns the label for a Qid wiki-linked to the local article (if the article exists). If label doesn't exist, it returns the Qid wiki-linked to the local article (if the article exists).
: Wikidata: {{q|Q29016906}} and {{q|Q3621491}}
* <code><nowiki>{{#invoke:WikidataIB |getLink |Q29016906}}</nowiki></code> → {{#invoke:WikidataIB |getLink |Q29016906}}
* <code><nowiki>{{#invoke:WikidataIB |getLink |Q3621491}}</nowiki></code> → {{#invoke:WikidataIB |getLink |Q3621491}}
=== Function getLabel ===
getLabel returns the label for a Qid. If label doesn't exist, it returns the Qid.
Note that this is the label given to the Wikidata entry in the same language as the current Wikipedia, if the label exists.
: Wikidata: {{q|Q29016906}} and {{q|Q3621491}}
* <code><nowiki>{{#invoke:WikidataIB |getLabel |Q29016906}}</nowiki></code> → {{#invoke:WikidataIB |getLabel |Q29016906}}
* <code><nowiki>{{#invoke:WikidataIB |getLabel |Q3621491}}</nowiki></code> → {{#invoke:WikidataIB |getLabel |Q3621491}}
=== Function getAT ===
getAT returns the article title for a Qid. If the article title doesn't exist, 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: {{q|Q29016906}} and {{q|Q3621491}}
* <code><nowiki>{{#invoke:WikidataIB |getAT |Q29016906}}</nowiki></code> → {{#invoke:WikidataIB |getAT |Q29016906}}
* <code><nowiki>{{#invoke:WikidataIB |getAT |Q3621491}}</nowiki></code> → {{#invoke:WikidataIB |getAT |Q3621491}}
=== 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.
* <code><nowiki>{{#invoke:WikidataIB |formatDate | 1 August 30 BCE |bc=BCE |df=dmy}}</nowiki></code> → {{#invoke:WikidataIB |formatDate | 1 August 30 BCE |bc=BCE |df=dmy}}
* <code><nowiki>{{#invoke:WikidataIB |formatDate | 1 August 30 BCE |bc=BC |df=mdy}}</nowiki></code> → {{#invoke:WikidataIB |formatDate | 1 August 30 BCE |bc=BC |df=mdy}}
* df = "dmy" / "mdy" / "y" - default is "dmy"
* bc = "BC" / "BCE" - default is "BCE"
== 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:
<pre style="line-height:1.2em;">
| label2 = Author{{#if:{{{authors|}}}|s}}
| data2 = {{#invoke:WikidataIB |getValue |P50 |name=author |fetchwikidata={{{fetchwikidata|}}} |suppressfields={{{suppressfields|}}} |{{{authors|{{{author|}}}}}} }}
</pre>
The property to be fetched is the first unnamed parameter. In this case it is {{Q|P50}}.
The name of the field is passed in {{para|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 {{para|suppressfields|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 {{para|author|[[George Orwell]]}}, for example, in the infobox. It also accepts {{para|authors}}. If the name of the field is on the whitelist, e.g. {{para|fetchwikidata|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, {{para|fetchwikidata|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 sentence case function from [[Module:String2]] can be used to capitalise the first letter of the returned text, e.g.
* <code><nowiki>{{#invoke:String2 | sentence | {{#invoke:WikidataIB |getValue |P136 |name=genre |fetchwikidata=ALL |onlysourced=false}} }}</nowiki></code> in {{Q|Q1396889}} produces:
* {{#invoke:String2 | sentence | {{#invoke:WikidataIB |getValue |P136 |name=genre |fetchwikidata=ALL |onlysourced=false |qid=Q1396889}} }}
=== Example of calls in an infobox ===
Basic use of getValue:
*<code><nowiki>{{#invoke:WikidataIB |getValue |P000 |name=fieldname |qid={{{qid|}}} |fetchwikidata={{{fetchwikidata|}}} |onlysourced={{{onlysourced|}}} |{{{localparameter|}}} }}</nowiki></code>
Full collection of parameters:
*<code><nowiki>{{#invoke:WikidataIB |getValue |P000 |name=fieldname |qid={{{qid|}}} |suppressfields={{{suppressfields|}}} |fetchwikidata={{{fetchwikidata|}}} |onlysourced={{{onlysourced|}}} |noicon={{{noicon|}}} |wdl={{{wikidatalink|}}} |df={{dateformat|}} |bc={{{bc|}}} |prefix= |postfix= |linkprefix= |linkpostfix= |sorted={{{sorted|}}} |sep={{{separator|}}} |list={{listtype|}}} |{{{localparameter|}}} }}</nowiki></code>
Any of the parameters can, of course, be 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 {{para|list|hlist}} where a series of short words is expected; whereas another field could use {{para|list|ubl}} where an unbulleted vertical list of several words on each line is required.
=== Coodinates ===
The getCoords call will display the output of [[Template:Coord]] when supplied with the coordinates returned from Wikidata. It can be coded like this:
<pre style="line-height:1.2em;">
|label20 = Coordinates
| data20 = {{#invoke:WikidataIB |getCoords |name=coordinates |suppressfields={{{suppressfields|}}} |fetchwikidata={{{fetchwikidata|}}} |{{{coordinates|}}} }}
</pre>
An example is [[Template:Infobox biosphere reserve]]
<pre style="line-height:1.2em;">
{{Infobox biosphere reserve
| fetchwikidata = ALL
}}
</pre>
Displays coordinates in the usual positions when used in an article where Wikidata has coordinates.
=== Upgrading existing infoboxes ===
Since the parameter {{para|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 {{para|fetchwikidata|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 {{para|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 <code>getValue</code>, making sure that {{para|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 {{para|onlysourced|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.
== Example of use: Infobox book ==
This section is taken from [[Template:Infobox book/Wikidata/Sandbox/doc]].
=== No Wikidata ===
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| suppressfields =
| fetchwikidata =
| name = Animal Farm
| title_orig = Animal Farm: A Fairy Story
| image = Animal Farm - 1st edition.jpg
| image_size = 200px
| caption = First edition cover
| author = [[George Orwell]]
| country = United Kingdom
| language = English
| genre = Political satire
}}
</pre>
Works as a non-aware infobox: only locally supplied parameters are displayed.
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| name = Animal Farm
| title_orig = Animal Farm: A Fairy Story
| image = Animal Farm - 1st edition.jpg
| image_size = 200px
| caption = First edition cover
| author = [[George Orwell]]
| country = United Kingdom
| language = English
| genre = Political satire
}}
</pre>
The blacklist and whitelist can be omitted if unused
=== All Wikidata ===
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| fetchwikidata = author; genre; pub_date; pages; dewey; congress
}}
</pre>
Fetches the author, publication date, number of pages, Dewey index, and Library of Congress catalogue number values from Wikidata.
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| fetchwikidata = ALL
}}
</pre>
As shorthand, the {{para|fetchwikidata}} parameter can be set to ALL to fetch all available fields.
Any field can be suppressed by naming it in {{para|suppressfields}}, or overridden by supplying a local value.
=== Never display genre ===
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| suppressfields = genre
| fetchwikidata = author; genre; pub_date; pages; dewey; congress
}}
</pre>
The genre field will always be suppressed, even if a local value is supplied.
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| suppressfields = genre
| fetchwikidata = author; genre; pub_date; pages; dewey; congress
| genre = Political satire
}}
</pre>
=== Local override ===
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| fetchwikidata = author; genre; pub_date; pages; dewey; congress
| genre = Political satire
}}
</pre>
The genre field is set to display "Political satire", no matter what is stored in Wikidata.
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| fetchwikidata = ALL
| genre = Novel
}}
</pre>
The genre field is set to display "Novel", no matter what is stored in Wikidata.
=== Don't fetch genre ===
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| suppressfields =
| fetchwikidata = author; pub_date; pages; dewey; congress
}}
</pre>
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.
| |||