Šablona:Zastaralý parametr/doc

Šablona je k použití při inovaci šablon, kdy je potřeba přechodná doba pro odstranění zastaralých parametrů, které nelze odebrat okamžitě, protože se ještě stále někde používají.

Motivace

Existuje například šablona, u které je díky přestavbě potřeba nahradit parametry novými. V nové verzi šablony se zahrnou obě možnosti parametru, aby se zachovaly všechny stávající funkce. Aby však šablona nebyla takto „nafouknutá“ velkým množstvím synonymních parametrů, přebytečné z parametrů se touto šablonou označí jako zastaralé. Až jsou pak na všech stránkách, kde je infobox vložen, použita jen nová jména parametrů (mravenčí práce nadšených wikipedistů), může se konečně zastaralý parametr z kódu šablony odstranit.

Syntax

Pojmenovaný parametr "šablona" předává povinnou informaci o prvotní šabloně a je klíčový k informační funkci této pomocné debugovací šablony při dohledávání chyby v článku.

Další pojmenovaný parametr "parametr" je také povinný, k již zadanému názvu šablony přidává i název samotného zastaralého parametru, který se má hlásit. Zadáním názvu parametru editované šablony určíme, který parametr je zastaralý.

Třetím nutným parametrem je nepojmenovaný "parametr" {{{1}}}: Zpřesňuje podávanou informaci o už konkrétního hodnotu předmětného zastaralého parametru. Projeví se až u označení v článku, kde se použil; naopak zde v dokumentaci cedule, ani v dokumentaci editované šablony se ještě nijak neprojeví. Nicméně při editaci předmětné šablony je potřeba její zastaralý parametr na ceduli nějak funkčně napojit, a to právě přiřazením hodnoty zastaralého do cedule.

Vložení

Ceduli definující zastaralý parametr je třeba vložit přímo do kódu editované šablony, tedy stačí 1x a na jediné místo.

Co vložit

{{Zastaralý parametr|šablona=sídlo světa|param=gps|{{{gps}}}|comment=správná šablona, v ní však zastaralý parametr, k dohledání podle místa použití a pomocí místní neprázdné hodnoty}}

Tímto způsobem šablona zakategorizuje (umožní dohledání a opravu) všechny články (obecněji stránky), kde je předmětný zastaralý parametr použit, tedy ke mu byla explicitně dána nějaká neprázdná hodnota.

Aby šablona detekovala všechny takové výskyty, kde je zastaralý parametr výslovně použit, tedy případy s jakoukoli výslovně předanou hodnotou, i prázdnou ("", ne však null), je potřeba vložit ceduli s náročnějším zavoláním zastaralého parametru:

{{Zastaralý parametr|šablona=sídlo světa|param=gps|{{#if:{{{gps|}}}|{{{gps|}}}|{{#if:{{{gps}}}||výslovně použit, prázdný}}}}|comment=správná šablona, v ní výslovně použit zastaralý parametr}}

kde "gps" je název zastaralého parametru z ukázkového příkladu, v reálném použití samozřejmě k nahrazení názvem hlášeného zastaralého parametru.

Kam vložit

Tuto ceduli vložte na samý začátek editované šablony (lze i na konec, jsou tyto dvě možnosti), kde na jedné straně nebude kolidovat s funkcí či účelem té šablony, na druhou stranu ovšem do takové oblasti kódu, kde není omezeno ani vložení do článků, ani zobrazení v dokumentaci: V obou těchto místech se šablona-cedule má projevit.

Účinky

Šablona se projeví dvojím způsobem, na dvou různých místech:

1) Na stránce šablony se zobrazí cedule hlášení. Ne však ve stránkách-článcích, kde je šablona-se-zastaralým-parametrem použita: Nezúčastněný čtenář není takto velkým hlášením obtěžován. (i k tomuto slouží výslovné určení názvu editované šablony, která v sobě má zastaralý parametr - šablona-cedule si vnitřně tento název porovnává s aktuální stránkou). Šablona je zároveň zařazena do kategorie Údržba:Šablony se zastaralými parametry.

2) Na stránce, kde je zastaralý parametr použit, se pak šablona sama projeví už s konkrétní hodnotou, např.:

{{Zastaralý parametr|šablona=sídlo světa|param=gps|gps_hodnota|comment=správná šablona, v ní však zastaralý parametr, k dohledání místa použití, mj. i pomocí místní hodnoty}}

a) Výsledek z šablony, a snad přímo z toho parametru, není graficky označen: Text chybového hlášení je skrytý CSS vlastností "hidden", ovšem je v HTML kódu stránky přítomen a tedy dohledatelný. (Což se šablona-cedule právě snaží co nejvíce zjednodušit.)

b) Stránka, kde se zastaralý parametr použil, je automaticky zakategorizována do kategorie Údržba:Články se zastaralými parametry v šablonách.

Vstupy

povinné

{{{šablona|{{{stacktrace}}}}}} - název šablony (bez namespace), která v sobě má definovaný a provozuje hlášený zastaralý parametr, která je právě editována, do které se tato cedule přidává. Použije se do skrytého chybového hlášení, jako návodčí informace, pro snazší opravování.
{{{parametr|{{{param}}}}}} - povinný název zastaralého parametru (jen text názvu), tedy vstupu šablony, do které se tato cedule přidává
{{{1}}} - hodnota vstupu, zde v docu zatím prázdná; důležitý vstup až při použití v článku, pro detekovanou momentální hodnotu, k vložení tam do chybového hlášení, skrytě

volitelné

{{{komentář|{{{comment|{{{2}}}}}}}}} - zprávička, nijak nepřednastavená: Použije se jak do cedule ke zobrazení v šabloně, tak do chybového hlášení při použití parametru, skrytě.
{{{kat-chyb|Údržba:Články se zastaralými parametry v šablonách}}} - možnost změnit cíl zakategorizování právě označovaného článku (stránky), kde je zastaralému parametru nastavována (neprázdná?) hodnota; zakategorizován článek každopádně nějak bude.
{{{kat-šablon|Údržba:Šablony se zastaralými parametry}}} - možnost změnit cíl zakategorizování právě označované šablony; zakategorizována šablona každopádně nějak bude.

Související šablony