Šablona:Chyba/doc

{{chyba}}

Úč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 na výsledné stránce.

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

• přidání stránky z hlavního prostoru Wikiverzity do chybové kategorie a
• označení místa chyby, kdekoli, nejen na stránkách hlavního prostoru.

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

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:Stránky s chybným voláním šablon (přednastavená cílová kategorie), do ní ovšem vkládá pouze stránky z hlavního jmenného prostoru. (To například pro odstínění stránek dokumentací.) Plnění zařizuje šablona {{Kategorie}}.

Skrytý popis chyby

Kromě chybových hlášení, které může být na různých stránká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 stránky: 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 uživatele, tedy 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é stránky (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á stránka 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 náhodnému návštěvníkovi se na stránce zobrazí pouze minimalistická verze popisu chyby. Naproti tomu aktivní uživatelé vědí, že takové stránky jsou kategorizovány a že i v samotné stránce, v jejím zdrojovém HTML kódu, je podrobný popis chyby uveden a k dohledání.

Předané chyby lze takto detekovat, i když 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 Wikiverzity 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é stránky se vůbec nemusí zahrnout: Záleží jen na uživateli 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}}

Externí odkazy

• w:Exception
• w:Kategorie:Validace volání šablon
• shared.css, bits.wikimedia.org, zdroj definice třídy "error"