Jump to content

Rozšíření:TemplateData

Sledovač problémů: #TemplateData
From mediawiki.org
This page is a translated version of the page Extension:TemplateData and the translation is 100% complete.
Languages:
This extension comes with MediaWiki 1.35 and above. To znamená, že jej nemusíte stahovat samostatně. Musíte se nicméně stále řídit pokyny k jeho použití.
Příručka k rozšířením MediaWiki
TemplateData
Stav rozšíření: stabilní
Implementace Značka , API
Popis Umožňuje ukládat, načítat a vizualizovat informace o šablonách
Autoři Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Nejnovější verze 0.1.2 (Průběžně aktualizováno)
Zásady kompatibility Vydání snímků současně s MediaWiki. Hlavní vývojová větev není zpětně kompatibilní.
PHP 5.4+
Změny v databázi Ne
Licence GNU General Public License 2.0 nebo novější
Stáhnout
Stáhněte si rozšíření
Git [?]:
Parametry
  • $wgTemplateDataEditorNamespaces
  • $wgTemplateDataUseGUI
Značky
‎<templatedata>
Použité háčky (hooks)
Čtvrtletní stahování 275 (Ranked 16th)
Veřejné wiki používající rozšíření 6,971 (Ranked 24th)
Přeložte rozšíření TemplateData, používá-li lokalizaci z translatewiki.net
Problémy Otevřené úkoly · Nahlásit chybu

Rozšíření TemplateData zavádí značku ‎<templatedata> a API, které společně umožňují editorům určit, jak mají být šablony a jejich parametry používány. Tato informace je k dispozici jako formátovaná tabulka pro koncové uživatele a jako JSON API, které umožňuje jiným systémům (např. VisualEditor ) vytvářet rozhraní pro práci se šablonami. Podrobnou nápovědu najdete na stránce Nápověda:TemplateData .

Instalace

  • Stáhněte soubor/y a vložte je do adresáře pojmenovaného TemplateData ve vaší složce extensions/.
    Vývojáři a přispěvatelé kódu by si místo toho měli nainstalovat rozšíření from Git pomocí:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData
  • Na konec vašeho souboru LocalSettings.php přidejte následující kód: 
    wfLoadExtension( 'TemplateData' );
  • Yes Dokončeno – Přejděte na stránku Special:Version vaší wiki a zkontrolujte, zda bylo rozšíření úspěšně nainstalováno.

Úpravy dat

Rozšíření TemplateData funguje tak, že ve wikitextu šablony stránky je definována značka ‎<templatedata> (volitelně může být také přenesena z jiné stránky). Toto je navrženo tak, aby bylo kompatibilní s běžným rozvržením, které má mnoho wiki při předávání dokumentace k šablonám ze samostatné stránky (není to však nutné). Obsah značky ‎<templatedata> musí být platný JSON ve formátu popsaném níže. Všimněte si, že všechny popisy musí být ve formátu prostého textu (v datech šablony není akceptován žádný wikitext).

Je-li na stránce zahrnut blok ‎<templatedata>, provede rozšíření TemplateData při ukládání stránky následující kontroly:

  1. Obsah musí být platný JSON.
  2. Každá položka ve struktuře JSON musí být očekávaného typu, jak je uvedeno níže (např. Objekt, pole nebo primitiv).
  3. U položek, které mají specifikovaný seznam možných hodnot (např. type parametr), musí hodnota v objektu JSON odpovídat jedné z těchto hodnot.

Pokud některá z těchto kontrol selže, server nebude moci ukládat a nad editační stránkou se zobrazí chybová zpráva.

U položek autovalue T4700 brání subst: fungovat v jakékoli šabloně, která je přidána do tagu, včetně tagů ‎<ref> a ‎<gallery>. Blok TemplateData se uloží správně, ale výsledný wikitext nebude při použití šablony správně analyzován.

Vyhněte se prosím použití {{#tag:templatedata}}, protože to znemožňuje použití editoru dat šablon.

Formát

Níže je vizualizovaná verze dat JSON, jak je definována na stránce šablony uzavřené značkami ‎<templatedata>‎</templatedata>. Formální specifikace je k dispozici v repozitáři TemplateData. Nejnovější verzi najdete na stránce Specification.md.

Objekt TemplateData

Objekt TemplateData je kořenový prvek JSON uzavřený v prvku ‎<templatedata> na stránce šablony.

Klíč Typ Popis
description InterfaceText nebo null Stručný popis šablony. Musí to být prostý text. Po vyplnění může být zobrazen jako titulek při úpravě jedné šablony a možná ve výsledcích vyhledávání, když si uživatelé vyberou jednu z mnoha. Výchozí hodnota je null.

→ For more details see: description

params Objekt obsahující objekty Param Objekt, který mapuje každý název parametru šablony na odpovídající objekt Param popisující vlastnosti tohoto parametru.

→ For more details see: params

paramOrder Pole obsahující řetězce názvů parametrů Logické pořadí, ve kterém by se měly parametry zobrazovat. Pole obsahuje přesně jednou každý klíč parametru. Každý řetězec musí být platným klíčem v objektu params.

→ For more details see: paramOrder

sets Pole obsahující
nastavení objektů 		Pole obsahující specifikace sady. Sada je skupina parametrů, které by měly být použity společně. Výchozí nastavení je []. Všimněte si, že funkce sets je stále ve vývoji.
format řetězec, buď inline nebo block Jak by mělo být uspořádáno zobrazení wikitextu šablony. Výchozí nastavení je inline. Další vlastní formáty najdete na stránce #Custom_formats.
maps Objekt obsahující Mapový objekt Objekt, který propojuje zjednodušené jméno spotřebitele dat šablony (tj. Citoid, Special:MyLanguage/Wikidata atd.) s objektem mapy, který zase spojuje název parametru spotřebitele s jedním nebo více odpovídajícími názvy parametrů šablony.

Param objekt

Klíč Typ Výchozí Popis
label InterfaceText null Krátký (velmi) název parametru. Zkuste zachovat méně než 20 znaků.

→ For more details see: label

description InterfaceText null Stručný popis parametru, aby uživatelé věděli, které mají vybrat ze seznamu možností.

→ For more details see: description

required boolean false Parametr je vyžadován pro to, aby šablona fungovala (true, pokud musí být zadán tento parametr).

→ For more details see: required

suggested boolean false Parametr je navržen pro šablonu, aby byla užitečná (true, pokud by měl být tento parametr uveden).

→ For more details see: suggested

deprecated booleovský nebo řetězec false Parametr je zastaralý. Hodnota může být řetězec instrukcí poskytujících uživateli návod, co místo toho lze udělat, nebo může být jednoduše true.

→ For more details see: deprecated

aliases Řetězce obsahující pole [] Seznam aliasů. Alias je alternativní název parametru, který lze použít namísto (nikoli vedle) primárního názvu. Aliasy nejsou dokumentovány v samostatném objektu Parameter. Pokud potřebují více informací, měly by být ve svých vlastnostech označeny jako "deprecated" (zastaralé).

→ For more details see: aliases

default InterfaceText null Výchozí hodnota použitá šablonou, není-li parametru nebo jeho popisu přiřazena žádná hodnota.

→ For more details see: default

autovalue řetězec null Dynamicky generovaná výchozí hodnota ve wikitextu, jako je dnešní datum nebo jméno editujícího uživatele. Bude často zahrnovat náhradu wikitextu, jako je {{subst:CURRENTYEAR}}.

→ For more details see: autovalue

example InterfaceText null Příklad textu parametru, který uživatelům pomůže vyplnit správnou hodnotu.

→ For more details see: example

type řetězec "unknown" Typ parametru pro (soft) typ hinting. Jeden z:
Řetězcová hodnota Typ parametru
"unknown" Předpokládaný typ, pokud není nastaven

→ For more details see: value ‘unknown’

"number" Jakákoli číselná hodnota (bez desetinných míst nebo oddělovačů tisíců)

→ For more details see: value ‘number’

"string" Jakákoli textová hodnota. Může obsahovat konce řádků.

→ For more details see: value ‘string’

"line" Krátké textové pole - používá se pro jména, štítky a jiná pole krátkých formulářů. Předpokládá se, že se jedná o text, u kterého se neočekává, že bude obsahovat konce řádků.

→ For more details see: value ‘line’

"boolean" Booleovská hodnota ('1' pro true, '0' pro false, '' pro neznámé), viz Tříhodnotová logika.

→ For more details see: value ‘boolean’

"date" Datum ve formátu ISO 8601, např. "2014-05-09" nebo "2014-05-09T16:01:12Z"

→ For more details see: value ‘date’

"url" URL, včetně protokolu, např. "http://www.example.org", "https://example.org", nebo "//example.org".

→ For more details see: value ‘url’

"wiki-page-name" Platný název stránky MediaWiki pro aktuální wiki. Nemusí existovat, ale pokud ano, měl by být platným názvem stránky, který by mohl být vytvořen.

→ For more details see: value ‘wiki-page-name’

"wiki-file-name" Platný název souboru MediaWiki pro aktuální wiki. Nemusí existovat, ale pokud ano, měl by být platný název souboru, který lze nahrát. Neměla by obsahovat jmenný prostor (např. "Foo.svg" ne "File:Foo.svg" nebo "Bild:Foo.svg").

→ For more details see: value ‘wiki-file-name’

"wiki-template-name" Platný název šablony MediaWiki pro aktuální wiki.

→ For more details see: value ‘wiki-template-name’

"wiki-user-name" Platné uživatelské jméno MediaWiki pro aktuální wiki. Nemusí existovat, ale pokud ano, mělo by to být platné uživatelské jméno, které by bylo možné vytvořit. Neměla by obsahovat jmenný prostor (např. "Foo", nikoli "User:Foo" nebo "Usario:Foo").

→ For more details see: value ‘wiki-user-name’

"content" Obsah stránky ve wikitextu, například styl textu, odkazy, obrázky, atd.

→ For more details see: value ‘content’

"unbalanced-wikitext" Hrubý wikitext, který by neměl být považován za samostatný obsah, protože je nevyvážený - například šablony spojující neúplný wikitext jako větší celek, například {{echo|before=<u>|after=</u>}}

→ For more details see: value ‘unbalanced-wikitext’

→ For more details see: type

inherits řetězec žádný
nahrazený 		Klíč názvu jiného parametru (musí to být platný klíč v objektu params). Aktuální parametrový objekt zdědí vlastnosti od zadaného objektu parametrů, přičemž místní vlastnosti potlačí zděděné.

→ For more details see: inherits

suggestedvalues Řetězce obsahující pole [] Nepovinná vlastnost parametru. Vytvoří seznam hodnot parametrů, které uživatelům pomohou vybrat požadovanou hodnotu. Aby se navrhované hodnoty zobrazily jako pole se seznamem ve VisualEditoru, musí být typ parametru nastaven na jeden z následujících: obsah, řádek, řetězec, číslo, neznámý nebo nevyvážený wikitext.

→ For more details see: suggestedvalues

Nastavení objektu

Klíč

Objekt nebo základní typ

Popis

label InterfaceText Krátký (velmi) název parametru. Zkuste zachovat méně než 20 znaků.
params Pole řetězců Jeden nebo více názvů parametrů, které mají být v sadě zahrnuty (každý musí být platným klíčem v objektu params). Parametr může být ve více sadách. Ne každý parametr musí být v sadě.

Struktura map

Mapy jsou jedinou datovou strukturou, která jde do hloubky několika úrovní. Stalo se běžné nazývat druhou úroveň "mapový objekt".

Klíč Typ Výchozí Popis
jméno spotřebitele objekt {} Objekt, který spojuje jméno spotřebitele s mapovým objektem, který zase spojuje název parametru spotřebitele s jedním nebo více odpovídajícími názvy parametrů šablony .

Názvy parametrů šablon mohou být zadány buď jako řetězec (jedno jméno), pole řetězců (několik jmen) nebo pole polí řetězců (několik sad názvů). Každý z těchto řetězců musí být platným klíčem v objektu params jinde v TemplateData stejné šablony.

Specifický parametr šablony může být ve více mapách a může být použit v hodnotách více klíčů v dané mapě, ale ne každý parametr šablony musí být v mapě.

Stručný příklad z Template:Cite_news#TemplateData anglické Wikipedie ilustruje strukturu objektů map. 

{
	"proveit": {
		"main": "title",
		"textarea": [
			"quote"
		]
	},
	"citoid": {
		"title": "title",
		"url": "url",
		"publisher": "publisher",
		"publicationTitle": "work",
		"date": "date",
		"ISSN": [
			"issn"
		],
		"ISBN": [
			"isbn"
		],
		"contributor": "others",
		"author": [
			[
				"first",
				"last"
			],
			[
				"first2",
				"last2"
			],
			[
				"first9",
				"last9"
			]
		],
		"editor": [
			[
				"editor-first",
				"editor-last"
			]
		]
	}
}

Text rozhraní (řetězec nebo objekt)

Volný textový řetězec prostého textu (tj. žádný wikitext nebo HTML) v jazyce obsahu wiki nebo objekt obsahující tyto řetězce klíčované kódem jazyka.

Výchozí hodnota pro všechna textová pole rozhraní je null.

Typ řetězce

Pokud se jedná o řetězec, musí obsahovat nelokalizovaný řetězec v jazyce obsahu místní wiki.

Typ objektu

Pokud se jedná o objekt, musí mít toto mapování:

Klíč Typ Popis
Kód jazyka Wikipedie řetězec Lokalizovaný řetězec pro uživatele daného jazyka rozhraní.

Příklad mapování objektu:

Klíč Hodnota
"en" "Welcome to Wikipedia"
"de" "Willkommen bei Wikipedia"
"fr" "Bienvenue sur Wikipédia"
"nl" "Welkom op Wikipedia"
"it" "Benvenuti su Wikipedia"
"es" "Bienvenidos a Wikipedia"
"ru" "Добро пожаловать в Википедию"

Příklad

Příklad struktury TemplateData, jak je uvedeno ve wikitextu na stránce šablony. 

<templatedata>
{
    "description": "Label unsigned comments in a conversation.",
    "params": {
        "user": {
            "label": "User's name",
            "type": "wiki-user-name",
            "required": true,
            "description": "User name of person who forgot to sign their comment.",
            "aliases": ["1"]
        },
        "date": {
            "label": "Date",
            "suggested": true,
            "description": {
                "en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
            },
            "aliases": ["2"],
            "autovalue": "{{subst:#time:Y-m-d}}"
        },
        "year": {
            "label": "Year",
            "type": "number"
        },
        "month": {
            "label": "Month",
            "inherits": "year"
        },
        "day": {
            "label": "Day",
            "inherits": "year"
        },
        "comment": {
            "required": false
        }
    },
    "sets": [
        {
            "label": "Date",
            "params": ["year", "month", "day"]
        }
    ],
    "maps": {
        "ExampleConsumer": {
            "foo": "user",
            "bar": ["year", "month", "day"],
            "quux": [
                "date",
                ["day", "month"],
                ["month", "year"],
                "year"
            ]
        }
    }
}
</templatedata>

Níže je uveden příklad, který by se zobrazil na stránce šablony:

Label unsigned comments in a conversation.

Template parameters[Edit template data]

ParameterDescriptionTypeStatus
User's nameuser 1

User name of person who forgot to sign their comment.

Userrequired
Datedate 2

Timestamp of when the comment was posted, in YYYY-MM-DD format.

Auto value
{{subst:#time:Y-m-d}}
Unknownsuggested
Yearyear

no description

Numberoptional
Monthmonth

no description

Numberoptional
Dayday

no description

Numberoptional
commentcomment

no description

Unknownoptional

API

Podívejte se na vygenerovanou nápovědu na Special:ApiHelp/templatedata. Ukázkové vyvolání (formátované pro čitelnost lidmi) je:

api.php?action=templatedata&titles=Template:Cite%20web&format=json [zkuste v ApiSandbox]

Tím se vrátí data šablony pro Šablona:Citovat web. Blok ‎<templatedata>...‎</templatedata> pro tuto šablonu je na stránce s dokumentací o přenesené šabloně, en:Template:Cite web/doc.

Přírůstky a změny JSON přijaté z API

Struktura JSON poskytovaná v reakci na požadavek API HTTP get se výrazně liší od struktury definované v bloku ‎<templatedata>...‎</templatedata>. V reakci na požadavek API provede rozšíření TemplateData následující změny objektu JSON:

  • Přidá dvě možnosti zabalení objektů:
    1. Celkový objekt stránky obsahující jeden nebo více objektů stránky
    2. Objekt s numerickým klíčem: stránka objektu
  • Přídavky nebo změny skutečného TemplateData objektu
    1. Přidejte klíč názvu title s názvem stránky, ze které byla požadována data (např. "Template:Cite web").
    2. Přidejte klíč sets
    3. Změňte všechny výskyty TemplateText, které jsou pouhými řetězci, na objekty s jediným klíčem pro aktuální kód jazyka Wikipedie
    4. Odstraňte všechny klíče inherits.
      • Přidejte všechny vlastnosti z parametru, ze kterého je definována dědičnost a které nejsou dědicem nahrazeny explicitně definovanými klíči v Parameter Object.
    5. Přidejte výchozí hodnoty pro všechny klíče v každém Parameter Object, které nebyly explicitně definovány nebo zděděny.

Vizualizované rozdíly v objektu JSON TemplateData dodané API

Objekty Wrapper přidané do JSON dodávané pomocí API
Nejsou definovány v objektu JSON uzavřeném značkami ‎<templatedata> na stránce šablony.
JSON Root
Klíč Typ Popis
pages Page Object Page object (obsahuje jeden klíč, kterým je číslo stránky). Pokud by bylo požadováno více stránek najednou, bude existovat více Page objektů.

Objekt stránky
Klíč Typ Popis
(číslo stránky) TemplateData Object TemplateData Object obsahující užitečné informace. Klíč je statické číslo stránky pro stránku šablony, ze které byla požadována data JSON.
Objekt TemplateData (přidáno pomocí API)
Následující klíč je přidán do kořene objektu JSON, který je uzavřen ve značkách ‎<templatedata> na stránce šablony.
Klíč Typ Popis
title řetězec Název stránky šablony (např. "Template:Cite web").
Tento klíč není součástí struktury JSON na stránce šablony. Je přidán do struktury pomocí softwaru MediaWiki na cestě k doručení přes API.
sets Pole obsahující nastavení objektů Pole obsahující specifikace sady. Sada je skupina parametrů, které by měly být použity společně.
Pokud na stránce šablony neexistuje, přidá se jako struktura do rozhraní poskytovaného API jako prázdné pole.
Objekty parametrů z API
Klíč Typ Popis
label InterfaceText Přeloženo do InterfaceText objektu, pokud již v tomto formátu není.
required boolean Pokud není definován, přidá se výchozí hodnota false.
description InterfaceText nebo null Pokud je definován jako řetězec, převeden na InterfaceText objekt. Pokud není definován, přidává se klíč s hodnotou null.
deprecated booleovský nebo řetězec Pokud není definován, přidá se výchozí hodnota false.
aliases Pole řetězců Pokud není definován, je přiřazeno výchozí prázdné pole (tj. []).
default řetězec Pokud není definován, je přiřazena výchozí hodnota "".
type řetězec Pokud není definován, je přiřazena výchozí hodnota "unknown".
inherits (odstraněno) Tento klíč je odstraněn a jsou přidány všechny zděděné klíče. Klíče definované pro aktuální parametr mají přednost a všem klíčům, které nejsou definovány ani na aktuálním parametru, ani na klíči, od kterého zdědí, je dána výchozí hodnota.
Text rozhraní (object nebo null):
Objekt obsahující řetězce klíčované kódem jazyka.
Klíč Objekt nebo
základní typ		 Popis
Objekt
(obsahující lokalizované řetězce podle kódu jazyka Wikipedie)
Pokud pole TemplateData na stránce šablony obsahuje řetězec, nikoli objekt s lokalizovanými řetězci, MediaWiki jej převede do objektu InterfaceText s řetězcem přiřazeným k názvu klíče zdroje Wikipedia v kódu jazyka Wikipedie. Výchozí hodnota pro všechna pole InterfaceText je null.
(Kód jazyka Wiki) řetězec Lokalizovaný řetězec pro uživatele daného jazyka rozhraní.

Příklad objektu JSON poskytovaného API

Odpověď na žádost API o strukturu TemplateData v části Příklad (výše) lze vidět:

Konfigurace

Proměnná Výchozí Popis
$wgTemplateDataUseGUI true Experimentální dialogové rozhraní pro úpravu templatedata JSON
$wgTemplateDataEditorNamespaces [ 10 ] The namespaces in which the template data editor appears when creating or editing a page. (úkol T189989)

Související odkazy

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:TemplateData/cs&oldid=6876044"