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
You can copy the blank boilerplate below to add new TemplateData to a template. Only the most common tags are included.

Syntax error in JSON / Bad JSON format
This error occurs if you attempt to save TemplateData that has certain types of invalid JSON code, such as duplicate keys (parameters) or trailing/missing commas, in VisualEditor or the 2017 wikitext editor (JavaScript-based editors).

"Syntax error in JSON" shows if you attempt to save such code in VisualEditor or the 2017 wikitext editor, while "Bad JSON format" shows if you attempt to open up such code in the TemplateData GUI editor, on template pages.

This error can come up quite frequently while editing a template's TemplateData. The most common mistakes that cause this error include excess commas (such as trailing commas), missing commas and missing quotation marks.


 * Examples of trailing commas:


 * Examples of missing commas:


 * Example of missing quotation marks:

To fix these errors, you can either look for the errors in the code yourself, or you can enter the JSON block into an external JSON validator, such as JSONLint, and it will highlight the problematic commas and keys that should be removed.

Due to a longstanding bug, users using the 2010 wikitext editor are able to save pages that have such invalid JSON (details: ), as the JavaScript parser is less strict and allows invalid JSON.

Required property "paramOrder(number)" not found.
This error occurs if you state a parameter in  that is not stated in  .The number in the square brackets refers to the parameter in   that is missing. It refers to its order in the sequence, but it is one less than its actual position, since  is an array; 0 is the first one, 1 is the second, etc.

To fix this, make sure all parameters stated in  are listed in  .Alternatively, you can remove the   object to remove this error.

Invalid value for property "paramOrder(number)".
This error occurs if you state a parameter in  that is not stated in  .The number in the square brackets refers to the parameter in   that shouldn't be there. It refers to its order in the sequence, but it is one less than its actual position, since  is an array; 0 is the first one, 1 is the second, etc.

To fix this, make sure all parameters stated in  are listed in  .Alternatively, you can remove the   object to remove this error.

Property "params.parametername.required" is expected to be of type "boolean".
This error occurs if you put quotation marks around the value of either  or.

These are boolean values, not strings, therefore they require no quotation marks. To fix this, remove any quotation marks around the values  or   for these parameters.

Property "format" is expected to be ...
If the  parameter exists but its value is not ,   or a valid format string, you will see the error message "Property "format" is expected to be "inline", "block", or a valid format string."

To fix this, make sure the value after  equals   or   and that there no spelling mistakes. Alternatively, if it's wikitext, make sure it contains a minimum of  and that there are no mistakes in the syntax that would normally cause a template to fail, such as duplicate equals signs or missing/duplicate curly brackets; see the section #Custom formats for the syntax for custom formats.Alternatively, you can remove the   parameter to remove this error.

Unexpected property "parametername".
This error occurs if you state a parameter in any object that is not a parameter of that object. This may be due to spelling mistakes, or you may have written the parameter of one object under another object that it doesn't belong to.

For example, you might have written the parameter  under the root TemplateData object instead of inside  :

Alternatively, if the unexpected parameter is under a template parameter inside, you'll see its name after "params.parametername." in the error.

To fix this, make sure your parameters are in their correct location, and make sure there aren't any spelling mistakes in the parameter names. Additionally, make sure you don't state any parameters that don't exist for an object. You can check which parameters exist for an object on this page, in the section.

Required property "params" not found.
This error occurs if there is no  object in the TemplateData.This is a necessary object, as it contains all the details of each parameter, so to fix this error, make sure it's added and that there are no spelling mistakes. See the section above on how to add the  parameter.

Omezení a zpětná vazba

 * Chybějící funkce — TemplateData is an example of a tool that was made available with few features, in hope that users would help to guide development of features that they desired. If you'd like to request new features for TemplateData, please let us know.
 * Prodlevy při zobrazování v šablonách — After adding TemplateData to a template, the metadata should be visible immediately when the template is opened in the visual editor. However, it is possible that it will take several hours before the metadata will show. You can force an update by making a null edit to the template page itself (not the documentation subpage). To perform a null edit, open the template page for editing, and save the page without making any change and without adding any edit summary.
 * Aktuální problémy — A list of current bugs and feature requests is available in the Wikimedia bug tracker.

Další nástroje

 * : A toolbar dialog window for entering template wikitext via an form built from TemplateData.
 * TemplateData Wizard: A tool that generates TemplateData through an interactive interface.
 * Skeleton TemplateData generator: A tool that reads the source wikicode of a template, tries to find all the parameters used and outputs a skeleton document with the parameters listed.
 * JSONLint: A tool that allows you to validate manually-written JSON to help find errors in the syntax.
 * List of all templates with TemplateData on this wiki
 * With dewiki template TemplateData template data is shown in a box, and the template is added to a category of templates with template data