Editace stránky Šablona:Chyba/doc

{{Podstránka s dokumentací}}
{{šablona|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 ve výsledném článku.
Pro dosažení těchto účelů působí šablona tyto účinky:
* přidání článku z hlavního prostoru wikipedie do chybové kategorie a
* označení místa chyby, kdekoli, nejen ve článcí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í <code><nowiki>{{Šablona|Chybu generující šablona}}</nowiki></code>
* popis chyby,
** především tedy přímo název chybějícho parametru: <code>hodnota parametru "NutnýVstup" chybí, ačkoli je požadována!</code>
** nebo s ukázkou hodnoty mimo rozsah: <code>hodnota "{{{NutnýVstup}}}" parametru "NutnýVstup" nebyla rozpoznána!</code>

Při editaci šablon a jejich rozšiřování o chybová hlášení se ujistěte, že nevzniknou žádná [[Nápověda:Neočekávaná odřádkování a mezery|nechtěná odřádkování]].

=== Příklady možných hlášení ===
==== Vůbec nezadáno ====
 <code><nowiki>{{Chyba|Šablona {{Šablona|Chybu generující šablona}} požaduje pro parametr "NutnýVstup" zadat nějakou hodnotu!}}</nowiki></code>
{{Chyba|Šablona {{Šablona|Chybu generující šablona}} požaduje pro parametr "NutnýVstup" zadat nějakou hodonotu!}}

==== Zadáno mimo definiční rozsah ====
 <code><nowiki>{{Chyba|Šablona {{Šablona|Chybu generující šablona}} hodnotu "{{{1}}}" zadanou do parametru "NutnýVstup" nerozeznala!}}</nowiki></code>
{{Chyba|Šablona {{Šablona|Chybu generující šablona}} hodnotu "{{{1}}}" zadanou do parametru "NutnýVstup" nerozeznala!}}

== Účinky ==
=== Zařazení do kategorie ===
Šablona typicky plní '''[[:Kategorie:Chybná volání šablon|kategorii Chybná volání šablon]]''' (přednastavená cílová kategorie), do ní ovšem vkládá pouze články z hlavního [[Nápověda:Jmenný prostor|jmenného prostoru]]. (To například pro odstínění stránek [[:Šablona:Dokumentace|dokumentací]].) Plnění zařizuje šablona {{šablona|Kategorie}}.

=== 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 [[w:cs:HyperText Markup Language|HTML]] kódu článku: Popis chyby je jen pomocí [[Kaskádové styly|CSS]] vlastnosti <code>display: none;</code> sice vyloučen ze zobrazování, ovšem text zadaný do šablony {{šablona|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:
<pre>{{chyba|Šablona {{Šablona|Dohledatelná}} selhala, ikdyž má všechny parametry, protože to tak zrovna chci!}}</pre>
Vygenerovaný výsledek:
{{chyba|Šablona {{Šablona|Dohledatelná}} selhala, ikdyž má všechny parametry, protože to tak zrovna chci!}}

=== 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 <code>/common/shared.css</code>:
<pre>.error {
	color: red;
	font-size: larger;
}</pre>

== Příklady použití ==
{| class="wikitable"
|-
! Kód
! Výsledek
! [[Kaskádové styly|CSS]] styl
|-
| {{šablona|Chyba}}
| {{Chyba}}
|
|-
| {{šablona|Chyba|}}
| {{Chyba|}}
|
|-
| {{šablona|Chyba|popis chyby}}
| {{Chyba|popis chyby}}
|
|-
| {{šablona|Chyba|<nowiki>popis chyby|kategorie=Jiná cílová kategorie</nowiki>}}
| <!--{{Chyba|popis chyby|kategorie=Jiná cílová kategorie}} Viz: [http://cs.wikipedia.org/w/index.php?title=Diskuse_k_%C5%A1ablon%C4%9B:Chyba&curid=551501&diff=6190533&oldid=6190079]-->{{Chyba|popis chyby}}
|
|-
| {{šablona|Chyba|<nowiki>popis chyby|skrytý=skrytý</nowiki>}}
| {{Chyba|popis chyby|skrytý=skrytý}}
| <code>display: none;</code>
|-
| {{šablona|Chyba|<nowiki>popis chyby|skrytý=</nowiki>}}
| {{Chyba|popis chyby|skrytý=}}
| <code>display: none;</code>
|}

== Parametry ==
Šablonu lze zavolat i bez parametrů: Implicitní hlášení pak je {{Chyba}}.
* <code><nowiki>{{{1}}}</nowiki></code> - nepojmenovaný volitelný (ale doporučený) parametr (první): Hodnotou je hlášení o chybě, text ke zobrazení.
* <code>skrytý</code> - volitelný parametr, text popisu chyby bude skryt, ale stále obsažen v HTML kódu výsledného článku (hledejte <code>title="Chyba v použití šablony!" class="error"</code>). 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.
* <code>kategorie</code> - 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í:
 <code><nowiki>abc{{Chyba|Chybný vstup!{{Chyba|skrytý=skrytý|Šablona {{Šablona|Chybu generující šablona}} hodnotu "{{{1}}}"<!--
 -->zadanou do parametru "NutnýVstup" nerozeznala!}}}}xyz</nowiki></code>
abc{{Chyba|Chybný vstup!{{Chyba|skrytý=skrytý|Šablona {{Š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 [[HyperText Markup Language|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 <code>class="error"</code>: Na tu totiž reaguje interní funkce <code>{{#iferror:</code>, šablona tedy má možnost detekovat chybu předanou z jiné šablony a reagovat na ní.<ref>{{en}}[http://www.mediawiki.org/wiki/Help:Extension:ParserFunctions#.23iferror iferror, Help:Extension:ParserFunctions], Wiki Help na commons, mediawiki.org</ref> 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ě.

{| class="wikitable"
|-
! Kód
! Výsledek
|-
| <code><nowiki>{{#iferror: {{#expr: a+1}} | error | O.K. }}</nowiki></code>
| {{#iferror: {{#expr: a+1}} | error | O.K. }}
|-
| <code><nowiki>{{#iferror: {{Vnitřně Volaná Šablona Možná Generující I Chybová Hlášení}} | error | O.K. }}</nowiki></code>
| {{#iferror: {{Vnitřně Volaná Šablona Možná Generující I Chybová Hlášení}} | error | O.K. }}
|-
| <code><nowiki>{{#iferror: {{Chyba|chyba dovnitř}} | error | O.K. }}</nowiki></code>
| {{#iferror: {{Chyba|chyba dovnitř}} | error | O.K. }}
|-
| <code><nowiki>{{#iferror: <span class="error">a</span> | error | O.K. }}</nowiki></code>
| {{#iferror: <span class="error">a</span> | error | O.K. }}
|-
| <code><nowiki>{{#iferror: <span class="error">chyba dovnitř</span> | {{chyba|chyba ven}} | O.K. }}</nowiki></code>
| {{#iferror: <span class="error">chyba dovnitř</span> | {{chyba|chyba ven}} | O.K. }}
|}
Pomocí takového mechanismu se lze přiblížit [[ExceptionHandling]]u jako má třeba [[Objektově orientované programování|objektové programování]]: Pak lze chybová hlášení používat na způsob třetí hodnoty [[w:cs:tříhodnotová logika|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.
<pre><nowiki>{{#iferror: {{IsInt|{{{num|}}}}}
| {{chyba|Hodnota "num" není číslo!}}
| {{IsInt|{{{num|}}}}}
}}</nowiki></pre>

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:
<pre><nowiki>{{#iferror: {{IsInt|{{{num|}}}}}
| {{chyba|Šablona {{Šablona|Tento příklad}} detekovala, že hodnota v parametru "num" není číslo!
    {{chyba|skrytý=skrytý|{{IsInt|{{{num|}}}}} }}
  }}
| {{IsInt|{{{num|}}}}}
}}</nowiki></pre>

== Odkazy ==
=== Reference ===
<references/>



=== Související články ===
* [[w:Exception (programování)]]
* [[w:Kategorie:Validace volání šablon]]

=== Externí odkazy ===
* [http://bits.wikimedia.org/skins-1.5/common/shared.css?283-16 shared.css], bits.wikimedia.org, zdroj definice třídy "error"

<includeonly>
<!-- Přidávejte KATEGORIE a INTERWIKI, prosíme, pod tento řádek -->
[[Kategorie:Šablony pomocné|{{PAGENAME}}]]

</includeonly>