Modul:Wikidata

Dokumentace  

Hlavní modul pro práci s daty na Wikidatech. Jeho základ byl převzat z test2wiki:Module:Wikidata, postupně je rozšiřován o nové funkce.

Modul je rozdělen do submodulů:

• Modul:Wikidata/lib – knihovna funkcí pro všechny další submoduly,
• Modul:Wikidata/i18n – lokalizace
• Modul:Wikidata/Filterers – filtrování tvrzení nebo vymezení podle kritérií,
• Modul:Wikidata/Formatters – formátování údajů,
• Modul:Wikidata/Sorters – seřazování údajů (podle abecedy, data apod.),
• Modul:Wikidata/cite – formátování referencí,
• Modul:Wikidata/sandbox – testovací modul,
• Modul:Wikidata/testcases – unit testing

Viz též seznam šablon, které tento modul využívají.

Použití

Podrobnější nápovědu naleznete na stránce Wikipedie:Wikidata/Přebírání do infoboxů.

Do šablony vložte {{#invoke:Wikidata|funkce|parametry = jako v šablonách}}.

Parametry a funkce označené hvězdičkou (*) nejsou plně podporované a není zatím doporučeno je využívat. Naopak parametry či funkce označené křížkem (†) jsou zastaralé a mohou být v brzké době odstraněny.

Přehled všech funkcí a parametrů

Funkce	Popis funkce	Parametr	Povinný	Popis parametru
formatStatements	získá data, vybere tvrzení, přefiltruje, seřadí a zformátuje jejich hodnoty a vrátí jejich seznam	id	ne	identifikátor položky (písmeno „q“ následované číslicemi) nebo vlastnosti (písmeno „p“ následované číslicemi) na Wikidatech, jejíž data se mají získat pro další práci s nimi (implicitně je to položka propojená s danou stránkou)
		of	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), ze kterého se získá entita, kterou modul skutečně využije, tak, že se použije první nejlepší hodnota vlastnosti
		page	ne	název stránky, jejíž položka se má použít pro získání údajů
		wiki	ne	zkratka projektu (např. enwiki), z něhož uvedená stránka pochází
		property	ano	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), jejíž hodnoty se mají zformátovat a zobrazit
		addlink	ne	pokud je „true“, na konci dat z repozitáře se objeví (e) odkazující přímo na vlastnost
		addclass	ne	pokud je „false“, potlačí obalení údajů CSS třídou (používat jen ve výjimečných případech)
		value-formatter	ne	submodul modulu Wikidata/Formatters (jeho podstránka), která se použije pro formátování hodnot, pokud výchozí submodul není vyhovující (seznam, návod)
		limit	ne	maximální počet hodnot, které se v seznamu zobrazí
		rank	ne	nutné postavení hodnoty v rámci tvrzení; může být all – použijí se všechna tvrzení; best – použijí se buď pouze tvrzení, která mají preferované postavení, nebo pouze ta s normálním postavením, pokud žádné preferované není; valid (implicitní) – použijí se jak preferovaná, tak normálně postavená tvrzení; preferred, normal, deprecated – použijí se pouze tvrzení s odpovídajícím postavením
		withtarget	ne	hodnota, jíž mají nabývat hledaná tvrzení (užitečné zejména pro funkce getCount a getQualifier)
		withqualifier	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), která musí být přiřazena dané hodnotě v tvrzení jako vymezení
		withqualifiervalue	ne	hodnota, jíž má nabývat vlastnost vymezení daná parametrem „withqualifier“
		withoutqualifier	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), která nesmí být přiřazena dané hodnotě v tvrzení jako vymezení
		withoutqualifiervalue	ne	hodnota, jíž nemá nabývat vlastnost vymezení daná parametrem „withoutqualifier“
		withunit	ne	identifikátor položky na Wikidatech
		withlabel*
		withsitelink*
		withlang	ne	kód jazyka, ve kterém mají být hodnoty jednojazyčného textu
		date	ne	datum ve formátu YYYY-MM-DD nebo „#now“ (dnešní datum), ke kterému mají být tvrzení platná
		sort	ne	způsob, jakým změnit implicitní pořadí jednotlivých hodnot; hodnota parametru odpovídá čárkou odděleným podstránkám modulu Wikidata/Sorters
		invert	ne	pokud je „true“ a je zadán způsob řazení („sort“), řazení bude sestupné, nikoliv výchozí vzestupné
		pattern	ne	pokud je typ hodnoty řetězec, je toto vzor pro zformátování, přičemž „$1“ nahrazuje daný řetězec
		autoformat	ne	pokud je „true“ a typ hodnoty řetězec, modul se na stránce dotyčné vlastnosti pokusí najít náhradu za pattern ( (P1630)) a aplikuje ji
		precision	ne	přizpůsobení formátu časových údajů (pokud je skutečná přesnost nižší, formát se přizpůsobí jí); 11 – 26. dubna 2024, 10 – duben 2024, 9 – 2024 atd.
		somevalue	ne	pokud je vyplněný, modul bude zobrazovat i speciální hodnotu „neznámá hodnota“ s tímto textem
		novalue	ne	pokud je vyplněný, modul bude zobrazovat i speciální hodnotu „bez hodnoty“ s tímto textem
		showqualifier	ne	čárkou oddělené identifikátory vlastností na Wikidatech (písmeno „p“ následované číslicemi nebo „time“), které se zobrazí v závorce za hodnotou, pokud jsou dané hodnotě jako vymezení přiřazeny
		showsource	ne	pokud je „true“, k datům z repozitáře se přidají reference
		max_ref	ne	maximální počet referencí, které se mají zobrazit
		showmore	ne	pokud je hodnota „true“, tak se v případě, že existuje více hodnot, než kolik povoluje limit, zobrazí na konci jejich seznamu text „… více na Wikidatech“ s odkazem přímo na vlastnost
		list	ne	pokud je hodnota „ul“ nebo „ol“, hodnoty budou vráceny jako HTML seznam („ol“ – číslovaný, „ul“ – odrážkový)
		separator	ne	znaky, jimiž se v seznamu oddělí jednotlivé hodnoty, kromě předposlední a poslední (implicitně čárka, neplatí pro HTML seznam)
		conjunction	ne	znaky, jimiž se v seznamu oddělí předposlední a poslední hodnota (implicitně spojka „a“, neplatí pro HTML seznam)
		qualifiers ...	ne	takto uvozený argument (např. „qualifiers precision“) bude použit pro výběr a formátování vymezení
		showtargetdata*	ne	podobné jako „showqualifier“, ovšem data se místo z vymezení získávají z cílové položky
		targetdate*	ne	podobné jako „date“, vztahuje se k údajům cílové položky
formatStatementsFromLua	funkce, kterou používají pouze jiné moduly a která je jinak shodná s formatStatements	entity	ne	tabulka s entitou, s níž má modul pracovat
getSitelink	vrátí odkaz na článek daného projektu	site / první nepojmenovaný	ne	zkratka projektu (implicitně „cswiki“)
		pattern	ne	vzor pro zformátování odkazu, kde „$1“ je název odkazovaného článku (implicitně „$1“)
		id	ne	identifikátor položky (písmeno „q“ následované číslicemi) nebo vlastnosti (písmeno „p“ následované číslicemi) na Wikidatech, jejíž data se mají získat pro další práci s nimi (implicitně je to položka propojená s danou stránkou)
		of	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), ze kterého se získá entita, kterou modul skutečně využije, tak, že se použije první nejlepší hodnota vlastnosti
		page	ne	název stránky, jejíž položka se má použít pro získání údajů
		wiki	ne	zkratka projektu (např. enwiki), z něhož uvedená stránka pochází
		addclass	ne	pokud je „true“, odkaz bude obalen CSS třídou
getLabel	vrátí štítek položky v daném jazyce	lang	ne	zkratka jazyka (implicitně „cs“)
		id	ne	identifikátor položky (písmeno „q“ následované číslicemi) nebo vlastnosti (písmeno „p“ následované číslicemi) na Wikidatech, jejíž data se mají získat pro další práci s nimi (implicitně je to položka propojená s danou stránkou)
		of	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), ze kterého se získá entita, kterou modul skutečně využije, tak, že se použije první nejlepší hodnota vlastnosti
		page	ne	název stránky, jejíž položka se má použít pro získání údajů
		wiki	ne	zkratka projektu (např. enwiki), z něhož uvedená stránka pochází
		addclass	ne	pokud je „true“, štítek bude obalen CSS třídou
getDescription	vrátí popisek položky v daném jazyce	lang	ne	zkratka jazyka (implicitně „cs“)
		id	ne	identifikátor položky (písmeno „q“ následované číslicemi) nebo vlastnosti (písmeno „p“ následované číslicemi) na Wikidatech, jejíž data se mají získat pro další práci s nimi (implicitně je to položka propojená s danou stránkou)
		of	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), ze kterého se získá entita, kterou modul skutečně využije, tak, že se použije první nejlepší hodnota vlastnosti
		page	ne	název stránky, jejíž položka se má použít pro získání údajů
		wiki	ne	zkratka projektu (např. enwiki), z něhož uvedená stránka pochází
		addclass	ne	pokud je „true“, popisek bude obalen CSS třídou
getAliases	vrátí aliasy položky v daném jazyce	lang	ne	zkratka jazyka (implicitně „cs“)
		limit	ne	maximální počet aliasů, který se má zobrazit
		id	ne	identifikátor položky (písmeno „q“ následované číslicemi) nebo vlastnosti (písmeno „p“ následované číslicemi) na Wikidatech, jejíž data se mají získat pro další práci s nimi (implicitně je to položka propojená s danou stránkou)
		of	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), ze kterého se získá entita, kterou modul skutečně využije, tak, že se použije první nejlepší hodnota vlastnosti
		page	ne	název stránky, jejíž položka se má použít pro získání údajů
		wiki	ne	zkratka projektu (např. enwiki), z něhož uvedená stránka pochází
		showmore	ne	jako u formatStatements
		list	ne
		separator	ne
		conjunction	ne
getBadges	vrátí štítek odznaku přiřazeného danému odkazu na článek	site	ano	zkratka projektu
		id	ne	identifikátor položky (písmeno „q“ následované číslicemi) nebo vlastnosti (písmeno „p“ následované číslicemi) na Wikidatech, jejíž data se mají získat pro další práci s nimi (implicitně je to položka propojená s danou stránkou)
		of	ne	identifikátor vlastnosti na Wikidatech (písmeno „p“ následované číslicemi), ze kterého se získá entita, kterou modul skutečně využije, tak, že se použije první nejlepší hodnota vlastnosti
		page	ne	název stránky, jejíž položka se má použít pro získání údajů
		wiki	ne	zkratka projektu (např. enwiki), z něhož uvedená stránka pochází
getCount	vrátí počet tvrzení podle daných kritérií	všechny parametry pro filtrování
getCurrentId	vrátí id položky, se kterou je stránka propojena
getId	Vrátí id položky propojené se zadanou stránkou. Není-li propojená a jedná se o přesměrování, následuje jej (i rekurzivně). Nepodaří-li se, zkusí další stránky, pokud jich bylo zadáno víc. Nedostane-li parametry přímo, zpracuje parametry předané volající šabloně.	první, druhý, ... nepojmenovaný	ne	název stránky na dané wiki (implicitně aktuální stránka)
		wiki	ne	zkratka projektu (např. enwiki), z něhož uvedená stránka pochází
getRawValue	použije stejná kritéria jako formatStatements, ovšem vrátí strojově čitelný (nezformátovaný) údaj	všechny parametry pro filtrování
		field	ne	pokud je typ hodnoty souřadnice, toto je její část, která se zobrazí; jedno z „latitude“, „longitude“, „precision“ a „globe“
getRawValueFromLua	jako getRawValue, pro použití v jiném modulu	entity	ne	tabulka s entitou, s níž má modul pracovat
getQualifier	vrací hodnoty vymezení nalezeného tvrzení	qualifier	ano	vlastnost vymezení, jejíž hodnoty mají být vráceny
		qualifiers ...	ne	takto uvozený argument (např. „qualifiers withlang“) bude použit pro výběr (při filtrování) vymezení
		stejné jako u funkce formatStatements
getRawQualifier	aplikuje chování funkce getRawValue na getQualifier	stejné jako u funkce getQualifier
formatEntity	lokalizuje položku zadanou pomocí jejího identifikátoru (pokusí se vytvořit lokální odkaz a zobrazit štítek)	id	ne	id položky, která se má zformátovat (jinak id položky, se kterou je stránka propojena)
entityExists	zjistí, zda entita (položka, vlastnost atd.) s daným identifikátorem existuje (přesměrování se považuje za existující)	id / první nepojmenovaný	ano	id položky, jejíž existenci zjišťujeme
		ifexpr	ne	pokud je „true“, negativní hodnota bude vrácena jako „0“, jinak (výchozí chování) jako prázdný řetězec (užitečné, pokud ve wikitextu používáme funkci #ifexpr:, a ne #if:)
isValidEntityId	zjistí, zda zadaný řetězec je platný identifikátor entity (položky, vlastnosti atd.)	id / první nepojmenovaný	ano	řetězec, jehož validitu testujeme
		ifexpr	ne	jako u entityExists
dumpWikidataEntity	zobrazí entitu v čitelné podobě, užitečná pro ladění a zavádění nových funkcí, nepoužívá se v šablonách nebo článcích	id	ne	identifikátor položky (písmeno „q“ následované číslicemi) nebo vlastnosti (písmeno „p“ následované číslicemi) na Wikidatech, jejíž entita se zobrazí (implicitně je to položka propojená s danou stránkou)

local i18n = {
    ["errors"] = {
        ["property-param-not-provided"] = "Property parameter not provided.",
        ["entity-not-found"] = "Entity not found.",
        ["unknown-claim-type"] = "Unknown claim type.",
        ["unknown-snak-type"] = "Unknown snak type.",
        ["unknown-datavalue-type"] = "Unknown datavalue type.",
        ["unknown-entity-type"] = "Unknown entity type.",
        ["unknown-value-module"] = "You must set both value-module and value-function parameters.",
        ["value-module-not-found"] = "The module pointed by value-module not found.",
        ["value-function-not-found"] = "The function pointed by value-function not found.",
        ["field-param-not-provided"] = "Field parameter not provided.",
        ["invalid-field"] = "Invalid field."
    },
    ["somevalue"] = "''unknown value''",
    ["novalue"] = "''no value''"
}

function getEntityFromId( id )
    return mw.wikibase.getEntity() --TODO support for getting other entities
end

function getEntityIdFromValue( value )
    if value['entity-type'] == 'item' then
        return 'q' .. value['numeric-id']
    elseif value['entity-type'] == 'property' then
        return 'p' .. value['numeric-id']
    else
        return formatError( 'unknown-entity-type' )
    end
end

function formatError( key )
    return '<span class="error">' .. i18n.errors[key] .. '</span>'
end


function formatStatements( options )
    if not options.property then
        return formatError( 'property-param-not-provided' )
    end

    --Get entity
    local entity = nil
    if options.entity and type( options.entity ) == "table" then
        entity = options.entity
    else
        entity = getEntityFromId( options.entityId )
    end

    if not entity then
        return '' --TODO error?
    end

    if not entity.claims or not entity.claims[string.lower(options.property)] then
        return '' --TODO error?
    end

    --Format statement and concat them cleanly
    local formattedStatements = {}
    for i, statement in pairs( entity.claims[options.property:lower()] ) do
        if options.rank == 'one' then
            return formatStatement( statement, options ) --Output only one value
        elseif (
                    ((not options.rank or options.rank == 'normal') and (statement.rank == 'normal' or statement.rank == 'preferred')) or
                    (options.rank == 'preferred' and statement.rank == 'preferred') or
                    (options.rank == 'all')
               ) then
            table.insert( formattedStatements, formatStatement( statement, options ) )
        end
    end
    return mw.text.listToText( formattedStatements, options.separator, options.conjunction )
end

function formatStatement( statement, options )
    if not statement.type or statement.type ~= 'statement' then
        return formatError( 'unknown-claim-type' )
    end

    return formatSnak( statement.mainsnak, options )
    --TODO reference and qualifiers
end

function formatSnak( snak, options )
    if snak.snaktype == 'somevalue' then
        return i18n['somevalue']
    elseif snak.snaktype == 'novalue' then
        return i18n['novalue']
    elseif snak.snaktype == 'value' then
        return formatDatavalue( snak.datavalue, options )
    else
        return formatError( 'unknown-snak-type' )
    end
end

function formatDatavalue( datavalue, options )
    --Use the customize handler if provided
    if options['value-module'] or options['value-function'] then
        if not options['value-module'] or not options['value-function'] then
            return formatError( 'unknown-value-module' )
        end
        local formatter = require ('Module:' .. options['value-module'])
        if not formatter then
            return formatError( 'value-module-not-found' )
        end
        local fun = formatter[options['value-function']]
        if not fun then
            return formatError( 'value-function-not-found' )
        end
        return fun( datavalue.value, options )
    end

    --Default formatters
    if datavalue.type == 'wikibase-entityid' then
        return formatEntityId( getEntityIdFromValue( datavalue.value ), options )
    elseif datavalue.type == 'string' then
        if options.pattern and options.pattern ~= '' then
            return formatFromPattern( datavalue.value, options )
        else
            return datavalue.value
        end
    elseif datavalue.type == 'time' then
        local Time = require 'Module:Time'
        return Time.newFromWikidataValue( datavalue.value ):toString()
    elseif datavalue.type == 'globecoordinate' then
        if not options.field then
            return formatError( 'field-param-not-provided' )
        elseif options.field == "latitude" or options.field == "longitude" or options.field == "precision" or options.field == "dimension" or options.field == "globe" then
            return mw.wikibase.getEntity().claims.p625[0].mainsnak.datavalue.value[options.field]
        else
            return formatError( 'invalid-field' )
        end
    else
        return formatError( 'unknown-datavalue-type' )
    end
end

function formatEntityId( entityId, options )
    local label = mw.wikibase.label( entityId )
    local link = mw.wikibase.sitelink( entityId )
    if link then
        if label then
            return '[[' .. link .. '|' .. label .. ']]'
        else
            return '[[' .. link .. ']]'
        end
    else
        return label or entityId --TODO fallback language?
    end
end

function formatFromPattern( str, options )
    return mw.ustring.gsub( options.pattern, '$1', str ) .. '' --Hack to get only the first result of the function
end

local p = {}

function p.formatStatements( frame )
    local args = frame.args

    --If a value if already set, use it
    if args.value and args.value ~= '' then
        return args.value
    end
    return formatStatements( frame.args )
end

function p.formatStatementsFromLua( options )
    --If a value if already set, use it
    if options.value and options.value ~= '' then
        return options.value
    end
    return formatStatements( options )
end

return p