Nápověda:Vytvoření modulu

K vytvoření modulu je vhodné znát alespoň základy programování a tvorby šablon. Navíc je dobré znát i základy programování v jazyce Lua a seznámit se předem s dodatečnými funkcemi pro wiki. Na jednodušší úkoly pak je vhodné použít spíše šablony. Vždy je důležité také na dokumentační podstránce poskytnout podrobný návod k použití modulu včetně příkladů.

Název modulu

Kvůli případnému předávání a sdílení modulů mezi různými jazykovými verzemi Wikipedie upřednostněte cizojazyčný název před českým, např. místo Čas použijte raději Time. V odůvodněných případech však lze použít i český název, např. Sraz, zejména je-li modul orientován pouze na české prostředí. Vzhledem k tomu, že jeden modul poskytuje více funkcí, je potřeba název modulu volit vždy co nejuniverzálnější, např. místo Délka nebo Length volte raději String (angl. textový řetězec), kde délka bude jen jedna z jeho funkcí a modul tak bude připravený k rozšíření o další funkce pro úpravu textu.

Také platí některá běžná pravidla pro šablony, přednostně použijte jednotné číslo, např. místo Infoboxy nebo Infoboxes použijte raději Infobox. Název tématu co nejvíce zjednodušte a zkraťte, např. místo Společný modul všem citačním šablonám použijte raději Citace. Mezi technická omezení modulů patří nemožnost vytváření jejich přesměrování, proto název volte po důkladném uvážení.

Jednoduchý modul

Základní osnova

Základem jednoduchého modulu je takzvaná tabulka funkcí (f), angl. package (p). Ta obsahuje všechny funkce modulu. Každá funkce poté vezme tzv. kontext, angl. frame, obsahující různé užitečné informace (parametry volající šablony, parametry modulu, jméno aktuální stránky, jméno modulu, atd.), zpracuje jej podle sebe a vrátí výsledek, který se vypíše. Jednoduchý modul tak vypadá např. takto:

local f = {}

function f.prvniFunkce(kontext)
  return kontext.args[1]
end

return f

Funkce prvniFunkce v tomto případě vrátí (vypíše) první parametr. Volání {{#invoke:můjModul|prvniFunkce|text k vypsání}} tedy zobrazí „text k vypsání“.

Modul může takových funkcí pod sebou obsahovat nekonečně mnoho. Je však vždy nutné udržovat je mezi prvním a posledním řádkem, které se starají o správnou funkci modulu.

Názvy funkcí, proměnných a parametrů

Funkce, proměnné a parametry modulu by měly být vždy ve stejném jazyce jako název modulu. Funkce prvniFunkce by tedy byla vhodná pro český pojmenovaný modul. U anglicky pojmenovaného pak je třeba zvolit firstFunction. Funkce, proměnné a parametry modulu ve většině případů nemohou obsahovat diakritiku ani mezery, je tedy nutné je pojmenovávat tak, aby byly co nejvíce čitelné. Proto se místo mezer používá velké písmeno na začátku každého nového slova (viz camelCase). Logické názvy funkcí jako cituj rok a číslo stránky tak je nutné upravit např. na citeYearNumberPage.

Základní prvky modulů

Jak již bylo zmíněno, moduly se skládají z funkcí, proměnných a tabulek, ale i z mnoha dalších strukturovaných příkazů.

proměnná se ve většině případů značí local. Za rovná se pak následuje její hodnota, např. local text = "nějaký text".
tabulka se ve většině případů značí {}. V tabulce jsou hodnoty, ať už samotné seřazené podle přidání, nebo dvojice hodnot, např.:

local tabulka = {5, 7}
local tabulka2 = {pocet=5, velikost=7}

funkce většinou začíná function nazev(parametry) a končí end. Pokud se jedná o hlavní funkce, před názvem je ještě f.. Samotné jádro funkce je pak zakončeno řádkem obsahujícím return neco, kde neco je výsledek, který funkce vypíše, např:

function pridejA(text)
  return text .. 'A'
end

if funguje podobně jako pokročilé funkce při tvorbě šablon. Podobně jako u funkcí modulů if začíná if podmínka then a končí end. Místo podmínky se vloží dotaz, který končí buď true nebo false. Mezi tyto řádky se pak vloží kód, který se provede. Navíc lze dovnitř přidat i elseif podmínka then nebo else, např:

if x > 2 then
  return 'x větší dvěma'
elseif x < 1 then
  return 'x menší jedné'
else
  return 'x mezi 1 a 2'
end

for dokáže pro více hodnot provést stejnou věc. Podobně jako u if, for začíná for hodnoty k projití do a končí end. Místo hodnot k projití se vloží buď jejich seznam nebo tabulka. Mezi tyto řádky se pak vloží kód, který se pro každou hodnotu provede, např:

for text = 'první text', 'druhý text' do
  ...
end

for klic, hodnota in pairs(tabulka) do
  ...
end

Dokumentace modulů

Testování modulů

K přípravě modulu lze využít pískoviště Modul:Test, společně s dalšími pískovišti (Šablona:Test, Wikipedie:Pískoviště, ...), viz nápověda. Kromě toho může mít každý modul jako u šablon i vlastní pískoviště na své podstránce.

Navíc může mít každý modul i tzv. testovací podmodul na podstránce /testcases. Zde jsou umístěny testovací funkce využívající jeden z modulů ScribuntoUnit nebo UnitTests a vypisující výsledek testu při volání na svojí diskusní stránce.

Tipy a triky

Funkce „Náhled stránky s touto šablonou“ je dostupná i pro moduly. Používejte ji. V kombinaci s funkcí mw.log (či mw.logObject) lze modul ladit bez nutnosti ho ukládat s kódem určeným pouze pro ladění.
Modul lze přesměrovat vložením pouze tohoto kódu: return require 'Modul:Název nového modulu'. Nejde ale o standardní přesměrování.
Z technických důvodů nemohou moduly vkládat plnohodnotný wikitext (šablony, kouzelná slova, parserové funkce). Pokud je to nutné, rozhraní pro jeho tvorbu poskytuje kontext (frame object).
kontext zpřístupňuje nejen parametry předané do modulu, ale i do volající šablony (pouze jedna úroveň). Běžnou práci s argumenty usnadňuje Modul:Arguments.
…

Související články