Zobrazení zdroje stránky MediaWiki:UploadForm.js/dokumentace

__NOEDITSECTION__
<div style="background-color: #FFFFEE; border: 1px dotted #DDD000;">
<div style="margin: 10px;">
== Základní informace ==
{| style="font-size: xsmall; border: 1px solid black; width: 250px;" align="right"
! style="border-bottom: 1px solid black;" | [[MediaWiki:UploadForm.js]]
|-
|
* skript upravující formulář stránky [[Speciální:Upload|Načíst soubor]]
|-
|
* určeno pro '''MediaWiki v. 1.22.0'''
|}

Tento skript přepisuje formulář na stránce [[Speciální:Upload|Načíst soubor]]. Jsou přidána pole
* '''popis''' - zde uživatel zadává stručný popis souboru,
* '''zdroj''' - zde se uvádí zdroj souboru (vlastní práce, případně kniha, web, apod.),
* '''autor''' - pro uvedení autora souboru,
* '''datum''' - datum vzniku souboru (nepovinné pole),
* '''licence''' - menu s nabídkou možných licencí,
* '''kategorie''' - pro zařazení souboru do kategorií (nepovinné pole).

Skript skrývá či maže
* pole '''"Popis"''' původního formuláře,
* tlačítko '''"Načíst soubor"''' a
* řádek s '''[[MediaWiki:Edittools]]'''.

Je generováno nové tlačítko '''"Načíst soubor"''', které nejdříve spustí kontrolní a zpracovávací funkce a teprve potom formulář odešle na server.

Při odesílání jsou veškeré údaje zapracovány do [[Šablona:Soubor| šablony '''Soubor''']].
</div>
</div>
<br />

{| align="right"
 | __TOC__
|}
== Popisky a nápovědy ==

Na začátku skriptu jsou definovány některé popisky, které může uživatel s právy správce jednoduše měnit.

'''Příklad:'''
<source lang="javascript">
// Pole "Popis"
var popisek_popis = "Popis:";
var napoveda_popis = "";
</source>

Tato část kódu například definuje popisek a nápovědu k poli '''"Popis"'''. Pro změnu je nutné nový text vepsat do uvozovek. Chceme-li třeba změnit popisek z "Popis:" na "Popis souboru:" a přidat krátkou nápovědu, která se zobrazí pod zadávacím políčkem, upravíme kód takto:

<source lang="javascript">
// Pole "Popis"
var popisek_popis = "Popis souboru:";
var napoveda_popis = "Zde stručně popište soubor.";
</source>

== Pomocné funkce ==
=== Funkce nezadanyParametr(parametr) ===

<source lang="javascript">
// FUNKCE ZOBRAZUJÍCÍ CHYBOVOU HLÁŠKU
// nevyplnil-li některé důležité pole
function nezadanyParametr(parametr) {
  window.alert("Nebyl zadán " + parametr + " souboru.\nDoplňte prosím chybějící informaci a odešlete soubor znovu.");
  return false;
}
</source>

Jednoduchá funkce zobrazující chybovou hlášku. Je používaná funkcí <code>odeslatFormular()</code>.

== Obecné proměnné používané v celém kódu ==

<source lang="javascript">
// OBECNÉ PROMĚNNÉ POUŽÍVANÉ V CELÉM KÓDU

// odesílací formulář - je definován ve funkci zmenitFormular()
var formular = "";

// tlačítko "Odeslat" - je definováno ve funkci zmenitFormular()
var tlacitkoOdeslat = "";

// zvolená licence pro případ odškrtnutí volby "Vlastní dílo"
var zvolenaLicence = 0;
</source>

Na tomto místě jsou deklarovány proměnné, které jsou následně definovány uvnitř některé z funkcí, ale je potřeba je používat globálně v celém kódu. Zde jsou tedy jen vytvořeny proměnné pro odkaz na formulář a tabulku, která formulář obsahuje, a zvolenou licenci (která se nastaví v případě, že uživatel odškrtne dříve zaškrtnuté tlačítko "Vlastní dílo").

== Zpracovávající funkce ==

=== Funkce vlastniPraceFce() ===
<source lang="javascript">
// FUNKCE VYPLŇUJÍCÍ POLE V PŘÍPADĚ VLASTNÍ PRÁCE
function vlastniPraceFce() {
  if (formular.elements["vlastniprace"].checked == true) {
    formular.elements["mySource"].value = "{{vlastní dílo}}";
    formular.elements["mySource"].disabled = true;
    formular.elements["myAuthor"].value = "[[Uživatel:" + wgUserName + "|]]";
    formular.elements["myAuthor"].disabled = true;
    // licence: předvolení licence "CC-BY CZ"
    zvolenaLicence = formular.elements["wpLicense"].selectedIndex;
    formular.elements["wpLicense"].selectedIndex = 9;
    licenseSelectorCheck();
  } else {
    formular.elements["mySource"].disabled = false;
    formular.elements["myAuthor"].disabled = false;
    formular.elements["wpLicense"].selectedIndex = zvolenaLicence;
    licenseSelectorCheck();
  }
}
</source>

Při zatrhnutí možnosti '''"Vlastní dílo"''' v generovaném formuláři tato funkce testuje aktuální hodnotu zatržítka. Pakliže je '''"Vlastní dílo"''' zatrženo, funkce vyplní pole '''"Autor"''' autorovým uživatelským jménem s odkazem na jeho uživatelskou stránku a pole '''"Zdroj"''' vyplní [[Šablona:Vlastní dílo|šablonou '''Vlastní dílo''']]. Obě pole jsou přitom znepřístupněna editacím. Dále se změní licence na CC-BY 3.0 CZ. Pokud uživatel zatržítko odznačí, zpřístupní se mu všechna pole a může je editovat.

[[Šablona:Vlastní dílo|Šablona '''Vlastní dílo''']] je používána v rámci [[Šablona:Soubor|šablony '''Soubor''']]. Lze potom jednoduše soubory, které byly vytvořeny jako vlastní dílo, kategorizovat, nebo hromadně upravit jejich stránku pouhou editací této šablony.

Funkce <code>licenseSelectorCheck()</code> volaná v této části kódu je jednou z vlastních funkcí MediaWiki, která kontroluje označení licence a okamžitě zobrazí pod formulářem příslušnou [[:Kategorie:Licenční šablony|licenční šablonu]].

=== Funkce dnesniDatumFce() ===
<source lang="javascript">
// FUNKCE VYPLŇUJÍCÍ POLE DATUM DNEŠNÍM DATEM
function dnesniDatumFce() {
  if (formular.elements["dnesnidatum"].checked == true) {
    dnesni_datum = new Date();
 
    vyplneni_rok = dnesni_datum.getFullYear();
    vyplneni_mesic = (dnesni_datum.getMonth() + 1);
    if (vyplneni_mesic < 10) vyplneni_mesic = "0" + vyplneni_mesic;
    vyplneni_den = dnesni_datum.getDate();
    if (vyplneni_den < 10) vyplneni_den = "0" + vyplneni_den;
    vyplneni_data = vyplneni_rok + "-" + vyplneni_mesic + "-" + vyplneni_den;
 
    formular.elements["myDate"].value = vyplneni_data;
    formular.elements["myDate"].disabled = true;
 
  } else {
    formular.elements["myDate"].disabled = false;
  }
}
</source>

Tato funkce pracuje se zatržítkem '''"Dnešní datum"''' v generovaném formuláři. Je-li zaškrtnuto, funkce vyplní pole'''"Datum"''' dnešním datem v iso formátu RRRR-MM-DD. Usnadňuje tak uživateli upload souboru a zkracuje dobu vyplňování formuláře. Jakmile je '''"Dnešní datum"''' zaškrtnuto, je pole '''"Datum"''' znepřístupněno editacím.

== Funkce odesílající formulář odeslatFormular() ==

=== Čtení proměnných ===
Na začátku této funkce jsou čtena všechna pole, která uživatel vyplnil, a ukládána do nových proměnných. Nebylo-li vyplněno pole '''"Popis"''', '''"Zdroj"''' nebo '''"Autor"''', je volána funkce <code>nezadanyParametr(parametr)</code> s názvem nevyplněného pole v parametru. Zobrazí se chybová hláška a formulář není odeslán.

=== Kejkle s licencemi ===
[[MediaWiki:Licenses|Nabídka s licencemi]] je generována samotným PHP kódem MediaWiki. Kód MediaWiki ale informace z této nabídky zpracovává vlastním způsobem. Protože chceme informaci o licencích uvést uvnitř [[Šablona:Soubor|šablony '''Soubor''']], náš kus kódu čte informaci z nabídky, ukládá ji do vlastní proměnné a následně pro MediaWiki kód vrací (záměrně mylnou) informaci, že licence nebyla zadána. Kód MediaWiki proto licence nezpracuje a informace o nich je uvedena pouze v [[Šablona:Soubor|šabloně '''Soubor''']].

Chceme-li přidat novou licenci do menu '''"Licence"''' ve formuláři, je nutno přidat řádek do [[MediaWiki:Licenses]] v následujícím formátu:
<pre>
* Název šablony | Text zobrazený v menu
</pre>
;Název šablony : Pro každou licenci je nutno vytvořit šablonu, v níž bude text nebo odkaz na licenci. Její název zde uvedeme bez jmenného prostoru.
;Text zobrazený v menu : Text, který se zobrazí v nabídce '''"Licence"''' ve formuláři.

=== Úprava kategorií ===
Dále jsou zpracovány kategorie. Uživatel je vyzván, aby do jednoho pole uvedl všechny kategorie ke svému souboru a oddělil je čárkou. Zde se zadané informace rozdělí v místě čárek a z každé uvedené kategorie se vytvoří ''wikimarkup'' pro danou kategorii:

<pre>
[[Kategorie:Název kategorie]]
</pre>

Přidáná je automaticky kategorie podle toho, o jaký typ souboru jde (obrázek textový soubor, apod.).

=== Začlenění údajů do šablony Soubor ===

<source lang="javascript">
// začlenění údajů do šablony Soubor
  formular_popis = "{{Soubor\n|popis = ";
  formular_popis += mujPopis;
  formular_popis += "\n|zdroj = ";
  formular_popis += mujZdroj;
  formular_popis += "\n|datum = ";
  formular_popis += mujDatum;
  formular_popis += "\n|autor = ";
  formular_popis += mujAutor;
  formular_popis += "\n|licence = ";
  formular_popis += mujLicence;
  formular_popis += "\n}}\n";
  formular_popis += mujKategorie;
</source>

V této části jsou všechny předzpracované a zkontrolované informace zavzaty do [[Šablona:Soubor|šablony '''Soubor''']].

=== Vložení šablony Soubor zpátky do formuláře ===
MediaWiki zpracovává pouze informace uvedené v původní poli '''"Popis"'''. Proto je jí předloženo skryté pole s tímto názvem, do něhož je zapsána [[Šablona:Soubor|šablona '''Soubor''']] s informacemi uživatele.

=== Odeslání ===
Odeslání je provedeno JavaScriptovou simulací kliknutí myší na skryté původní tlačítko '''"Načíst Soubor"'''. Na server je odeslán soubor, jeho cílové jméno a popis obsahující informace zavzaté do [[Šablona:Soubor|šablony '''Soubor''']]. Veškeré zpracování informací se tedy děje na straně uživatele (v jeho vlastním počítači) a server dostává jen zpracované informace.

== Funkce pro vkládání řádků vytvoritRadek() ==

Tato funkce je používána ve funkci zmenitFormular() pro vložení nového řádku do tabulky obsahující formulář. Jejími parametry jsou:

;jmeno : jméno daného řádku podle políčka formuláře, použito pouze do názvu proměnných
;id : id daného políčka formuláře, odkazuje se na něj při zpracování údajů
;cislo_radku : číslo řádku v tabulce, kam má být vložen nový řádek
;nabidka_checkboxu : volitelný parametr definující <code>id</code> a <code>name</code> checkboxu, je-li přítomen, a je na něj odkazováno při zpracování údajů
;funkce_checkboxu : volitelný parametr zadávaný společně s <code>nabidka_checkboxu</code>, jde o jméno funkce použité při změně checkboxu (zaškrtnutí / odškrtnutí) - funkce samozřejmě musí existovat

== Funkce měnící formulář zmenitFormular() ==

=== Kontrola stránky ===
Začátek funkce kontroluje přítomnost či nepřítomnost některých proměnných. Je nutno, aby tato kontrola byla uvnitř funkce, neboť funkce je spouštěna až po načtení celé stránky a všech kontrolovaných elementů.

==== Kontrola načítacího formuláře ====
Nejprve se kontroluje, zdali je načtena správná stránka a načítací formulář.

==== Uploadwarning ====
<source lang="javascript">
  // pokud jsem již na další stránce s varováním, nespouštět funkci
  if(document.getElementById("uploadwarning")) return;
</source>

Skript nechceme spouštět ve chvíli, kdy se uživatel pokusil nahrát soubor (obrázek), ale došlo k problému (např. obrázek již existuje nebo je shodný s jiným obrázkem v databázi). V tom případě se ukáže element s <code>id="uploadwarning"</code>, přičemž jsme stále na stránce [[Speciální:Upload]]. Proto se zde testuje existence <code>id="uploadwarning"</code>. Jestliže takový element existuje, skript se zastaví.

==== wgUserName ====

<source lang="javascript">
  // pokud nejsem přihlášený, nespouštět funkci
  if(!wgUserName) return;
</source>


Proměnná <code>wgUserName</code> obsahuje jméno aktuálně přihlášeného uživatele. Není-li uživatel přihlášen, je její hodnota nastavena na <code>null</code> a na stránce se zobrazí výzva k přihlášení. Do této výzvy také nechceme skriptem zasahovat, proto se při neexistenci <code>wgUserName</code> skript přeruší.

==== wpForReUpload ====
Při načítání nové verze souboru je definována v URL adrese proměnná <code>wpForReUpload</code>. Pokud znovu načítáme soubor, tato funkce se zastaví (neboť není nutné znovu zadávat údaje o souboru, které se navíc na stránce souboru již nezobrazí).

==== Chybová hláška ====
V případě, že je již zobrazena chybová hláška, výkon funkce se rovněž pozastaví.

=== Definice proměnných ===

<source lang="javascript">
// odkaz na formulář
  formular = document.forms["mw-upload-form"];
 
  // odkaz na tabulku s formulářem v proměnné "tabulka"
  tabulka = document.getElementById("mw-htmlform-description");
</source>


Zde se proměnným deklarovaným [[#Obecné proměnné používané v celém kódu|vně funkce]] přiřazují jejich hodnoty. Jde o odkazy na formulář a tabulku formulář obsahující.

=== Schování prvků ===

<source lang="javascript">
// schovat tlačítko submit
  $('input[name="wpUpload"]').css({"visibility":"hidden", "position":"absolute"});
 
  // úplně smazat řádek s původním polem "Popis:"
  $(".mw-htmlform-field-HTMLTextAreaField").css({"visibility":"hidden", "position":"absolute"})
 
  // úplně smazat řádek s Edittools
  $(".mw-editTools").hide();
</source>

Další část kódu schovává původní tlačítko '''"Načíst soubor"''' a řádek s původním polem '''"Popis"''' a úplně maže [[MediaWiki:Edittools]]. Původní tlačítko '''"Načíst soubor"''' lze tedy pomocí skriptu ovládat.

=== Vkládání nových řádků ===
Zbytek funkce vkládá nové řádky s popisky, nápovědami a novými poli, do kterých uživatel zadácá požadované informace. Kód dynamicky generuje formulář a nastavuje atributy. Kód každého řádku se ve své podstatě opakuje (zřejmě bude možné ho časem zjednodušit). Pakliže je na počátku zadána nápověda k danému poli, zde se vygeneruje.

Pole licence je generováno samotným MediaWiki kódem. Tento skript pouze zpracovává informace z něj získané.

Nakonec je generováno i nové virtuální pole '''"Popis"''' a nové tlačítko '''"Načíst soubor"'''.

== Spuštění skriptu ==
<source lang="javascript">
// SPUSTIT
$(function() {
  zmenitFormular();
});
</source>
Je-li aktuálně načtena stránka [[Speciální:Upload]], spustí se při načtení celé stránky funkce <code>zmenitFormular()</code>.

== Použití a poznámky k verzi ==
Tento skript lze použít pouze v [[Special:Version|MediaWiki verze 1.22.0]]. Jiné verze mohou být (a také jsou) odlišné, používají jinou tabulku a poněkud jinak stavěný formulář.

Zároveň skript pracuje pouze tehdy, existuje-li stránka [[MediaWiki:Edittools]] a [[MediaWiki:Licenses]]. V případě neexistence [[MediaWiki:Edittools]] by došlo ke smazání jiného řádku skriptem a formulář by byl nefunkční. Pakliže by nebyly definovány licence v [[MediaWiki:Licenses]], formulář by se nezobrazil a nepracoval správně. Licence jsou zpracovávány složitěji, v případě přidání nebo odmazání licence ze seznamu je nutné zkontrolovat funkčnost skriptu.

V případě upgradu na vyšší verzi MediaWiki je nutno skript přepracovat, aby byl funkční.
[[Kategorie:Dokumentace]]