Šablona:Chyba/doc

Účel

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

Použití

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>.

Příklady možných hlášení

Vůbec nezadáno

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

Zadáno mimo definiční rozsah

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

Účinky

Zařazení do kategorie

Š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.

Skrytý popis chyby

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:

Stylování chyby ve zdrojovém kódu stránky

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;
}

Příklady použití

Kód	Výsledek	CSS styl
{{Chyba}}
{{Chyba|}}
{{Chyba|popis chyby}}
{{Chyba|popis chyby|kategorie=Jiná cílová kategorie}}
{{Chyba|popis chyby|skrytý=skrytý}}		display: none;
{{Chyba|popis chyby|skrytý=}}		display: none;

Parametry

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

• {{{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.

Skrytý popis

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

abcxyz

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ý".

Použití chyb

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í. 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ě.

Kód	Výsledek
{{#iferror: {{#expr: a+1}} | error | O.K. }}	error
{{#iferror: {{Šablona|Vnitřně Volaná Šablona Možná Generující I Chybová Hlášení}} | error | O.K. }}	O.K.
{{#iferror: {{Chyba|chyba dovnitř}} | error | O.K. }}	error
{{#iferror: <span class="error">a</span> | error | O.K. }}	error
{{#iferror: <span class="error">chyba dovnitř</span> | {{chyba|chyba ven}} | O.K. }}

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".

Praktické použití tříhodnotové logiky

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|}}}}}
}}

Odkazy

Související šablony

• {{smazat}}

Související články

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