Cesko.wiki Nápověda:Vytvoření modulu
Author
Albert FloresK 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. +more 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 , 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. +more 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), . Ta obsahuje všechny funkce modulu. +more Každá funkce poté vezme tzv. kontext, 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í 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. +more 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. +more 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. +more 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. +more 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 * 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. +more 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. +more 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. +more 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 „“ je dostupná i pro moduly. Používejte ji. +more 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. * ….