MediaWiki:UploadForm.js/dokumentace

Z WikiSkript

Základní informace

MediaWiki:UploadForm.js
  • určeno pro MediaWiki v. 1.22.0

Tento skript přepisuje formulář na stránce 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 šablony Soubor.


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: 

// Pole "Popis"
var popisek_popis = "Popis:";
var napoveda_popis = "";

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: 

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

Pomocné funkce

Funkce nezadanyParametr(parametr)

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

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

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

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

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()

// 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();
  }
}

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í š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 je používána v rámci š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 licenseSelectorCheck() 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 licenční šablonu.

Funkce dnesniDatumFce()

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

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 nezadanyParametr(parametr) s názvem nevyplněného pole v parametru. Zobrazí se chybová hláška a formulář není odeslán.

Kejkle s licencemi

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ř š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 š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: 

* Název šablony | Text zobrazený v menu
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: 

[[Kategorie:Název kategorie]]

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

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

V této části jsou všechny předzpracované a zkontrolované informace zavzaty do š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 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 š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í id a name 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 nabidka_checkboxu, 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

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

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 id="uploadwarning", přičemž jsme stále na stránce Speciální:Upload. Proto se zde testuje existence id="uploadwarning". Jestliže takový element existuje, skript se zastaví.

wgUserName

  // pokud nejsem přihlášený, nespouštět funkci
  if(!wgUserName) return;


Proměnná wgUserName obsahuje jméno aktuálně přihlášeného uživatele. Není-li uživatel přihlášen, je její hodnota nastavena na null 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 wgUserName skript přeruší.

wpForReUpload

Při načítání nové verze souboru je definována v URL adrese proměnná wpForReUpload. 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

// 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");


Zde se proměnným deklarovaným vně funkce přiřazují jejich hodnoty. Jde o odkazy na formulář a tabulku formulář obsahující.

Schování prvků

// 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();

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

// SPUSTIT
$(function() {
  zmenitFormular();
});

Je-li aktuálně načtena stránka Speciální:Upload, spustí se při načtení celé stránky funkce zmenitFormular().

Použití a poznámky k verzi

Tento skript lze použít pouze v 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í.

Citováno z „https://www.wikiskripta.eu/index.php?title=MediaWiki:UploadForm.js/dokumentace&oldid=256389“