Chyba! …ukázka funkce šablony.

{{chyba}}

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í

editovat

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í

editovat

Vůbec nezadáno

editovat
{{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!

Zadáno mimo definiční rozsah

editovat
{{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!

Účinky

editovat

Zařazení do kategorie

editovat

Š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

editovat

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: Šablona {{Dohledatelná}} selhala, i když má všechny parametry, protože to tak zrovna chci!

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

editovat

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í

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

Parametry

editovat

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

editovat

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!xyz

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

editovat

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í.[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é 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. }} chyba ven

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

editovat

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

Reference

editovat
  1. (en)iferror, Help:Extension:ParserFunctions, Wiki Help na commons, mediawiki.org

Související šablony

editovat

Externí odkazy

editovat