Editing Module:WikidataIB/sandbox1/doc (section)

== Function getValue ==
=== Parameters to getValue ===
{| class ="wikitable"
|-
! scope="col" | Name
! scope="col" | Alias
! scope="col" | Function
! scope="col" | Default
|-
| (first unnamed)
| 1
| The property-ID whose values are returned. Required.
| 
|-
|-
| (second unnamed)
| 2
| A locally supplied value that, if it is not empty, will be returned in preference to the value on Wikidata.
| empty
|-
| qid
| 
| The Q-number (entity-ID) of the entity that the property belongs to. If not supplied or empty, defaults to the associated Wikidata entry of the current page – uses [[:mw:Extension:Wikibase Client/Lua #mw.wikibase.getEntityIdForCurrentPage|mw.wikibase.getEntityIdForCurrentPage()]].
| Item id for current page
|-
| rank
|
| [Case insensitive] When set to <code>best</code>, returns preferred values if present, otherwise returns normal values. When set to <code>preferred</code> returns preferred values. When set to <code>normal</code>, returns normal values. When set to <code>deprecated</code> returns deprecated values. Any parameter value beginning with "b" is "best"; beginning with "p" is "preferred"; beginning with "n" is "normal"; beginning with "d" is deprecated. Multiple values are allowed: "p n d" would return all ranks. "Best" overrides the other flags. Other values are ignored and if no ranks are requested, preferred and normal are returned.
| preferred and normal
|-
| qual
| 
| The property-ID of a qualifier that is to be returned in parentheses after the property. Setting <code>qual=ALL</code> returns all qualifiers. Setting <code>qual=DATES</code> returns {{q|P580}} and {{q|P582}} with a date separator.
| none
|-
| fetchwikidata
| fwd
| List of fields to fetch values from. <code>ALL</code> fetches all fields. A value of <code>NONE</code> or blank or omitting the parameter fetches no fields.
| none
|-
| suppressfields
| spf
| List of fields which will never display. This will even force a local value in the field not to display.
| none
|-
| name
| 
| Name of the field. When encoding an infobox, this is the name that fetchwikidata and suppressfields will recognise. Required if fetchwikidata or suppressfields is specified (except when <code>fetchwikidata=ALL</code>).
| nil
|-
| onlysourced
| osd
| A boolean which will filter out Wikidata values that are unsourced or only sourced to Wikipedia. Values <code>no</code>, <code>false</code> and <code>0</code> are all false; anything else is true.
| true
|-
| df
| 
| Date format: may be <code>dmy</code> (day before month) or <code>mdy</code> (month before day) or <code>y</code> (year alone).
| dmy
|-
| bc
| 
| Format of the BC/BCE suffix for dates.
| BCE
|-
| linked
| 
| A boolean that enables the link to a local page via its sitelink on Wikidata. Values <code>no</code>, <code>false</code> and <code>0</code> are all false; anything else is true.
| true
|-
| wdlinks
| wdl
| A boolean that enables the display of links to Wikidata when no local article exists. Values <code>no</code>, <code>false</code> and <code>0</code> are all false; anything else is true.
| false
|-
| unitabbr
| 
| A boolean that enables unit abbreviations for common units. Values <code>no</code>, <code>false</code> and <code>0</code> are all false; anything else is true.
| false
|-
| maxvals
| 
| Sets the maximum number of values to be returned when multiple values are available. Setting it to 1 is useful where the returned string is used within another call, e.g. image. Values <code>0</code> and empty return all values.
| 0 (all)
|-
| collapse
| 
| Sets the maximum number of values to be returned before the content is auto-collapsed. Values <code>0</code> and empty allow all content to be displayed uncollapsed.
| 0 (all)
|-
| linkprefix
| 
| A link prefix that is prepended to the linked value when linked. Applies only to items that have articles and to strings (e.g. url). It triggers linking of strings. Any double-quotes " are stripped out, so that spaces may be passed.
| empty
|-
| linkpostfix
| 
| A link postfix that is appended to the linked value when linked. Applies only to items that have articles and to strings (e.g. url). It triggers linking of strings. Any double-quotes " are stripped out, so that spaces may be passed.
| empty
|-
| prefix
| 
| A prefix that is prepended to the displayed value of strings (e.g. url). Any double-quotes " are stripped out, so that spaces may be passed.
| empty
|-
| postfix
| 
| A postfix that is appended to the displayed value of strings (e.g. url). Any double-quotes " are stripped out, so that spaces may be passed.
| empty
|-
| qlinkprefix
| 
| Qualifier link prefix (see linkprefix).
| empty
|-
| qlinkpostfix
| 
| Qualifier link postfix (see linkpostfix).
| empty
|-
| qprefix
| 
| Qualifier prefix (see prefix).
| empty
|-
| qpostfix
| 
| Qualifier postfix (see postfix).
| empty
|-
| sorted
| 
| A boolean which enables sorting of the values returned. Values <code>no</code>, <code>false</code> and <code>0</code> are all false; anything else is true.
| false
|-
| qsorted
| 
| A boolean which enables sorting of the qualifier values within each item returned. Values <code>no</code>, <code>false</code> and <code>0</code> are all false; anything else is true.
| false
|-
| noicon
| 
| A boolean which will suppress the trailing "edit at Wikidata" pen-icon. Useful for when the returned value is to be further processed. Values <code>no</code>, <code>false</code> and <code>0</code> are all false; anything else is true.
| false
|-
| list
| 
| The name of a template that the list of multiple values is then passed through. Examples include "hlist" and "ubl". Setting it to "prose" produces something like "1, 2, 3, and 4"
| none
|-
| sep
| 
| Customises the string that is used to separate multiple returned values. Any double-quotes " are stripped out, so that spaces may be passed. If nothing or an empty string is passed it is set to the default list separator (", " in English).
| ", "
|-
| qsep
| 
| Customises the string that is used to separate multiple returned qualifier values. Any double-quotes " are stripped out, so that spaces may be passed. If nothing or an empty string is passed it is set to the default list separator (", " in English).
| ", "
|-
| format
| 
| Determines whether global coordinates should be rendered as degree/minute/second or as decimal degrees. Any value beginning "dec" (case insensitive) will render as decimal. Anything else will render as DMS.
| dms
|-
| show
| 
| Determines how global coordinates should be returned. The value "longlat" will return <code>longitude, latitude</code>. Any other value beginning "lon" (case insensitive) will return just longitude. Any value beginning "lat" (case insensitive) will return just latitude. When used with {{para|noicon|true}}, all of these will be pure numbers in decimal degrees (signed: N and E as positive), which are intended for use in mapping templates, etc. Anything other value (or nothing) will render the usual coordinate values as DMS or decimal with "NSEW" qualifiers, etc.
| empty
|-
| lang
| 
| Allows an unlinked value to be returned in the chosen language. Takes a standard ISO language code recognised by MediaWiki. If not supplied or blank, the local language (or set language for multi-lingual wikis) is used as normal.
| local language
|}

=== Base parameters ===
* 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 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 {{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}}

=== Sourcing ===
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).

=== Link to Wikidata ===
The getValue function will accept a boolean parameter <code>noicon</code> 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 ({{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).

=== Dates ===
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]].

=== Ranks ===
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. These may be centuries, years, years and months, or years, months and days.
# Items that represent Commons media, urls, external ids, or other sorts of plain text.
# Items that represent quantities. All of these may have an associated unit, or be dimensionless, and may have a range.
# Items that represent global coordinates. These will be in degrees of latitude and longitude and will have an associated precision.
Items that represent other types of data are not handled at present.

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 at least one of {{para|linkprefix}} or {{para|linkpostfix}}, 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}} or {{para|linkpostfix}}, 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}}

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

==== Formatting multiple returned values ====
* {{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|&lt;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"

=== Limiting the returned values ===
Sometimes a property is expected to have a single value, such as {{q|P18}}, but may have multiple values on Wikidata. Setting {{para|maxvals|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 {{para|linked|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 {{para|unitabbr|true}}.

=== Qualifiers ===
A parameter {{para|qual}} may be supplied, which will return qualifiers of the required property, if they exist. If the value is set to a property id (P12345), then only the values of qualifiers with that property will be returned. If the value is set to {{para|qual|ALL}}, then all of the qualifier values are returned. If the value is set to {{para|qual|DATES}} then the {{q|P580}} and the {{q|P582}} 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 {{para|qsep}} (which may be enclosed in double-quotes, which are stripped out, so that spaces can be included). Setting the parameter {{para|qsorted|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:
* <code>fwd → fetchwikidata</code>
* <code>osd → onlysourced</code>
* <code>spf → suppressfields</code>
* <code>wdl → wdlinks</code>

=== Wrapper template ===
The template {{tl|wdib}} can be used as a convenient wrapper for <code><nowiki>{{#invoke:WikidataIB |getValue}}</nowiki></code>.