3 167
edições
Mudanças
Criação da documentação do Módulo WikidataIB
{{Module rating |alpha}}
<includeonly>{{MóduloWikidata}}</includeonly>
Este módulo foi projetado especificamente para implementar um mecanismo que move o controle de se os valores do Wikidata são usados em uma infobox do programador da predefinição no nível de design da infobox para o editor no nível de artigo. Ele só deve ser usado dentro de uma infobox.
== Uso ==
O módulo provê essas chamadas especificamente para o uso em infoboxes no presente:
# <code>getValue</code>
# <code>getPreferredValue</code>
# <code>getSourcedValue</code>
# <code>getCoords</code>
# <code>getQualifierValue</code>
A chamada getSourcedValue é mantida para compatibilidade com versões anteriores, pois agora é redundante para getValue que pode fazer o mesmo trabalho usando o parâmetro <code>{{parâmetro|onlysourced|true}}</code>.
Existem também essas chamadas úteis:
# <code>getLink</code>
# <code>getLabel</code>
# <code>getAT</code>
# <code>formatDate</code>
# <code>checkBlacklist</code>
# <code>predDni</code>
# <code>predMorte</code>
Chamadas generalizadas:
<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> |<local parameter>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getPreferredValue |<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> |<local parameter>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getSourcedValue |<PropertyID> |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 |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>
=== Função getValue ===
* getValue pode também pegar um parâmetro <code>{{parâmetro|qid}}</code> que é o ID do Wikidata para o artigo. Isto não será normalmente usado, mas está disponível para teste, embora faça a chamada ''cara''.
* A propriedade a ser retornada é passada na primeira propriedade não nomeada.
* O nome do campo que a função é chamada é passada no parâmetro <code>{{parâmetro|name}}</code>, que é primeiramente checado em uma blacklist de campos que não devem ser mostradas nunca, (i.e. a chamada retorna nil em todas as circunstâncias). Se o campo não está na blacklist, é então checado contra uma whitelist. Se o nome do campo concorda, a chamada retornará qualquer valor fornecido localmente se é fornecido como segundo parâmetro não nomeado, ou o valor do Wikidata caso contrário.
* O nome é compulsório quando a blacklist ou a whitelist é usada, então o módulo retorna nil se não é fornecido.
* A blacklist é passada no parâmetro <code>{{parâmetro|suppressfields}}</code>
* A whitelist é passada no parâmetro <code>{{parâmetro|fetchwikidata}}</code>
A função getValue aceitará um parâmetro booleano <code>{{parâmetro|onlysourced}}</code> que irá suprimir retornos dos valores do Wikidata que estão sem fontes ou somente referenciados a wIRChelp. A ausência do parâmetro, um parâmetro <code>|onlysourced</code> vazio e uma string vazia (<code>""</code>) têm como default para verdadeiro (i.e. somente os valores referenciados são retornados). Os valores <code>no</code>, <code>false</code> e <code>0</code> são tratados como falsos (i.e. todos os valores são retornados); qualquer outro valor é verdadeiro (embora <code>{{parâmetro|onlysourced|yes}}</code> seja recomendado para legibilidade).
A função getValue aceitará um parâmetro booleano <code>noicon</code> que suprimirá o ícone "edite no Wikidata" para quando o valor retornado for processado futuramente pela infobox (e.g. uma url). A ausência do parâmetro ou um parâmetro <code>|noicon</code> vazio default para falso (i.e. o parâmetro é adicionado). A string vazia (<code>""</code>) e os valores <code>no</code>, <code>false</code> e <code>0</code> são tratados como falsos; qualquer outro valor é verdadeiro (embora <code>{{parâmetro|noicon|true}}</code> seja recomendado para legibilidade).
Em ordem de lidar com o requerimento para datas em my, dmy ou y, getValue aceita um parâmetro <code>{{parâmetro|df}}</code> que pode pegar valores "dmy", "my" ou "y" - default é "dmy".
Se um artigo exigir o sufixo a.C., getValue retornará a data com esse sufixo;
Em uma invocação do módulo para extrair datas, getValue aceita um parâmetro <code>{{parâmetro|idioma}}</code> que pode receber o valor "pt" para formatar a data de acordo com o português europeu (única diferença se dá nas datas envolvendo o primeiro dia do mês. Por exemplo: [[1º de maio]] de [[2017]] (em português brasileiro) e [[1 de maio]] de [[2017]] (em português europeu)).
* A propriedade a ser retornada é passada na primeira propriedade não nomeada.
A função getValue aceitará um especificador de uso de unidade de medida (ao invés da unidade por extenso) na terceira propriedade não nomeada. A unidade de medida será exibida somente se o valor passado for <code>unidade</code>
=== Função getPreferredValue ===
A função getPreferredValue trabalha exatamente como getValue, tomando os mesmos parâmetros, mas se qualquer um dos valores para a propriedade tem um rank set preferido, ela retornará esses valores.
==== Exemplo ====
Obtendo o(s) nome(s) da {{Q|P170}} de {{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}}
=== Função getSourcedValue ===
* getSourcedValue trabalha exatamente como getValue, mas somente retorna valores que tenham referência a algo mais do que a wIRChelp. Não há garantias de fontes confiáveis, mas ajuda separar o joio do trigo.
==== Exemplo de getSourcedValue ====
De {{Q|Q151973}}:
[https://www.wikidata.org/w/index.php?title=Q151973&oldid=363049791 Burton correntemente] tem quatro valores para {{Q|P106}} no Wikidata:
* {{Q|Q10800557}} (referenciado a Dutch wIRChelp);
* {{Q|Q33999}} (referenciado a http://www.nytimes.com/1983/05/09/theater/theater-private-lives-burton-and-miss-taylor.html);
* {{Q|Q18939491}} (referenciado a wIRChelp);
* {{Q|Q2259451}} (não referenciado).
Usando getValue em [[Richard Burton]]:
* <code><nowiki>{{#invoke:WikidataIB |getValue |P106 |name=occupation |fetchwikidata=ALL}}</nowiki></code> -> {{#invoke:WikidataIB |getValue |P106 |name=occupation |fetchwikidata=ALL |qid=Q151973|onlysourced=no}}
Usando getSourcedValue em [[Richard Burton]]:
* <code><nowiki>{{#invoke:WikidataIB |getSourcedValue |P106 |name=occupation |fetchwikidata=ALL}}</nowiki></code> -> {{#invoke:WikidataIB |getSourcedValue |P106 |name=occupation |fetchwikidata=ALL |qid=Q151973}}
=== Função getCoords ===
* getCoords pode também pegar um parâmetro <code>{{parâmetro|qid}}</code> que é o ID do Wikidata para o artigo. Isto não será normalmente usado, mas está disponível para testes, embora faça a chamada ''cara''.
* As coordenadas do Wikidata são passadas a [[Predefinição:Coord]] que retorna o display como se fosse chamado manualmente.
* O nome do campo que a função é chamada é passada no parâmetro <code>|name</code>, que é primeiramente checado em uma blacklist de campos que não devem ser mostradas nunca, (i.e. a chamada retorna nil em todas as circunstâncias). Se o campo não está na blacklist, é então checado contra uma whitelist. Se o nome do campo concorda, a chamada retornará qualquer valor fornecido localmente se é fornecido como segundo parâmetro não nomeado, ou o valor do Wikidata caso contrário.
* O nome é compulsório quando a blacklist ou a whitelist é usada, então o módulo retorna nil se não é fornecido.
* A blacklist é passada no parâmetro <code>{{parâmetro|suppressfields}}</code>
* A whitelist é passada no parâmetro <code>{{parâmetro|fetchwikidata}}</code>
=== Função getQualifierValue ===
O getQualifierValue é para usar quando queremos concordar o valor de um qualificador. Nós precisamos saber a propriedade e o valor da propriedade que a qualifica. Os parâmetros são:
* A propriedade ID passada no parâmetro não nomeado (ou <code>|1</code>)
* O valor alvo para esta propriedade em <code>|pval</code>
* O ID qualificador para o valor alvo em <code>|qual</code>
* O nome do campo onde é chamada para implementar "whitelisting" e "blacklisting" da propriedade nele
* A lista de campos para concordância ("whitelist") em <code>{{parâmetro|fetchwikidata}}</code> - aceita <code>{{parâmetro|fetchwikidata|ALL}}</code> para concordar todos os campos
* Lista opcional de campos para não serem exibidos ("blacklist") em <code>{{parâmetro|suppressfields}}</code>
* booleano opcional para especificar se apenas valores referenciados da propriedade são retornados (default para "no") em <code>{{parâmetro|onlysourced}}</code>
* Item ID opcional para acesso arbitrário (chamada carísssima!) em <code>{{parâmetro|qid}}</code>
==== Exemplo de getQualifierValue ====
Em {{Q|Q1513315}} existe uma propriedade {{Q|P793}}, que tem um valor {{Q|Q385378}}. Tem dois qualificadores, {{Q|P580}} e {{Q|P582}}. Para obter a data de início:
* <code><nowiki>{{#invoke:WikidataIB |getQualifierValue |P793 |pval=Q385378 |qual=P580 |name=xyz |fetchwikidata=ALL }}</nowiki></code>
Em [[Telescópio do Polo Sul]] retorna:
* {{#invoke:WikidataIB |getQualifierValue |P793 |pval=Q385378 |qual=P580 |name=xyz |fetchwikidata=ALL |qid=Q1513315}}
=== Função getLink ===
getLink retorna o rótulo para um Qid ligado a wiki para o artigo local (se o artigo existe).
=== Função getLabel ===
getLabel retorna o rótulo para uma Qid. Se o rótulo não existe, retorna o Qid.
Note que este é o rótulo dado para a entrada no Wikidata na mesma linguagem da corrende wIRChelp, se o rótulo existe.
* <code><nowiki>{{#invoke:WikidataIB |getLabel |Q29016906}}</nowiki></code> → {{#invoke:WikidataIB |getLabel |Q29016906}}
* <code><nowiki>{{#invoke:WikidataIB |getLabel |Q3621491}}</nowiki></code> → {{#invoke:WikidataIB |getLabel |Q3621491}}
=== Função getAT ===
getAT retorna o título do artigo para uma Qid. Se o título do artigo não existe, não retorna nada.
Note que este é o título do artigo na corrente wIRChelp, se o interwiki existe na entrada Wikidata.
* <code><nowiki>{{#invoke:WikidataIB |getAT |Q29016906}}</nowiki></code> → {{#invoke:WikidataIB |getAT |Q29016906}}
* <code><nowiki>{{#invoke:WikidataIB |getAT |Q3621491}}</nowiki></code> → {{#invoke:WikidataIB |getAT |Q3621491}}
=== Função predDni ===
predDni toma uma data de nascimento passada pelo usuário (tal como devolvida pela função getValue ou getPreferredValue ou da forma DD<nowiki>{{!}}</nowiki>MM<nowiki>{{!}}</nowiki>AAAA) e a insere dentro da [[predefinição:Dni]]. Também aceita os argumentos "|idioma=" caso se deseje exibir a data na variante do português angolano e a variável não nomeada "sem idade" quando não se desejar exibir a idade.
<nowiki>{{#invoke:WikidataIB |predDni |<data de nascimento obtida através da função getValue ou getPreferredValue acrescentada opcionalmente dos parâmetros "|idioma=" e "|sem idade" ou então a data por extenso como "01{{!}}04{{!}}2018">}}</nowiki>
Exemplo:
*<code><nowiki>{{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2016}}</nowiki></code> → {{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2016}}
*<code><nowiki>{{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2020|idioma=pt-ao|sem idade}}</nowiki></code> → {{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2020|idioma=pt-ao|sem idade}}
=== Função predMorte ===
Tal qual predDni, predMorte toma uma data de morte e uma data de nascimento passada pelo usuário (novamente: tal como devolvida pela função getValue ou getPreferredValue ou da forma DD<nowiki>{{!}}</nowiki>MM<nowiki>{{!}}</nowiki>AAAA) e a insere dentro da [[predefinição:Morte]]. Também aceita o argumento "|idioma=" caso se deseje exibir a data na variante do português angolano.
<nowiki>{{#invoke:WikidataIB |predMorte |<data de morte obtida através da função getValue ou getPreferredValue ou então a data por extenso como "01{{!}}04{{!}}2018">|<data de nascimento obtida através da função getValue ou getPreferredValue ou então a data por extenso como "01{{!}}04{{!}}2017">}}</nowiki>
Exemplo:
*<code><nowiki>{{#invoke:WikidataIB|predMorte|01{{!}}04{{!}}2018|01{{!}}04{{!}}2016}}</nowiki></code> → {{#invoke:WikidataIB|predMorte|01{{!}}04{{!}}2018|01{{!}}04{{!}}2016}}
=== Função formatDate* ===
formatDate aceita uma data no formato usual de mw.wikibase.entity:formatPropertyValues, como "1 de agosto de 30 a.C." como parâmetro 1 e o formata de acordo com os parâmetros df e bc.
* <code><nowiki>{{#invoke:WikidataIB |formatDate | 1 de agosto de 30 | bc=BC |df=dmy}}</nowiki></code> → {{#invoke:WikidataIB |formatDate | 1 de agosto de 30 | bc=BC |df=dmy}}
* <code><nowiki>{{#invoke:WikidataIB |formatDate | 1 de agosto de 20 | bc=BCE |df=mdy}}</nowiki></code> → {{#invoke:WikidataIB |formatDate | 1 de agosto de 30 | bc=BCE |df=mdy}}
* df = "dmy" / "mdy" / "y" - default é "dmy"
* bc = "BC" / "BCE" - default é "BCE"
<nowiki>*</nowiki> Não está funcionando normalmente
<!--Vou verificar o código antes de traduzir o restante, prefiro arrumar o formatDate primeiro.
== 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 {{parâmetro|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 {{parâmetro|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 {{parâmetro|author|[[George Orwell]]}}, for example, in the infobox. It also accepts {{parâmetro|authors}}. If the name of the field is on the whitelist, e.g. {{parâmetro|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}} }}
=== Coodenadas ===
The getCoords call will display the output of [[Template:Coord]] when supplied with the coordinates returned from Wikidata.There's an example in [[Template:Sandbox/Infobox biosphere reserve]] where it's coded like this:
<pre style="line-height:1.2em;">
|label20 = Coordinates
| data20 = {{#invoke:WikidataIB |getCoords |name=coordinates |suppressfields={{{suppressfields|}}} |fetchwikidata={{{fetchwikidata|}}} |{{{coordinates|}}} }}
</pre>
=== 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 wIRChelp, thus making the job of checking easier at the article level. If unsourced data is acceptable (!), set {{para|onlysourced|true}}. 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.-->
<!-- Mesma coisa para os exemplos
== Exemplos ==
Esta seção foi extraída de [[:en:Template:Infobox book/Wikidata/Sandbox/doc|Template:Infobox book/Wikidata/Sandbox/doc]].
=== Sem 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
| suppressfields =
| fetchwikidata = author; genre; pub_date; pages; dewey; congress
}}
</pre>
Fetches all of its values from Wikidata.
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| fetchwikidata = ALL
}}
</pre>
As shorthand, the {{para|fetchwikidata}} can be set to ALL to fetch all available fields.
Any of them can be suppressed by {{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.
=== Coordenadas ===
<pre style="line-height:1.2em;">
{{Testes/Infobox biosphere reserve
| fetchwikidata = ALL
}}
</pre>
Displays coordinates when used in an article where Wikidata has coordinates.
-->
== Adendo sobre o idioma de retorno ==
Por padrão, os rótulos retornados pelo módulo serão retornados por ''default'' na variante brasileira do português. Caso um editor deseje que o rótulo seja retornado em português europeu (essas são, infelizmente, as duas únicas variantes implementadas no Wikidata), ao utilizar qualquer uma das funções apresentadas, basta adicionar {{parâmetro|idioma|pt}} ou {{parâmetro|idioma|pt-ao}} (neste caso, os ''rótulos'' serão retornados em português europeu, e as datas serão retornadas no formato angolano) nos parâmetros da função.
==Ver também==
* [[Módulo:Wikidata]], lidando com o Wikidata de forma mais básica
{{Infocaixas Wikidata}}
<includeonly>{{testes outro ||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Categoria:!Módulos Wikidata]]
}}</includeonly>
<includeonly>{{MóduloWikidata}}</includeonly>
Este módulo foi projetado especificamente para implementar um mecanismo que move o controle de se os valores do Wikidata são usados em uma infobox do programador da predefinição no nível de design da infobox para o editor no nível de artigo. Ele só deve ser usado dentro de uma infobox.
== Uso ==
O módulo provê essas chamadas especificamente para o uso em infoboxes no presente:
# <code>getValue</code>
# <code>getPreferredValue</code>
# <code>getSourcedValue</code>
# <code>getCoords</code>
# <code>getQualifierValue</code>
A chamada getSourcedValue é mantida para compatibilidade com versões anteriores, pois agora é redundante para getValue que pode fazer o mesmo trabalho usando o parâmetro <code>{{parâmetro|onlysourced|true}}</code>.
Existem também essas chamadas úteis:
# <code>getLink</code>
# <code>getLabel</code>
# <code>getAT</code>
# <code>formatDate</code>
# <code>checkBlacklist</code>
# <code>predDni</code>
# <code>predMorte</code>
Chamadas generalizadas:
<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> |<local parameter>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getPreferredValue |<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> |<local parameter>}}</nowiki>
<nowiki>{{#invoke:WikidataIB |getSourcedValue |<PropertyID> |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 |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>
=== Função getValue ===
* getValue pode também pegar um parâmetro <code>{{parâmetro|qid}}</code> que é o ID do Wikidata para o artigo. Isto não será normalmente usado, mas está disponível para teste, embora faça a chamada ''cara''.
* A propriedade a ser retornada é passada na primeira propriedade não nomeada.
* O nome do campo que a função é chamada é passada no parâmetro <code>{{parâmetro|name}}</code>, que é primeiramente checado em uma blacklist de campos que não devem ser mostradas nunca, (i.e. a chamada retorna nil em todas as circunstâncias). Se o campo não está na blacklist, é então checado contra uma whitelist. Se o nome do campo concorda, a chamada retornará qualquer valor fornecido localmente se é fornecido como segundo parâmetro não nomeado, ou o valor do Wikidata caso contrário.
* O nome é compulsório quando a blacklist ou a whitelist é usada, então o módulo retorna nil se não é fornecido.
* A blacklist é passada no parâmetro <code>{{parâmetro|suppressfields}}</code>
* A whitelist é passada no parâmetro <code>{{parâmetro|fetchwikidata}}</code>
A função getValue aceitará um parâmetro booleano <code>{{parâmetro|onlysourced}}</code> que irá suprimir retornos dos valores do Wikidata que estão sem fontes ou somente referenciados a wIRChelp. A ausência do parâmetro, um parâmetro <code>|onlysourced</code> vazio e uma string vazia (<code>""</code>) têm como default para verdadeiro (i.e. somente os valores referenciados são retornados). Os valores <code>no</code>, <code>false</code> e <code>0</code> são tratados como falsos (i.e. todos os valores são retornados); qualquer outro valor é verdadeiro (embora <code>{{parâmetro|onlysourced|yes}}</code> seja recomendado para legibilidade).
A função getValue aceitará um parâmetro booleano <code>noicon</code> que suprimirá o ícone "edite no Wikidata" para quando o valor retornado for processado futuramente pela infobox (e.g. uma url). A ausência do parâmetro ou um parâmetro <code>|noicon</code> vazio default para falso (i.e. o parâmetro é adicionado). A string vazia (<code>""</code>) e os valores <code>no</code>, <code>false</code> e <code>0</code> são tratados como falsos; qualquer outro valor é verdadeiro (embora <code>{{parâmetro|noicon|true}}</code> seja recomendado para legibilidade).
Em ordem de lidar com o requerimento para datas em my, dmy ou y, getValue aceita um parâmetro <code>{{parâmetro|df}}</code> que pode pegar valores "dmy", "my" ou "y" - default é "dmy".
Se um artigo exigir o sufixo a.C., getValue retornará a data com esse sufixo;
Em uma invocação do módulo para extrair datas, getValue aceita um parâmetro <code>{{parâmetro|idioma}}</code> que pode receber o valor "pt" para formatar a data de acordo com o português europeu (única diferença se dá nas datas envolvendo o primeiro dia do mês. Por exemplo: [[1º de maio]] de [[2017]] (em português brasileiro) e [[1 de maio]] de [[2017]] (em português europeu)).
* A propriedade a ser retornada é passada na primeira propriedade não nomeada.
A função getValue aceitará um especificador de uso de unidade de medida (ao invés da unidade por extenso) na terceira propriedade não nomeada. A unidade de medida será exibida somente se o valor passado for <code>unidade</code>
=== Função getPreferredValue ===
A função getPreferredValue trabalha exatamente como getValue, tomando os mesmos parâmetros, mas se qualquer um dos valores para a propriedade tem um rank set preferido, ela retornará esses valores.
==== Exemplo ====
Obtendo o(s) nome(s) da {{Q|P170}} de {{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}}
=== Função getSourcedValue ===
* getSourcedValue trabalha exatamente como getValue, mas somente retorna valores que tenham referência a algo mais do que a wIRChelp. Não há garantias de fontes confiáveis, mas ajuda separar o joio do trigo.
==== Exemplo de getSourcedValue ====
De {{Q|Q151973}}:
[https://www.wikidata.org/w/index.php?title=Q151973&oldid=363049791 Burton correntemente] tem quatro valores para {{Q|P106}} no Wikidata:
* {{Q|Q10800557}} (referenciado a Dutch wIRChelp);
* {{Q|Q33999}} (referenciado a http://www.nytimes.com/1983/05/09/theater/theater-private-lives-burton-and-miss-taylor.html);
* {{Q|Q18939491}} (referenciado a wIRChelp);
* {{Q|Q2259451}} (não referenciado).
Usando getValue em [[Richard Burton]]:
* <code><nowiki>{{#invoke:WikidataIB |getValue |P106 |name=occupation |fetchwikidata=ALL}}</nowiki></code> -> {{#invoke:WikidataIB |getValue |P106 |name=occupation |fetchwikidata=ALL |qid=Q151973|onlysourced=no}}
Usando getSourcedValue em [[Richard Burton]]:
* <code><nowiki>{{#invoke:WikidataIB |getSourcedValue |P106 |name=occupation |fetchwikidata=ALL}}</nowiki></code> -> {{#invoke:WikidataIB |getSourcedValue |P106 |name=occupation |fetchwikidata=ALL |qid=Q151973}}
=== Função getCoords ===
* getCoords pode também pegar um parâmetro <code>{{parâmetro|qid}}</code> que é o ID do Wikidata para o artigo. Isto não será normalmente usado, mas está disponível para testes, embora faça a chamada ''cara''.
* As coordenadas do Wikidata são passadas a [[Predefinição:Coord]] que retorna o display como se fosse chamado manualmente.
* O nome do campo que a função é chamada é passada no parâmetro <code>|name</code>, que é primeiramente checado em uma blacklist de campos que não devem ser mostradas nunca, (i.e. a chamada retorna nil em todas as circunstâncias). Se o campo não está na blacklist, é então checado contra uma whitelist. Se o nome do campo concorda, a chamada retornará qualquer valor fornecido localmente se é fornecido como segundo parâmetro não nomeado, ou o valor do Wikidata caso contrário.
* O nome é compulsório quando a blacklist ou a whitelist é usada, então o módulo retorna nil se não é fornecido.
* A blacklist é passada no parâmetro <code>{{parâmetro|suppressfields}}</code>
* A whitelist é passada no parâmetro <code>{{parâmetro|fetchwikidata}}</code>
=== Função getQualifierValue ===
O getQualifierValue é para usar quando queremos concordar o valor de um qualificador. Nós precisamos saber a propriedade e o valor da propriedade que a qualifica. Os parâmetros são:
* A propriedade ID passada no parâmetro não nomeado (ou <code>|1</code>)
* O valor alvo para esta propriedade em <code>|pval</code>
* O ID qualificador para o valor alvo em <code>|qual</code>
* O nome do campo onde é chamada para implementar "whitelisting" e "blacklisting" da propriedade nele
* A lista de campos para concordância ("whitelist") em <code>{{parâmetro|fetchwikidata}}</code> - aceita <code>{{parâmetro|fetchwikidata|ALL}}</code> para concordar todos os campos
* Lista opcional de campos para não serem exibidos ("blacklist") em <code>{{parâmetro|suppressfields}}</code>
* booleano opcional para especificar se apenas valores referenciados da propriedade são retornados (default para "no") em <code>{{parâmetro|onlysourced}}</code>
* Item ID opcional para acesso arbitrário (chamada carísssima!) em <code>{{parâmetro|qid}}</code>
==== Exemplo de getQualifierValue ====
Em {{Q|Q1513315}} existe uma propriedade {{Q|P793}}, que tem um valor {{Q|Q385378}}. Tem dois qualificadores, {{Q|P580}} e {{Q|P582}}. Para obter a data de início:
* <code><nowiki>{{#invoke:WikidataIB |getQualifierValue |P793 |pval=Q385378 |qual=P580 |name=xyz |fetchwikidata=ALL }}</nowiki></code>
Em [[Telescópio do Polo Sul]] retorna:
* {{#invoke:WikidataIB |getQualifierValue |P793 |pval=Q385378 |qual=P580 |name=xyz |fetchwikidata=ALL |qid=Q1513315}}
=== Função getLink ===
getLink retorna o rótulo para um Qid ligado a wiki para o artigo local (se o artigo existe).
=== Função getLabel ===
getLabel retorna o rótulo para uma Qid. Se o rótulo não existe, retorna o Qid.
Note que este é o rótulo dado para a entrada no Wikidata na mesma linguagem da corrende wIRChelp, se o rótulo existe.
* <code><nowiki>{{#invoke:WikidataIB |getLabel |Q29016906}}</nowiki></code> → {{#invoke:WikidataIB |getLabel |Q29016906}}
* <code><nowiki>{{#invoke:WikidataIB |getLabel |Q3621491}}</nowiki></code> → {{#invoke:WikidataIB |getLabel |Q3621491}}
=== Função getAT ===
getAT retorna o título do artigo para uma Qid. Se o título do artigo não existe, não retorna nada.
Note que este é o título do artigo na corrente wIRChelp, se o interwiki existe na entrada Wikidata.
* <code><nowiki>{{#invoke:WikidataIB |getAT |Q29016906}}</nowiki></code> → {{#invoke:WikidataIB |getAT |Q29016906}}
* <code><nowiki>{{#invoke:WikidataIB |getAT |Q3621491}}</nowiki></code> → {{#invoke:WikidataIB |getAT |Q3621491}}
=== Função predDni ===
predDni toma uma data de nascimento passada pelo usuário (tal como devolvida pela função getValue ou getPreferredValue ou da forma DD<nowiki>{{!}}</nowiki>MM<nowiki>{{!}}</nowiki>AAAA) e a insere dentro da [[predefinição:Dni]]. Também aceita os argumentos "|idioma=" caso se deseje exibir a data na variante do português angolano e a variável não nomeada "sem idade" quando não se desejar exibir a idade.
<nowiki>{{#invoke:WikidataIB |predDni |<data de nascimento obtida através da função getValue ou getPreferredValue acrescentada opcionalmente dos parâmetros "|idioma=" e "|sem idade" ou então a data por extenso como "01{{!}}04{{!}}2018">}}</nowiki>
Exemplo:
*<code><nowiki>{{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2016}}</nowiki></code> → {{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2016}}
*<code><nowiki>{{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2020|idioma=pt-ao|sem idade}}</nowiki></code> → {{#invoke:WikidataIB|predDni|01{{!}}04{{!}}2020|idioma=pt-ao|sem idade}}
=== Função predMorte ===
Tal qual predDni, predMorte toma uma data de morte e uma data de nascimento passada pelo usuário (novamente: tal como devolvida pela função getValue ou getPreferredValue ou da forma DD<nowiki>{{!}}</nowiki>MM<nowiki>{{!}}</nowiki>AAAA) e a insere dentro da [[predefinição:Morte]]. Também aceita o argumento "|idioma=" caso se deseje exibir a data na variante do português angolano.
<nowiki>{{#invoke:WikidataIB |predMorte |<data de morte obtida através da função getValue ou getPreferredValue ou então a data por extenso como "01{{!}}04{{!}}2018">|<data de nascimento obtida através da função getValue ou getPreferredValue ou então a data por extenso como "01{{!}}04{{!}}2017">}}</nowiki>
Exemplo:
*<code><nowiki>{{#invoke:WikidataIB|predMorte|01{{!}}04{{!}}2018|01{{!}}04{{!}}2016}}</nowiki></code> → {{#invoke:WikidataIB|predMorte|01{{!}}04{{!}}2018|01{{!}}04{{!}}2016}}
=== Função formatDate* ===
formatDate aceita uma data no formato usual de mw.wikibase.entity:formatPropertyValues, como "1 de agosto de 30 a.C." como parâmetro 1 e o formata de acordo com os parâmetros df e bc.
* <code><nowiki>{{#invoke:WikidataIB |formatDate | 1 de agosto de 30 | bc=BC |df=dmy}}</nowiki></code> → {{#invoke:WikidataIB |formatDate | 1 de agosto de 30 | bc=BC |df=dmy}}
* <code><nowiki>{{#invoke:WikidataIB |formatDate | 1 de agosto de 20 | bc=BCE |df=mdy}}</nowiki></code> → {{#invoke:WikidataIB |formatDate | 1 de agosto de 30 | bc=BCE |df=mdy}}
* df = "dmy" / "mdy" / "y" - default é "dmy"
* bc = "BC" / "BCE" - default é "BCE"
<nowiki>*</nowiki> Não está funcionando normalmente
<!--Vou verificar o código antes de traduzir o restante, prefiro arrumar o formatDate primeiro.
== 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 {{parâmetro|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 {{parâmetro|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 {{parâmetro|author|[[George Orwell]]}}, for example, in the infobox. It also accepts {{parâmetro|authors}}. If the name of the field is on the whitelist, e.g. {{parâmetro|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}} }}
=== Coodenadas ===
The getCoords call will display the output of [[Template:Coord]] when supplied with the coordinates returned from Wikidata.There's an example in [[Template:Sandbox/Infobox biosphere reserve]] where it's coded like this:
<pre style="line-height:1.2em;">
|label20 = Coordinates
| data20 = {{#invoke:WikidataIB |getCoords |name=coordinates |suppressfields={{{suppressfields|}}} |fetchwikidata={{{fetchwikidata|}}} |{{{coordinates|}}} }}
</pre>
=== 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 wIRChelp, thus making the job of checking easier at the article level. If unsourced data is acceptable (!), set {{para|onlysourced|true}}. 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.-->
<!-- Mesma coisa para os exemplos
== Exemplos ==
Esta seção foi extraída de [[:en:Template:Infobox book/Wikidata/Sandbox/doc|Template:Infobox book/Wikidata/Sandbox/doc]].
=== Sem 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
| suppressfields =
| fetchwikidata = author; genre; pub_date; pages; dewey; congress
}}
</pre>
Fetches all of its values from Wikidata.
<pre style="line-height:1.2em;">
{{Infobox book/Wikidata/Sandbox
| fetchwikidata = ALL
}}
</pre>
As shorthand, the {{para|fetchwikidata}} can be set to ALL to fetch all available fields.
Any of them can be suppressed by {{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.
=== Coordenadas ===
<pre style="line-height:1.2em;">
{{Testes/Infobox biosphere reserve
| fetchwikidata = ALL
}}
</pre>
Displays coordinates when used in an article where Wikidata has coordinates.
-->
== Adendo sobre o idioma de retorno ==
Por padrão, os rótulos retornados pelo módulo serão retornados por ''default'' na variante brasileira do português. Caso um editor deseje que o rótulo seja retornado em português europeu (essas são, infelizmente, as duas únicas variantes implementadas no Wikidata), ao utilizar qualquer uma das funções apresentadas, basta adicionar {{parâmetro|idioma|pt}} ou {{parâmetro|idioma|pt-ao}} (neste caso, os ''rótulos'' serão retornados em português europeu, e as datas serão retornadas no formato angolano) nos parâmetros da função.
==Ver também==
* [[Módulo:Wikidata]], lidando com o Wikidata de forma mais básica
{{Infocaixas Wikidata}}
<includeonly>{{testes outro ||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Categoria:!Módulos Wikidata]]
}}</includeonly>