Šablona:Chyba/doc

Toto je dokumentační podstránka šablony Šablona:Chyba

Obsahuje návod k použití, kategorie a další obsah, který není součástí samotné šablony.

Tato šablona je velmi často použita (případně i dalšími šablonami).

Každá změna se tak projeví na mnoha místech. Editujte ji s maximální obezřetností, jen pokud víte jistě, co děláte. Pokud úprava způsobí nečekané následky, urychleně ji vraťte. Veškeré experimenty byste měli raději provádět na pískovišti nebo ve svém uživatelském prostoru.

Tato šablona slouží pro označení povinných parametrů volaných šablon a pro validaci vstupních hodnot.

Účelem šablony je:

• ošetření chyb při volání šablon,
• určení jejich důvodu a
• určení jejich původu, pro umožnění snadného nalezení místa jejich projevu ve výsledném článku.

Pro dosažení těchto účelů působí šablona tyto účinky:

• kategorizace stránky do chybové kategorie a
• označení místa chyby

V textu chybového hlášení se mají objevit tyto informace:

• odkaz na šablonu, která chybová hlášení generuje, ideálně pomocí {{Šablona|Chybu generující šablona}}
• popis chyby,
  • především tedy přímo název chybějícho parametru: hodnota parametru "NutnýVstup" chybí, ačkoli je požadována!
  • nebo s ukázkou hodnoty mimo rozsah: hodnota "{{{NutnýVstup}}}" parametru "NutnýVstup" nebyla rozpoznána!

Při editaci šablon a jejich rozšiřování o chybová hlášení se ujistěte, že nevzniknou žádná nechtěná odřádkování.

Šablona používající chybu by také neměla do chybové kategorie kategorizovat sama sebe. Abyste se vyhnuli této nechtěné kategorizaci sama sebe, můžete použít následující volání: <includeonly>{{Chyba| ... }}</includeonly>.

{{Chyba|Šablona {{Šablona|Chybu generující šablona}} požaduje pro parametr "NutnýVstup" zadat nějakou hodnotu!}}

Šablona {{Chybu generující šablona}} požaduje pro parametr "NutnýVstup" zadat nějakou hodnotu!

{{Chyba|Šablona {{Šablona|Chybu generující šablona}} hodnotu "{{{1}}}" zadanou do parametru "NutnýVstup" nerozeznala!}}

Šablona {{Chybu generující šablona}} hodnotu "{{{1}}}" zadanou do parametru "NutnýVstup" nerozeznala!

Šablonou je typicky plněna kategorie:Údržba:Chybná volání šablon či jiné kategorie podle jmenného prostoru, kde došlo k chybě anebo určené volající šablonou hlásící chybu.

Kromě chybových hlášení, které může být v různých článcích různé, podle textu zadaného při volání, lze chybové hlášení stále dohledat i ve výsledném HTML kódu článku: Popis chyby je jen pomocí CSS vlastnosti display: none; sice vyloučen ze zobrazování, ovšem text zadaný do šablony {{chyba}} bude v kódu přítomen.

Ovšem jakmile se tento schovávací mechanismus použije a skutečně dojde na prohledávání HTML, samotné hlášení "Chyba!" stále nijak nepomůže k rozpoznání problému! Je na zodpovědnosti wikipedisty, autora šablony, který skrývá chybová hlášení, aby do textu zahrnul i odkaz na šablonu, ve které chyba nastala!

• Použijte text, jako by se měl čtenářům ukázovat, aby objasňoval potíž.
• Do textu zahrňte i odkaz na šablonu samotnou.

Příklad:

{{chyba|Šablona {{Šablona|Dohledatelná}} selhala, i když má všechny parametry, protože to tak zrovna chci!}}

Vygenerovaný výsledek: Šablona {{Dohledatelná}} selhala, i když má všechny parametry, protože to tak zrovna chci!

Chybová hlášení jsou stylována podle této definice CSS třídy, konkrétně ze souboru /common/shared.css:

.error {
	color: red;
	font-size: larger;
}

Šablonu lze zavolat i bez parametrů: Implicitní hlášení pak je Chyba!.

• {{{1}}} - nepojmenovaný volitelný (ale doporučený) parametr (první): Hodnotou je hlášení o chybě, text ke zobrazení.
• skrytý - volitelný parametr, text popisu chyby bude skryt, ale stále obsažen v HTML kódu výsledného článku (hledejte title="Chyba v použití šablony!" class="error"). Je-li tento parametr použit, žádné hlášení se čtenáři nezobrazí: Takové chování je vhodné například pro ošetření zastaralých parametrů používaných šablon, aby se všechna volání s takovými parametry mohla postupně opravit/nahradit. Na hodnotě parametru nezáleží, nepoužívá se, stačí i jen jeho přítomnost.
• kategorie - volitelný parametr, cílová kategorie, do které se má článek s chybou zařadit.

V situacích, kdy sice je cílem varovat o chybném použití šablony, ovšem bez nevzhledného porušení obsahu příliš dlouhým hlášením, lze použít vnořené skryté hálšení:

abc{{Chyba|Chybný vstup!{{Chyba|skrytý=skrytý|Šablona {{Šablona|Chybu generující šablona}} hodnotu "{{{1}}}"<!--
 -->zadanou do parametru "NutnýVstup" nerozeznala!}}}}xyz

abcChybný vstup!Šablona {{Chybu generující šablona}} hodnotu "{{{1}}}" zadanou do parametru "NutnýVstup" nerozeznala!xyz

Z příkladu je vidět, že se čtenáři v článcích zobrazí pouze minimalistická verze popisu chyby. Naproti tomu wikipedisté vědí, že takové články jsou kategorizovány a že i v samotném článku, v jeho zdrojovém HTML kódu, je podrobný popis chyby uveden a k dohledání.

Předané chyby lze takto detekovat ikdyž jsou generovány skrytě, parametrem "skrytý".

Kromě použití této šablony jako nápovědy při volání šablon a jako nástroje pro kategorizaci a následnou údržby Wikipedie lze chyby také detekovat v šablonách a reagovat na ně. Klíčová je zde CSS třída class="error": Na tu totiž reaguje interní funkce {{#iferror:, šablona tedy má možnost detekovat chybu předanou z jiné šablony a reagovat na ní.^[1] Na základě detekované chyby lze větvit další činnost: Buď vygenerovat vlastní chybu, anebo tuto předanou naopak ošetřit. Takové vnitřně detekované chyby jsou pak pouze dočasné hodnoty během zpracovávání šablony, do výsledku a do samotného článku se vůbec nemusí zahrnout: Záleží jen na wikipedistovi a jeho šabloně.

Pomocí takového mechanismu se lze přiblížit ExceptionHandlingu jako má třeba objektové programování: Pak lze chybová hlášení používat na způsob třetí hodnoty tříhodnotové logiky, vedla klasických "ano" a "ne".

Prostý příklad testování chyby předané z vnořené šablony: Nejdříve volána pro test chyby, pak znovu už pro hodnotu samotnou.

{{#iferror: {{IsInt|{{{num|}}}}}
| {{chyba|Hodnota "num" není číslo!}}
| {{IsInt|{{{num|}}}}}
}}

Komplexnější možné (už programátorsky překomplikované) testování chyby z volané vnořené šablony, navíc i s původním chybovým hlášením:

{{#iferror: {{IsInt|{{{num|}}}}}
| {{chyba|Šablona {{Šablona|Tento příklad}} detekovala, že hodnota v parametru "num" není číslo!
    {{chyba|skrytý=skrytý|{{IsInt|{{{num|}}}}} }}
  }}
| {{IsInt|{{{num|}}}}}
}}

• {{smazat}}

• exception
• Šablony:Validace a chybová hlášení