Help:TemplateData/cs

 je rozšíření používané k ukládání informací o wikitext template a jejích parametrech, takže editační rozhraní může tyto informace načíst a zobrazit v editoru šablon, což uživatelům usnadní přidávání a editaci šablon na stránkách.

Od dubna 2019 je TemplateData součástí výchozího uživatelského prostředí pro všechny uživatele na všech Wikimedia wiki, když přidávají šablonu, včetně neregistrovaných uživatelů. Výchozí zdroj i vizuální editory jej nějakým způsobem začleňují. Používá se také jinde ve skriptech, nástrojích a miniaplikacích. Pokud máte vlastní wiki, budete muset nainstalovat Extension:TemplateData.

Přidání TemplateData do šablony v podstatě spočívá v vložení malého bloku kódu JSON (vysvětleno níže) na stránce dokumentace šablony. Existují dva hlavní způsoby, jak to provést, buď ručně nebo pomocí editoru TemplateData, grafického uživatelského rozhraní umístěného na stránkách "Edit"/"Edit source" (Upravit/Upravit zdroj) šablon na wiki s nainstalovanou příponou TemplateData. JSON obsahuje seznam parametrů s informacemi o každém parametru šablony i šablony jako celku. Ty jsou nastíněny níže.

Jakmile šablona obsahuje data TemplateData, zobrazí se tato informace v uživatelském rozhraní, když uživatel přidá šablonu, někdy místo původních informací nebo někdy jako doplňující informace. V některých případech se může změnit chování editoru při úpravách nebo vkládání šablony. To může uživatelům usnadnit identifikaci toho, co se šablonou potřebují při přidávání.

Historie
TemplateData byl původně vyvinut na začátku roku 2013 s ohledem na, což bylo v té době ve fázi testování MediaWiki. VisualEditor je hlavní vizuální editační rozhraní pro Wikimedia wikis a TemplateData mu umožnilo mít užitečnější rozhraní při přidávání šablon. To bylo oficiálně podporováno VisualEditor okamžitě. Vzhledem k tomu, že VisualEditor byl rozšířen na různé hlavní Wikimedia wiki jako výchozí funkce od roku 2013 do roku 2016, TemplateData se také stala jejich součástí.

V březnu 2018 společnost Sam Wilson vyvinula rozšíření, rozšíření editoru GUI pro výchozí zdrojový editor Wikimedia, (jinak známý jako editor wikitext 2010), jehož cílem je usnadnit proces přidávání šablon pomocí informací z TemplateData. V dubnu 2019 byl TemplateWizard nastaven jako výchozí součást editoru wikitext 2010 na všech Wikimedia wiki. To znamenalo, že TemplateData byla nyní výchozí součástí vizuálního editoru i zdrojového editoru na Wikimedia wikis.

Editor Strojového popisu šablony
Editor TemplateData je nástroj zabudovaný do rozšíření TemplateData pro přidání a úpravy TemplateData pomocí grafického uživatelského rozhraní.

Je dostupný přístupem na jakoukoli stránku šablony (nebo podstránky dokumentace) a kliknutím na "Upravit" (Edit) nebo "Upravit zdroj" (Edit source). Poté, co to uděláte, uvidíte tlačítko nad editační oblastí a nadpis stránky, který říká "".



Kliknutím na toto tlačítko vstoupíte do editoru TemplateData.

Editor umožňuje přidat parametry šablony a nastavit nejběžnější atributy. Pokud již editovaná stránka obsahuje blok TemplateData, když otevřete správnou stránku v editoru TemplateData, zobrazí se již dokumentované informace. V prvním poli můžete přidat nebo aktualizovat krátký popis šablony jako prostý text. Poté můžete pomocí tlačítek "Přidat navrhované parametry" (Add suggested parameter(s)) a "Přidat parametr" (Add parameter) zdokumentovat názvy a atributy parametrů, které šablona používá.

Můžete uvést název parametru, případné aliasy, štítek a popis, který se zobrazí uživatelům. Můžete také uvést příklad použití parametru. Jediným povinným polem je Název (Name) (první pole v každém řádku), kde se zaznamenává přesný název parametru rozlišující velká a malá písmena. V rozbalovací nabídce "Typ" (Type) můžete vybrat typ obsahu, který by měl parametr obdržet, například řetězec (pro odpovědi prostého textu), stránka (pro odkazy na jiné stránky) nebo data. Pokud šablona způsobí chybu, pokud je tento parametr ponechán prázdný, označte jej jako "Povinné" (Required). Pokud je parametr běžně používán nebo doporučován, označte jej jako "Navrhovaný" (Suggested). Tlačítko "Odstranit informace o parametru" (Remove parameter information) odstraní položku parametru z TemplateData.



Po dokončení dokumentace všech parametrů klikněte na "Použít" (Apply) a vložte předformátované TemplateData do otevřeného editačního pole. Stránku musíte uložit pomocí běžného tlačítka „Uložit“ (Save) pod editačním oknem.

Upozornění: Editor TemplateData umístí TemplateData na stránku šablony nebo na podstránku dokumentace. Určete, kam budou TemplateData přidána otevřením (úpravou) stránky, na kterou má být TemplateData umístěna. Pokud je však na stejnou šablonu umístěno více bloků TemplateData, bude použit pouze jeden z těchto bloků TemplateData. Pokud již na stránce existují TemplateData, musíte upravit stránku, na které byla TemplateData dříve umístěna, aby nedošlo k náhodnému vytvoření více bloků TemplateData.

Umístění Strojového popisu šablony
TemplateData musí být na stránce, kterou popisuje nebo musí být na ní transcluded. V šabloně se obvykle zabalí do značek. Při normálním vykreslování stránky zobrazuje automaticky generovanou dokumentaci, jak je uvedeno v #Příklad.

Struktura Strojového popisu šablony
Struktura TemplateData je založena na standardu JSON. Všechny popisy v TemplateData musí být v prostém textu (žádný wikitext, žádné odkazy, "atd.").

První věcí, kterou musíte udělat, je napsat pár značek, kdekoli na podstránce dokumentace šablony, takto:

To říká softwaru, že vše mezi těmito dvěma značkami je TemplateData a mělo by se na něj při použití šablony odkazovat.

Příklad
Popisy uvnitř TemplateData se řídí standardním rozvržením. Řekněme, že máte šablonu nazvanou "Commons", která slouží k propojení s kategorií Commons o daném tématu. Vyžaduje jeden povinný parametr: název kategorie v Commons. TemplateData bude vypadat asi takto:

To by se v šabloně zobrazilo takto:

{   "description": "Šablona pro propojení na kategorii commons o článku", "params": { "1": {           "label": "Commons kategorie", "description": "Kategorie commons, se kterou chcete propojit.", "default": "Category:CommonsRoot", "type": "string", "required": true }   } }

TemplateData parametry
Každý parametr pro TemplateData je uveden níže s popisem a příkladem. Jsou také uvedeny na Extension:TemplateData # Format.

Pořadí parametrů neovlivňuje funkčnost, pokud jsou uvnitř objektu zachovány například parametry.

O názvu parametru
Poznámka: Pokud pro parametr není nastaveno "required" (povinné), "suggested" (navrhované) ani "deprecated" (zastaralé), jeho stav se v dokumentaci TemplateData zobrazí jako "optional" (volitelné).

Až budete hotovi, stiskněte "save" (uložit). Pokud jste udělali chyby, nedovolí vám uložení (což je rušivé, ale znamená, že nic nemůžete zkazit). Pokud narazíte na chyby, vysvětlete na stránce zpětné vazby, co jste se snažili udělat a my vám rádi pomůžeme.

Pokud zneužíváte šablonu hack pro dynamické generování TemplateData, nelze ji před uložením zkontrolovat na chyby.

Všimněte si, že každá položka informací je uzavřena v uvozovkách (s výjimkou  a  ) a je oddělena od dalšího bitu čárkou (pokud není poslední).

Účinky parametru type
Parametr  může mít několik různých efektů nebo žádný efekt v závislosti na hodnotě a v závislosti na editoru šablon. Jeho účinky jsou uvedeny následovně.



Hodnota  je určena pro číselné hodnoty, včetně záporných hodnot a desetinných míst.


 * V aplikaci VisualEditor a editoru wikitext 2017 nemá  žádný viditelný efekt.
 * V editoru wikitext 2010 s TemplateWizard,, způsobí, že se ve vstupním poli zobrazí tlačítko "+" a "-" na obou stranách, které zvýší nebo sníží číselnou hodnotu ve vstupním poli, a uživatel může pouze psát čísla do pole. Tlačítka mohou také snížit počet na záporný.



Hodnota  je určena pro jakýkoli řetězec prostého textu.


 * Ve všech hlavních editorech (VisualEditor, 2017 wikitext editor a 2010 wikitext editor s TemplateWizard) nemá  ve srovnání s   žádný viditelný efekt.



Hodnota  je určena pro obsah, který má zůstat na jednom řádku.


 * V aplikaci VisualEditor a editoru wikitext 2017  brání vstupnímu poli parametru povolit nové řádky, které jsou obvykle v těchto editorech možné.
 * V editoru wikitext 2010 s TemplateWizard nemá  žádný viditelný efekt (vstupní pole ve výchozím nastavení neumožňuje v tomto editoru nové řádky).



Hodnota https:// je určena pro adresu URL, včetně internetového protokolu (např. https://).


 * V aplikaci VisualEditor a editoru wikitext 2017  způsobí, že vstupní pole zobrazí v levé části pole ikonu externího odkazu (čtverec se šipkou směřující ven) a po kliknutí uživatele odešle v červené barvě hodnotu URL, která obsahuje platný internetový protokol (např. „https: //“, „ftp: //“ nebo „//“), za kterým následuje nějaký text. Tento druhý efekt je podobný jako u nastavení "required" (požadováno), ale uživatele nevaruje, pokud se pokusí vložit šablonu bez platné adresy URL. Vyskytuje se také s jakémkoli nastavením stavu (například "suggested" (navrženo) nebo "deprecated" (zastaralé)).
 * V editoru wikitext 2010 s TemplateWizard nemá  žádný viditelný efekt.



Hodnota  je určena pro název stránky na wiki.


 * Ve všech hlavních editorech (VisualEditor, 2017 wikitext editor a 2010 wikitext editor s TemplateWizard),  způsobí, že vstupní pole parametrů zobrazí rozbalovací nabídku návrhů obsahující seznam stránek na wiki, například články na Wikipedii, které lze vybrat. Při hledání lze také definovat jmenný prostor. V aplikaci VisualEditor a editoru wikitext 2017 navíc vynutí, aby obsah vstupního pole zůstal na jednom řádku. Nemá žádný další viditelný efekt a nezabraňuje zadávání jiné stránky.



Hodnota  je určena pro jméno souboru hostované buď lokálně na wiki, nebo na Wikimedia Commons.


 * V aplikaci VisualEditor a editoru wikitext 2017 nemá  žádný viditelný efekt.
 * V editoru wikitext 2010 s TemplateWizard  způsobí, že vstupní pole parametrů zobrazí rozbalovací nabídku návrhů obsahující seznam souborů hostovaných lokálně i na Wikimedia Commons, které lze vybrat. Ukazuje také miniaturu souborů. Nemá žádný další viditelný efekt a nebrání tomu, aby byl soubor vložen.



Hodnota  je určena pro název šablony.


 * Ve všech hlavních editorech (VisualEditor, 2017 wikitext editor a wikitext editor 2010 s TemplateWizard)  způsobí, že vstupní pole parametrů zobrazí rozbalovací nabídku návrhů obsahující seznam šablon, které lze vybrat. V aplikaci VisualEditor a editoru wikitext 2017 navíc vynutí, aby obsah vstupního pole zůstal na jednom řádku. Nemá žádný další viditelný efekt a nezabraňuje zadávání jiné než šablony.



Hodnota  je určena pro uživatelské jméno na wiki.


 * Ve všech hlavních editorech (VisualEditor, 2017 wikitext editor a 2010 wikitext editor s TemplateWizard)  způsobí, že vstupní pole parametrů zobrazí rozbalovací nabídku návrhů obsahující seznam skutečných uživatelských jmen, které lze vybrat. V aplikaci VisualEditor a editoru wikitext 2017 navíc vynutí, aby obsah vstupního pole zůstal na jednom řádku. Nemá žádný další viditelný efekt a nezabraňuje zadávání jiného uživatele.



Hodnota  je určena pro wikitext obsahu stránky, například pro odkazy, obrázky nebo formátování textu.


 * V aplikaci VisualEditor a editoru wikitext 2017 nemá  žádný viditelný efekt.
 * V editoru wikitext 2010 s TemplateWizard,  dělá vstupní pole parametrů o jeden řádek vyšší a umožňuje nové řádky, které běžná vstupní pole v editoru wikitext 2010 nedělají.



Hodnota  je určena pro wikitext, který nemůže stát samostatně, tj. Postrádá otevírací nebo uzavírací značku nebo odkazuje na jiné části wikitextu.


 * V aplikaci VisualEditor a editoru wikitext 2017 nemá  žádný viditelný efekt.
 * V editoru wikitext 2010 s TemplateWizard,  dělá vstupní pole parametrů o jeden řádek vyšší a umožňuje nové řádky, které běžná vstupní pole v editoru wikitext 2010 nedělají.

S dalšími parametry


 * V aplikaci VisualEditor a editoru wikitext v roce 2017 přepíše  viditelné efekty   - pokud jsou oba nastaveny, nebude vstupní pole obsahovat ikonu URL ani červeně zvýrazněnou, když uživatel klepne odchod, aniž by zadal platnou adresu URL.
 * V editoru wikitext 2010 s TemplateWizard,  přepíše efekty   - hodnota "autovalue" nebude automaticky vložena do vstupního pole, pokud je typ parametru "number".

Vlastní formáty
Při úpravě hodnoty  vytvoříte vlastní formáty zadáním sady symbolů wikitextu pomocí některých předdefinovaných pravidel.


 * - začátek šablony
 * - obsah (např. řetězec, celé číslo nebo parametr). Toto podtržítko slouží k označení minimální délky hodnoty ve znakech a může být opakováno, například . Není-li této délky dosaženo, vyplní zbývající znaky mezerami. To lze použít k zarovnání všech znamének rovná se na konkrétní pozici za parametr (pokud se použije s   pro nové řádky).
 * - potrubí, trubka, svislá čára, svislítko (odděluje parametry)
 * - znaménko rovná se (předchází hodnotě parametru)
 * nebo stisknutí klávesy Enter - nový řádek (ve vstupním poli se zobrazí jako )
 * - mezera (lze použít s  k odsazení nových řádků)
 * - konec šablony

Wikitext by měl splňovat minimálně, jinak dojde k neplatnosti řetězce formátového řetězce.

Prázdná předloha
Můžete zkopírovat prázdnou boilerplate níže a přidat do šablony nová data TemplateData. Zahrnuty jsou pouze nejběžnější značky.

Chyba syntaxe ve formátu JSON / Bad JSON
K této chybě dochází, pokud se pokusíte uložit TemplateData, která obsahuje určité typy neplatných kódů JSON, například duplicitní klíče (parametry) nebo koncové nebo chybějící čárky, v VisualEditor nebo editoru wikitext 2017 (editory založené na JavaScriptu).

"Syntax error in JSON" (Chyba syntaxe v JSON) se zobrazí, pokud se pokusíte takový kód uložit do VisualEditoru nebo do wikitextového editoru 2017, zatímco „Bad JSON format“ (Špatný formát JSON)se zobrazí, pokud se pokusíte otevřít takový kód v editoru GUI TemplateData na stránkách šablon.

Tato chyba se může objevit poměrně často při úpravách TemplateData šablony. Mezi nejčastější chyby, které způsobují tuto chybu, patří nadbytečné čárky (například koncové čárky), chybějící čárky a chybějící uvozovky.


 * Příklady koncové čárky:


 * Příklady chybějících čárek:


 * Příklad chybějících uvozovek:

Chcete-li tyto chyby opravit, můžete buď hledat chyby v kódu sami, nebo můžete zadat blok JSON do externího validátoru JSON, například JSONLint. Ten zvýrazní problematické čárky a klíče, které by měly být odstraněny.

Díky dlouhodobé chybě mohou uživatelé používající editor wikitext 2010 ukládat stránky, které mají takový neplatný JSON (podrobnosti: ), protože analyzátor JavaScript je méně přísný a umožňuje neplatný JSON.

Požadovaná vlastnost "paramOrder(number)" nebyla nalezena.
K této chybě dochází, pokud uvedete parametr v, který není uveden v  .Číslo v hranatých závorkách odkazuje na parametr v  , který chybí. To odkazuje na jeho pořadí v sekvenci, ale to je o jeden méně než jeho skutečná pozice, protože  je pole; 0 je první, 1 je druhý atd.

Chcete-li to vyřešit, ujistěte se, že všechny parametry uvedené v  jsou uvedeny v  .Alternativně můžete odebrat objekt   a tuto chybu odstranit.

Neplatná hodnota pro vlastnost "paramOrder(number)".
K této chybě dochází, pokud uvedete parametr v, který není uveden v  .Číslo v hranatých závorkách odkazuje na parametr v  , který by tam neměl být. To odkazuje na jeho pořadí v sekvenci, ale to je o jedno méně než je jeho skutečná pozice, protože  je pole; 0 je první, 1 je druhý atd.

Chcete-li to vyřešit, ujistěte se, že všechny parametry uvedené v  jsou uvedeny v  .Alternativně můžete odebrat objekt   a tuto chybu odstranit.

Očekává se, že vlastnost params.parametername.required" bude typu "boolean".
K této chybě dochází, pokud uvozovky umístíte kolem hodnoty buď (required) nebo  (suggested).

Toto jsou booleovské hodnoty, nikoli řetězce, proto nevyžadují žádné uvozovky. Chcete-li to vyřešit, odeberte uvozovky kolem hodnot  nebo   pro tyto parametry.

Očekává se, že "formát" vlastnosti bude ...
Pokud parametr  existuje, ale jeho hodnota není ,   nebo platný řetězec formátu, zobrazí se chybová zpráva: "Vlastnost "format" by měla být "inline", "block" nebo platný formátový řetězec."

Chcete-li to vyřešit, ujistěte se, že hodnota po  se rovná   nebo   a že nedochází k pravopisným chybám. Pokud je to wikitext, ujistěte se, že obsahuje minimálně  a že v syntaxi nejsou chyby, které by normálně způsobily selhání šablony. Jako jsou duplicitní znaménka rovná se nebo chybějící nebo duplicitní složené závorky; viz část #Vlastní formáty pro syntaxi vlastních formátů. Alternativně můžete odstranit tuto chybu pomocí parametru.

Neočekávaná vlastnost "parametername".
K této chybě dochází, pokud uvedete parametr v libovolném objektu, který není parametrem tohoto objektu. Může to být způsobeno pravopisnými chybami nebo jste mohli napsat parametr jednoho objektu pod jiný objekt, ke kterému nepatří.

Například byste mohli napsat parametr  pod kořenový objekt TemplateData namísto uvnitř  :

Pokud je neočekávaný parametr pod parametrem šablony uvnitř, uvidíte jeho název za "params.parametername." omylem.

Chcete-li to vyřešit, ujistěte se, že jsou vaše parametry na správném místě a že v názvech parametrů nejsou žádné pravopisné chyby. Dále se ujistěte, že neuvádíte žádné parametry, které pro objekt neexistují. Na této stránce můžete zkontrolovat, které parametry objektu existují, v sekci.

Požadovaná vlastnost "params" nebyla nalezena.
K této chybě dochází, pokud v TemplateData není žádný objekt .Toto je nezbytný objekt, protože obsahuje všechny podrobnosti o každém parametru, takže tuto chybu opravte, ujistěte se, že je přidána a že nedochází k pravopisným chybám. Viz část výše o tom, jak přidat parametr.

Omezení a zpětná vazba

 * Chybějící funkce — TemplateData je příkladem nástroje, který byl zpřístupněn s několika funkcemi, v naději, že by uživatelé pomohli řídit vývoj funkcí, které požadovali. Pokud chcete požádat o nové funkce pro TemplateData, dejte nám prosím vědět na.
 * Prodlevy při zobrazování v šablonách — Po přidání TemplateData do šablony by měla být metadata viditelná okamžitě, jakmile se šablona otevře ve vizuálním editoru. Je však možné, že to bude trvat několik hodin, než se metadata zobrazí. Aktualizace můžete vynutit provedením nulové úpravy samotné stránky šablony (nikoli podstránky dokumentace). Chcete-li provést nulovou úpravu, otevřete stránku šablony pro úpravy a stránku uložte bez jakékoli změny a bez přidání souhrnu úprav.
 * Aktuální problémy — Seznam aktuálních chyb a požadavků na funkce je k dispozici v nástroji pro sledování chyb Wikimedia.

Další nástroje

 * : Dialogové okno panelu nástrojů pro zadávání wikitextů šablony pomocí formuláře vytvořeného z TemplateData.
 * TemplateData Wizard: Nástroj, který generuje TemplateData prostřednictvím interaktivního rozhraní.
 * Skeleton TemplateData generator: Nástroj, který čte zdrojovou šablonu wikicodu a snaží se najít všechny použité parametry a vydá dokument kostry s uvedenými parametry.
 * JSONLint: Nástroj, který vám umožní ověřit ručně napsaný JSON, který pomůže najít chyby v syntaxi.
 * Seznam všech šablon s TemplateData na této wiki
 * S dewiki template TemplateData jsou data šablony zobrazena v rámečku a šablona je přidána do kategorie šablon se šablonou data