Juhend:Mall

Vikipeedia nimeruumid
Põhinimeruumid		Arutelunimeruumid
0	Artiklid	Arutelu	1
2	Kasutaja	Kasutaja arutelu	3
4	Vikipeedia	Vikipeedia arutelu	5
6	Fail	Faili arutelu	7
8	MediaWiki	MediaWiki arutelu	9
10	Mall	Malli arutelu	11
12	Juhend	Juhendi arutelu	13
14	Kategooria	Kategooria arutelu	15
100	Portaal	Portaali arutelu	101
102	Mustand	Mustandi arutelu	103
828	Moodul	Mooduli arutelu	829
2300	Tööriist	Tööriista arutelu	2301
2302	Tööriista määratlus	Tööriista määratluse arutelu	2303
2600	Teema
Virtuaalsed nimeruumid
-1	Eri
-2	Meedia

Mall on Vikipeedia lehekülg, mida teistesse Vikipeedia lehekülgedesse liidetakse. Mallid sisaldavad enamasti korduvat materjali, mida on vaja vähemal või suuremal arvul teistel lehekülgedel kuvada. Malle kasutatakse standardsõnastusega teadete, hoiatuste või märguannete loomiseks, ühetaolise kujundusega info- ja navigeerimiskastide jaoks, või muudel eesmärkidel.

Kõige sagedamini kasutatavat teisele leheküljele liitmise meetodit nimetatakse transklusiooniks (inglise keeles transclusion). Transklusiooni puhul on liitva lehekülje tekstis viide mallile kujul {{Malli nimi}}. Teiseks meetodiks on asendamine. Selle meetodi puhul pannakse malli töötluse tulemus malli kasutava lehekülje vikiteksti sisse vaid ühel korral, lehekülje esimese salvestamise ajal.

Üldine kirjeldus

Enamik malle asub mallide nimeruumis, mis teisisõnu tähendab seda, et mallilehekülje nimi on kujul "Mall:XXXX". Samas on lehekülgi võimalik transklueerida ja asendada mistahes nimeruumist. Seetõttu võivad mõned mallid asuda teistes nimeruumides, näiteks kasutaja nimeruumis (leheküljed nimekujuga "Kasutaja:XXXX"). Igal mallileheküljel on sellega seotud arutelulehekülg.

Mallid võivad sisaldada ükskõik millist vikiteksti, sealhulgas teiste mallide väljakutsumisi. Mallid võimaldavad piiratud ulatusega programmeerimist. Mallides saab kasutada muutujaid (ehk parameetreid), arvutustehteid, hargnemist (parserifunktsioonide abil). Samuti saab mallides kasutada vikimuutujaid (niinimetatud "võlusõnu"), mille näideteks on kuupäev, kellaaeg ja lehekülje nimi. Mallid võivad sisaldada ka silte, mis määravad, milline osa malli vikitekstist malli transklueerimisel või asendamisel artiklisse liidetakse. See tähendab seda, et mallilehekülje väljanägemine ei pruugi olla sama, mis teisele leheküljele transklueeritud sisul; näiteks võib mallilehekülg sisaldada malli dokumentatsiooni, kategooriaid jms.

Kuidas malli kasutada. Malli transklueerimiseks artikli leheküljele kirjuta vikiteksti sisse {{malli nimi}} sellel kohal, kus mallitöötluse tulemus ilmuma peab. Esimene täht on tõstutundetu, see võib olla nii suur- kui väiketäht.

See kood eeldab, et mall asub malli nimeruumis, mistõttu eesliidet Mall: pole vaja lisada. Muudes nimeruumides asuvate mallide puhul tuleb lisada nimeruumi eesliide, näiteks Kasutaja:. Artiklinimeruumis asuva lehekülje transklueerimiseks pane lehe pealkirja ette koolon: {{:Lehekülje nimi}}.

Pane tähele. Kui püüad transklueerida malli, mida pole olemas, siis tekib punane link, täpselt samamoodi nagu muude mitteeksisteerivate lehekülgede linkimisel. Lingile vajutades avaneb lehekülg, millel saab selle nimega malli luua. Transklueerimine on võimalik vaid sama viki piires, ei ole võimalik transklueerida teistest vikidest või vikiprojektidest. Muukeelses vikis asuva malli kasutamiseks tuleb koduvikis luua malli koopia.

Malli kasutamise süntaks

Parameetrid

Eespool toodud transklueerimise süntaksit saab laiendada parameetrite lisamisega, mida kasutatakse malli väljundi juhtimiseks. See käib järgmise süntaksiga.

• {{malli nimi|parameeter|parameeter|...}}

Malli nimi on konkreetse malli nimi, iga parameeter võib sisaldada kas ainult väärtust (neid nimetatakse nimeta parameetriteks) või olla kujul nimi=väärtus (neid nimetatakse nimega parameetriteks). Nimeta parameetrid saavad automaatselt nimeks kasvavas järjekorras numbrid: 1, 2, 3 jne.

Nimega parameetri nime ja väärtuse eest ja lõpust korjatakse tühemikumärgid (tühiku-, tabuleerimis- ja reavahetusmärgid) automaatselt ära, keskelt aga mitte. Seega on kood {{ ... | minuparameeter = see on katse }} sama hea kui {{ ... |minuparameeter=see on katse}}. Öeldu ei kehti nimeta parameetri puhul, selles säilitatakse kõik tühemikumärgid.

See, milliseid parameetreid malli väljakutsumise koodis kasutada (kui üldse kasutada) ja mis nimega need on, sõltub malli koodist. Nimega parameetrite puhul pole nende järjekord tähtis. Üleliigseid või vale nimega parameetreid eiratakse; defineerimata jäänud parameetritele omistatakse vaikeväärtus. Kui sama parameetrit on kasutatud enam kui ühel korral, võetakse arvesse viimasena määratud väärtus.

Parameetri väärtuseks võib olla tühistring (püstkriips või võrdusmärk, millel järgneb kohe järgmine püstkriips või sulgevad loogelised sulud). See ei ole sama, mis parameetri täielik väljajätmine. Viimasel juhul jääb parameetri väärtus määramata. Samas on mallid sageli nii kirjutatud, et nad käituvad mõlemal juhul ühtemoodi.

Asendamine

Kui mall tuleb vikitekstis asendada, mitte transklueerida, siis pane esimese loogeliste sulgude paari järele modifikaator asenda:, näiteks {{asenda:Toimeta}}. Parameetrite lisamine käib samamoodi nagu transklueeritud mallis.

Kui liidetav lehekülg asub artiklinimeruumis, tuleb lühendile "asenda" panna järgi kaks koolonit. Näide: {{asenda::Tunnustamata riikide loend}}.

Muud üksikasjad

Malli nimele kehtivad täpselt samad reeglid, mis muudele leheküljenimedele: see on tõstutundlik, välja arvatud esimene täht, ja tühik nimes on eristamatu alakriipsust. Kui malli kutsumise koodis on trellimärk # (mida tavaliselt kasutatakse lehekülje alaosale linkimiseks), siis seda ja sellele järgnevaid märke eiratakse. Kui transklueeritavaks leheks on ümbersuunamislehekülg, siis transklueeritakse ümbersuunamislehe sihtmärk.

Tasub tähele panna, et täpselt sama kahekordsete looksulgude süntaksit kasutatakse paljude MediaWiki muutujate ja parserifunktsioonide juures. Näiteks kood {{NIMERUUM}} võib paista malli väljakutsumise koodina, kuid on tegelikult muutuja, mis tagastab käesoleva lehekülje nimeruumi eesliite.

Lihtnäiteid malli kasutamisest

Kui soovid näiteid katsetada, siis kasuta mõnd liivakastimalli: {{X1}}, {{X2}}, {{X3}}, {{X4}}, {{X5}}, ...

Väga lihtsa malli näiteks on Mall:Lambda, mis tekitab kreeka tähe lamdba (λ). Vajuta malli leheküljel nuppu "Muuda lähteteksti", et näha malli koodi (vikiteksti). Malli koodi aktiivseks osaks on λ. (Ülejäänud osa vikitekstist on suletud siltide <noinclude>...</noinclude> vahele, mis tähendab, et seda kuvatakse malli leheküljel, kuid ei kuvata leheküljel, kus malli välja kutsutakse.)

Selleks, et malli Mall:Lambda teisele leheküljele (näiteks Vikipeedia liivakastilehele) transklueerida, kirjuta kuskile lehekülje vikiteksti sisse {{lambda}} (sobib ka {{Lambda}}, esimene täht pole tõstutundlik) ja salvesta lehekülg. Kui nüüd lehekülge vaadata, siis kuvatakse seda nii, nagu oleks malli väljakutsumise kood asendatud mallitöötluse tulemusega. Teiste sõnadega nii, nagu sisaldakski vikitekst malli väljakutsumise kohas koodi λ. Leheküljel kuvatakse teksti "λ".

Kirjuta näiteks liivakastileheküljele lause "Kreeka tähestiku 11. täht on lambda ({{lambda}})" ja salvesta. Tulemusena näed leheküljel teksti "Kreeka tähestiku 11. täht on lambda (λ)". Malli kasutamiseks ei pea selle koodist aru saama. Tuleb vaid meelde jätta, mida mall teeb (ja seda on tavaliselt malli leheküljel kirjeldatud).

Teine võimalus sama malli kasutamiseks on asendamine. Kui kirjutad liivakastileheküljele "Kreeka tähestiku 11. täht on lambda ({{asenda:lambda}})" ja salvestad, on tulemuseks taas lause "Kreeka tähestiku 11. täht on lambda (λ)". Ent kui sa nüüd uuesti lehekülje lähteteksti vaatad, näed, et malli väljakutsumise kood asendati salvestamise hetkel mallitöötluse tulemusega. Side leheküljel oleva malli väljundi ja malli vahel on katkenud. Kui malli koodi peaks muudetama, ei mõjuta see enam leheküljel olevat väljundit (nagu juhtuks transklueerimise korral).

Parameetritega malli näiteid

Näide parameetritega mallist on mall {{suunamine}}. Kirjuta liivakasti kood {{suunamine|Kosmosesüstik}}. Tulemusena tekib järgmine tekst:

"Kosmosesüstik" suunab siia. Teiste tähenduste kohta vaata lehekülge Kosmosesüstik (täpsustus).

Ülal toodud näites kasutab mall {{suunamine}} ühte nimeta parameetrit. Sama malli saab kasutada ka teistsuguse arvu parameetritega, mille tulemuseks on veidi teistsugune väljund (selle kohta saad täpsemalt lugeda malli leheküljel). Näiteks kood {{suunamine|Mall (programmeerimine)||Mall}} tekitab järgmise tulemuse:

"Mall (programmeerimine)" suunab siia. Teiste tähenduste kohta vaata lehekülge Mall.

Pane tähele, et teisel juhul on malli väljakutsumise koodis kasutatud tühja parameetrit. Siin tähendavad kaks järjestikkust püstkriipsu seda, et teine mallile antud parameeter on tühistring.

Teistel mallidel, eriti keerulisematel, on nimega parameetrid (või segu nimeta ja nimega parameetritest). Lihtne näide on Mall:Tasuvusmaatriks, mida kasutatakse 2x2 ruudustiku tekitamiseks. Kirjuta liivakastilehele järgmine kood:

{{tasuvusmaatriks | UL = 5 | UR = 7 | DL = 2 | DR = 9 | nimi = Näide }}.

	vasak	parem
üleval	5	7
all	2	9
Näide

Paremal näed tulemusena tekkivat ruudustikku.

Malli leheküljel on teavet teiste võimaluste kohta. Pane tähele, et siin on malli kasutatud ilma selle kõiki võimalikke parameetreid määramata. Parameetrid, mida pole malli väljakutsumise koodis määratud, saavad väärtuseks vaikeväärtused.

Võrdusmärkide ümber ning parameetrite ees ja järel olevaid tühikuid on kasutatud vaid selguse eesmärgil. Need pole vajalikud ja malli koodi töötlemise ajal neid eiratakse (kuid nimeta parameetritega on teine lugu). Parameetrite nimed on tõstutundlikud. Ülaltoodud näites pole võimalik kasutada parameetri nime "DR" asemel nimesid "dr" või "Dr". Kui pöörduda malli poole parameetritega, mis pole mallis kasutusel, siis neid parameetreid eiratakse.

Mallide kasutamise nõuandeid ja lahendusi

Järgmistest punktidest võib mallide kasutamisel abi olla.

• Nimeta parameetris ei tohi olla võrdusmärki, sest stringi tõlgendataks kui nimega parameetrit. (See ei kehti juhul, kui võrdusmärk antakse mallile parameetris, mis tuleb läbi teise malli – seda juhtumit käsitleb parser (süntaksianalüsaator) teistmoodi.) Võrdusmärgi kasutamiseks malli nimeta parameetris (näiteks kui tegu on URL-i võtme ja vääruse paariga) asenda võrdusmärk erimalliga {{=}}. See mall tagastab võrdusmärgi, mida parser ei töötle kui nimega parameetri osa. Teine võimalus on nimeta parameetri asendamine nimega parameetriga. Esimene nimeta parameeter on sama, mis nimega parameeter "1" jne. Näiteks, kui soovid kutsuda välja malli {{korras}} ja kasutada selle esimese parameetrina teksti "a=b", kirjuta kas {{korras|a{{=}}b}} või {{korras|1=a=b}}.

• Täpselt samuti ei saa malli parameetris kasutada püstkriipsu (|), sest parser tõlgendab seda parameetrite eraldajana. (See ei kehti jällegi juhul, kui mall saab parameetris oleva püstkriipsu mõne muu sisseloetud üksuse osana, näiteks püstkriipsuga vikilingis.) Selle probleemi saab lahendada märgistuse {{!}} kasutamisega püstkriipsu asemel. Samuti võib püstkriipsu kohal kasutada HTML-märgistust |.

• Pea meeles, et erinevalt nimega parameetritest ei eemaldata nimeta parameetrite algusest ja lõpust automaatselt tühemikumärke (tühikud, tabuleerimised ja reavahemärgid). Tühemikumärgid (ja muud nähtamatud märgid mistahes parameetrites) võivad malli käitumist ootamatul viisil mõjutada. Mallide loojad saavad tühemikumärkide eemaldamiseks nimeta parameetritest kasutada malli {{trimmi}}.

• Mallide dokumentatsioonis ja arutelulehtedel on sageli vaja tekitada malli kutsumise kood, milles on link kõnealusele mallile, kuid mis malli ennast välja ei kutsu. Seda saab teha kergesti malliga {{tl}}. Näiteks kood "{{tl|Näide}}" annab tulemuseks "{{Näide}}". On samalaadne suuremate võimalustega mall {{tlx}}, mis toetab ka malli parameetrite näitamist.

• Kui malli muudetakse (redigeeritakse kas malli või mõnd selle alammalli), siis kajastub muudatus kõigil lehekülgedel, kus malli on kasutatud. Muutus ei pruugi aga kõigil lehekülgedel kohe nähtavaks saada, sest mõnda aega võidakse kuvada lehekülje puhvris olevat versiooni, mis põhineb malli eelmisel versioonil. Selleks, et sundida lehekülge kasutama malli uusimat versiooni, tuleb lehekülje puhver purgimise funktsiooniga puhastada. (Kirjuta brauseri aadressireal lehekülje lõppu ?action=purge (või kui märk ? on juba real olemas, siis &action=purge), ja vajuta sisestusklahvi.) See käib nii lehekülje kohta, kust malli välja kutsutakse, kui ka malli enda lehekülje kohta, kui seal on malli näidiskasutused.

• Kui vaatad lehekülje ajaloost lehekülje vanemaid versioone, siis pea meeles, et mallid liidetakse leheküljele sellisena nagu need praegu on. Ajal kui lehekülje vanem versioon oli kõige uuem versioon, võisid mallid olla teistsugused.

• Et vaadata, millistel lehtedel mall kasutusel on, kasuta malli leheküljel olles Tööriistade menüü all olevat linki "Lingid siia". (Loendis ei näidata lehekülgi, kuhu mall on asendusega pandud.)

• Selleks, et näha leheküljele liidetud malle, klõpsa vahekaardile "Muuda lähteteksti" ja vaata redigeerimisakna all olevat loendit. Loendis kuvatakse ka kõik alammalle, mida leheküljele otse liidetud mallid kasutavad. Sama loendit võib kuvada ka lehekülje alajaotuse ja lehekülje vanema versiooni kohta (ava vastava alajaotuse või lehekülje redigeerimisaken) või lehekülje veel salvestamata versiooni kohta (klõpsa nupule "Näita eelvaadet"). Lehekülje vanema versiooni puhul näidatakse alammallide puud, mis vastab mallide praegusele seisule.

• Artiklis oleval mallide arvul ja keerukusel on ülempiir.

• Kui soovid, et mall jätaks maha ajatempli, võid panna malli koodi <noinclude><nowiki></noinclude>~~~~~<noinclude></nowiki></noinclude>. Samas töötab see vaid malli kasutamisel asendamisega. Malli transklueerimisel on tulemuseks lihtsalt ~~~~~.

• Loetavuse parandamiseks tavatsevad programmeerijad koodi reavahetustega lahku lüüa ja taanetega varustada. Kahjuks MediaWiki tarkvara ei toeta seda ja kohtleb lisatud reavahetusi kui malli väljundi osa. Üks võimalus selles mööda minemiseks on lisada enne igat reavahetusmärki (rea lõppu) HTML-i kommentaari algus <!-- ja alustada uut rida HTML-i kommentaari lõpuga -->.

Mallide loomine ja muutmine

Mallide loomine ja muutmine käib teiste lehekülgedega enam-vähem ühtemoodi: vali malli nimi, liigu malli leheküljele ja klõpsa nupule "Muuda lähteteksti" või "Loo lähtetekst". Mallid pannakse tavaliselt malli nimeruumi, isiklikuks kasutamiseks või katsetamiseks mõeldud mallid võib luua ka kasutaja nimeruumis. Mall võib sisaldada kõike seda, mida iga tavaline artikkel või lehekülg, sealhulgas teisi malle (neid nimetatakse alammallideks või metamallideks). Enamasti on mallides kasutusel programmeerimisfunktsioonid – parameetrid, parserifunktsioonid ja "võlusõnad" – mis võimaldavad liidetud sisul olenevalt kontekstist varieeruda. Samuti on olemas spetsiaalsed sildid, mis määravad selle, milline osa mallist liidetakse artiklisse ja milline mitte.

Enne kui asud uut malli looma, tee kiire otsing olemasolevate mallide seas (näiteks võid sirvida kategooriat Kategooria:Mallid) ja vaata, kas ehk juba on olemas mõni mall, mis teeb, mida soovid. Või ehk leidub sarnane mall, mille koodi saad kopeerida ja uue malli aluseks võtta (või täiendada hoopis olemasoleva malli koodi ja lisada sinna uusi võimalusi). Otsi geneerilisi malle, mida saaks kasutada uue malli alammallina. Näiteks saab kergesti luua uusi navigeerimiskasti malle, kasutades alammallina malli Mall:Navmall (vaata näidet, kuidas Navmalli põhjale on loodud Mall:Muusika navigeerimismall).

Uuele mallile nime valimisel pole ühtegi kivisse raiutud reeglit, ent üldjuhul peaks malli nimi olema lühike, kuid malli otstarvet kirjeldav. Kui on juba olemas sarnaseid malle, siis järgi ühtset nimetamisstiili. Malle saab ümber nimetada, nii et olemasolevad kasutused katki ei lähe, kui ümbernimetamisel jätta maha ümbersuunamine uuele mallinimele.

Ole olemasoleva malli muutmisel äärmiselt ettevaatlik – muudatused võivad mõjutada paljusid artikleid ja sageli sellisel viisil, mida on raske ette näha. Just sel põhjusel on osad mallid redigeerimise eest kaitstud. Kõige ohutum viis malli muutmiseks on luua mallile alamlehekülg /liivakast (või kui mallil on liivakast juba olemas, siis kasutada seda), kopeerida malli lehelt kood liivakasti ja teha muudatused liivakastis. Seejärel kontrolli, kas malli muudetud versioon töötab: ava mõni artikkel, kus senine mall on kasutusel, kirjuta artiklis malli väljakutsumise koodis malli nime lõppu /liivakast ja vajuta nuppu "Näita eelvaadet". Niimoodi kasutatakse artiklis vana malli asemel liivakastis olevat malli. Suurema kindluse saavutamiseks tuleks malli uut koodi kontrollida mitmete erinevate artiklite peal. Kui kõik on korras, siis asenda malli leheküljel senine kood liivakastist kopeeritud koodiga ja kirjelda resümee väljal lühidalt muudatuste sisu.

Selleks, et teha ettepanek kasutamata, vananenud või sobimatu malli kustutamiseks, lisa malli leheküljele kõige ette kood <noinclude>{{kustutada mall}}</noinclude>.

Malli koodis parameetritega toimetamine

Parameetrite väärtused, mida mallile saab anda, on malli koodis esindatud kolmekordsete looksulgude vahel olevate sõnadega.

• Mallis olev kood {{{xxx}}} asendatakse parameetriga nimega xxx.
• Mallis olevad koodid {{{1}}}, {{{2}}} jne asendatakse esimese, teise jne nimeta parameetriga. Neid nimetatakse ka positsioonilisteks parameetriteks.

Kui parameetrile väärtust ei määrata, siis asendust ei toimu. Teisisõnu, kui parameetrile xxx ei omistata mingit väärtust, on malli koodis oleva avaldise {{{xxx}}} väärtuseks {{{xxx}}}. Selleks, et saavutada intuitsiooniga rohkem kooskõlas olev käitumine, saab kasutada parameetrite vaikeväärtusi. See käib püstkriipsusüntaksi abil: {{{1|vaikim}}} määrab esimese nimeta parameetri vaikeväärtuseks vaikim. Kõige sagedamini kasutatakse seda tühiväärtuse omistamiseks ({{{1|}}} või {{{xxx|}}}).

Ühe parameetri väärtust ei saa teise parameetri vaikeväärtusena kasutada, sel juhul omistatakse esimesele parameetrile väärtuseks lihtsalt teise parameetri nimi tekstina.

Kui malli väljakutsumise koodis on parameetrile antud tühiväärtus (näiteks nii:{{Mallinimi|}}), siis malli koodis parameetrile vaikeväärtust ei omistata. Kui selline käitumine ei sobi, on võimalik parameetri väärtuse olemasolu kontrollida parseri koodiga ja omistada selle puudumisel vaikeväärtus:{{#if:{{{1|}}}|{{{1}}}|vaikeväärtus}}. Sel juhul saab {{{1}}} väärtuseks "vaikeväärtus" isegi juhul, kui mallile antav parameeter on tühiväärtusega.

Kahe- ja kolmekordsete looksulgude paljukordse kasutamise tõttu malli koodis võivad avaldised malli koodis olla raskesti jälgitavad. Selguse mõttes võib kasutada tühikuid, kirjutades näiteks {{ {{{xxx}}} }} või {{{ {{xxx}} }}} ja mitte {{{{{xxx}}}}}. Samas tuleb jälgida, et tühikud ei satuks soovimatult malli väljundisse.

Erijuhtum: XML-tüüpi avasildi sees olevad parameetrid

Siltide <nowiki>...</nowiki> vahel asuvaid parameetreid ei interpreteerita. Samuti ei interpreteerita parameetreid, mis asuvad XML-stiilis avasildi sees. Seetõttu see kood malli sees ei tööta:

<ref name={{{param}}}> Smith, Adam (1776)... </ref>

Selle asemel kasuta parserifunktsiooni {{#tag:}}. See kood malli sees töötab:

{{#tag:ref | Marx, Karl (1848)... | name={{{param}}} }}

Süsteemimuutujad ja tingimusloogika

Selleks, et muuta malli käitumine sõltuvaks keskkonnast (näiteks käesolev aeg või nimeruum) või mallile antud parameetrite väärtustest, kasutavad mallid sageli "võlusõnadena" tuntud muutujaid ja parserifunktsioone. Mallid võivad teha ka aritmeetilisi arvutusi. Stringide täistöötlust mallide süntaks ei toeta (on loodud mõned sedasorti funktsionaalsust pakkuvad mallid, kuid need on vähetõhusad ja ebatäiuslikud). Samuti ei toeta mallide süntaks programmeerimises tuntud standardfunktsioone nagu silmused ja muutujale väärtuse omistamine.

Järgnevalt on ära toodud kõige sagedamini kasutatavad muutujad ja funktsioonid.

Näiteid põhilistest parserifunktsioonidest

Kirjeldus	Sisestatud tekst	Tulemus
Teksti muutmine suurtähtedeks	{{uc: On vast LUGU! }}	ON VAST LUGU!
Teksti muutmine väiketähtedeks	{{lc: On vast LUGU! }}	on vast lugu!
Nimeruumi nime saamine	{{NS: 1 }}	Arutelu
Vikipeedia URL-i tekitamine	{{fullurl: pagename }}	//et.wikipedia.org/wiki/Pagename

MediaWiki ParserFunctionsi laiendusel on rohkem programmeerimisega seotud parserifunktsioone.

Laienduse parserifunktsioonide näiteid

Kirjeldus	Sisestatud tekst	Tulemus
Kahe stringi (või parameetri) vahelise võrdsuse testimine	{{#ifeq: jah | jah | Hurraa! | Pagan! }}	Hurraa!
	{{#ifeq: jah | ei | Hurraa! | Pagan! }}	Pagan!
Testimine, kas string (või parameeter) sisaldab midagi (peale tühemikumärkide)	{{#if: {{{param|}}} | Hurraa! | Pagan! }}	Pagan!
Arvutuse tegemine [raadiusega 4 ringi pindala; täpsus kolm kohta pärast koma]	{{#expr: ( pi * 4 ^ 2 ) round 3 }}	50.265
Arvutuse tulemuse testimine [kas arv 1230 on paaris või paaritu?]	{{#ifexpr: 1.23E+3 mod 2 | Paaritu | Paaris }}	Paaris

Süsteemimuutujate näiteid

Kirjeldus	Sisestatud tekst	Tulemus (selle abilehe korral)
Leheküljenimed	{{PAGENAME}}	Mall
	{{FULLPAGENAME}}	Juhend:Mall
Käesoleva nimeruumi nimi	{{NAMESPACE}}	Juhend
Registreerunud kasutajate arv	{{NUMBEROFUSERS}}	199 231
Kindlasse kategoorias kuuluvate artiklite arv	{{PAGESINCATEGORY:UNESCO maailmapärand}}	105
Käesolev tarkvaraversioon	{{CURRENTVERSION}}	1.44.0-wmf.4 (a8dd895)
Viimase muudatuse ajatempel	{{REVISIONTIMESTAMP}}	20210407170540

Malli käitumise muutmiseks olenevalt kontekstist on eriti kasulikud ja sageli kasutatud muutujad PAGENAME ja NAMESPACE. Näiteks kui mall paneb lehekülje teatud kategooriasse, siis kontrollib see tihti muutujat NAMESPACE. Seda selleks, et kui mall pannakse kogemata peale valesse nimeruumi kuuluvale leheküljele, ei liigitaks ta seda lehekülge põhinimeruumi lehekülgedega samasse kategooriasse.

Malli sees asuvad mallid

Üks mall võib sisaldada teisi malle. Malli töötlemise ajal liidetakse alammallis olev vikitekst malli, mille sisse alammall on pandud. Nii kujutavad üksteise sees olevad mallid justkui matrjoška-nukke, mille töötlus algab kõige sügavamal asuvast mallist ja kulgeb kuni kõige välimise mallini, mis lõpptulemuse artiklisse väljastab.

Malli sees olevale mallile parameetri edastamiseks säti parameetri silt sisemise malli mõne parameetri väärtuseks.

• Näited:
  • Mall:A sisaldab koodi "väle pruun {{B|{{{3}}}}} hüppab üle...". Siin võetakse mallile A antud kolmas nimeta parameeter ja sätitakse see Mall:B esimeseks nimeta parameetriks. Seejärel tagastab Mall:A lause koos lause osaga, mille Mall:B mallile A tagastas.
  • Mall:A sisaldab koodi "väle pruun {{B|waldo={{{3}}}}} hüppab üle...". Sama, mis eelmisel juhul, kuid siin sätitakse mallile A antud kolmas nimeta parameeter malli B parameetri "waldo" väärtuseks.

Malli parameetreid endid saab valida tingimuslikult.

• Näited:
  • Mall:A sisaldab koodi "väle pruun {{B|{{{3}}}=rebane}} hüppab üle...". Siin edastab mall:A mallile B sõna "rebane" malli B parameetri väärtusena, kusjuures malli B parameetri nimi on malli A kolmanda nimeta parameetri väärtus.
  • {{#if: testistring | väärtus, kui testistring pole tühi | {{#if: testistring | väärtus, kui testistring pole tühi | väärtus, kui testistring on tühi (või sisaldab vaid tühemikumärke) }} }}

Mall võib iseennast välja kutsuda, kuid töötlemine katkestatakse ühe iteratsiooni järel, et lõputusse silmusesse mitte sattuda.

Kui malli sees asuv mall sisaldab liigseid looksulge – näiteks selliselt {{lb}}} –, siis käsitleb süntaksianalüsaator neid tavalise tekstina ja need ei mõjuta konteinermallis olevate looksulgude parsimist. Juhul, kui sees asuv mall on pandud asendusega, siis tehakse mallitöötluse ajal esmalt asendus, ja see mõjutab seda, kuidas looksulge konteinermallis parsitakse. Tavajuhtudel pole selle teadmisega suurt midagi peale hakata, kuid see võib mõnikord põhjustada ootamatuid vigu.

Sildid noinclude, includeonly ja onlyinclude

Kui malli lehekülg ühtegi neist siltidest ei sisalda, siis liidetakse terve malli vikitekst (kood) transklueerimise või asendamise teel leheküljega, kus asub malli väljakutsumise kood. Seda käitumist saab muuta, kui kasutada silte, mis ütlevad, milline osa või osad malli koodist on vaja leheküljega liita. Nii on võimalik ära hoida sellise teabe liitmist malli leheküljelt, mis on mõeldud vaid malli enda juures kuvamiseks, näiteks malli dokumentatsioon, kategooriad ja intervikilingid. Samuti saab siltidega määrata, milline osa malli koodist tuleb sihtleheküljega liita, kuid mida ei tohi töödelda malli enda leheküljel (näiteks kategooriad, mis on mõeldud artiklile ja mitte mallile külge panemiseks). Sildid on järgmised.

• <noinclude>...</noinclude>: noinclude-siltide vahel asuvat teksti ei liideta, kuid seda näidatakse malli leheküljel; kasutatakse tavaliselt mallide dokumentatsiooni puhul
• <onlyinclude>...</onlyinclude>: ainult nende siltide vahel olev tekst liidetakse leheküljega, kust malli välja kutsutakse, kõik ülejäänu jäetakse liitmata
• <includeonly>...</includeonly>: siltide vahel olev tekst liidetakse leheküljega, kust malli välja kutsutakse, kuid seda ei näidata malli enda leheküljel

Vikitekst	Mida näidatakse siin (päritolulehel, malli lehel)	Mida näidatakse seal (sihtlehel, artiklis)
<noinclude> tekst1 </noinclude> tekst2	tekst1 tekst2	tekst2
<onlyinclude> tekst1 </onlyinclude> tekst2	tekst1 tekst2	tekst1
<includeonly> tekst1 </includeonly> tekst2	tekst2	tekst1 tekst2

Üks kõige sagedasemaid probleeme, mis nende siltide kasutamisega seoses esineb, on (malli liitvas artiklis esinevad) üleliigsed tühikud või read. Tasub meeles pidada, et sildid kehtivad täpselt avava sildi esimesest nurksulust kuni sulgeva sildi viimase nurksuluni. Allolevates näidetes on rohelisega toodud variandid, kus liigseid tühikuid ei teki, ja punasega variandid, kus tekivad liigsed tühikud.

Näiteid

1. }}<includeonly>

   }}
   <includeonly>

2. }}<noinclude>

   }}
   <noinclude>

3. {{mall}}</includeonly><noinclude>

   {{mall}}</includeonly>
   <noinclude>

Neid silte saab üksteise sisse paigutada, kuid sellel on mõtet vaid sildi <onlyinclude> puhul, siltide <includeonly> ja <noinclude> üksteise sisse paigutamine ei anna midagi. Enne uue sildi avamist tuleb eelmine silt sulgeda. Niimoodi ei saa teha: <onlyinclude>abc<includeonly>def</onlyinclude>ghi</includeonly>.

Kasuta standardset XML-i reeglit: mis ennem avati, tuleb ka ennem sulgeda.

Probleemid ja nende lahendused

• Kui malli või parserifunktsiooni esimene artiklisse liidetav tähemärk on üks neljast järgmisest vikisüntaksi märgist –  : ; * # –, siis käsitletakse seda nii, nagu oleks see rea alguses (isegi kui malli silt seda pole). See võimaldab mitmesuguseid loendeid mallis, mis ei pruugi loendi jaoks tekstis sobivas paigas asuda. Selleks, et taolist käitumist ära hoida, kasuta enne märki silti <nowiki />, või kasuta HTML-i olemeid : &#59; * #. Vahel on nii, et HTML-i olemid töötavad ka seal, kus <nowiki /> ei tööta.

• Kasuta malli {{Trimmi}} nimeta parameetrite lõpust ja algusest tühemikumärkide ära koristamiseks, kui need võiks probleeme tekitada. Nimega parameetrite väärtused puhastatakse tühemikumärkidest automaatselt.

• Mallide silumisel (vigade leidmisel) on kasulikud järgmised tehnikad.
  • "Asenda:" kasutamine. Kui kasutada malli asendamisega, siis näed teinekord selgemalt, mis malli väljakutsumisel juhtub.
  • "msgnw:" kasutamine malli väljakutsumise alguses liidab malli lehekülje vikiteksti, mitte mallitöötluse tulemuse. See pole täiuslik: loendid renderdatakse, kommentaarid eemaldatakse ja ühekordsed reavahetusmärgid asendatakse tühikumärkidega (mis segab eriti liidetavatest vikitekstis kirjapandud tabelitest arusaamist).
  • Kasuta lehekülge Eri:Mallide hõrendamine, et näha, milline tekst malli väljakutsumise tulemusel tekib. See hõrendab ka kõik üksteise sees olevad mallid rekursiivselt.

• Serveriressursi kaitsmiseks ja lõputa silmuste ära hoidmiseks seab parser piirid üksteise sees asuvate mallide sügavustasemele ja mallide töötlemise tulemusel tekkiva lehekülje suurusele. See võib lehekülje töötlemise katkestada, kui sellel on kasutusel väga keerukad mallid, eriti kui neid on enam kui üks. Üldist koormust, mida lehekülje töötlemine serveris tekitab, saab vaadata lehekülje HTML-koodist HTML-i kommentaari seest, mis algab sõnadega "NewPP limit report".

• Ära kasuta malli koodi sees põhinimeruumis vahepealkirjade loomiseks mõeldud vikimärgistust =. See tekitab artiklisse lingid [ muuda ] | [ muuda lähteteksti ], millele vajutades avaneb redigeerimiseks malli lehekülg.
  • Malli leheküljele suunatud redigeerimislinke saab ära hoida, lisades koodi <includeonly>__NOEDITSECTION__</includeonly>.

Malli dokumentatsioon ja kategooriad

Malli sobivatesse kategooriatesse paigutamine ja sellele selge kasutusjuhendi lisamine teeb malli üles leidmise ja kasutamise teistele inimestele lihtsamaks.

Malli kasutajatele mõeldud dokumentatsioon koos malli kategooriatega paigutatakse harilikult kohe pärast malli koodi lõppu siltide <noinclude>...</noinclude> vahele. Selleks, et malli kasutavasse artiklisse ei tekiks üleliigseid tühikuid või reavahetusi, tuleb avasilt <noinclude> panna vahetult malli koodi järele.

Keerulisematel mallidel asub dokumentatsioon ühes kategooriatega enamasti malli alamlehel (nimega Mall:XXX/doc). Sellisel juhul pannakse malli leheküljele kohe pärast koodi lõppu (siltide <noinclude>...</noinclude> vahele) malli dokumentatsiooni abimall {{dokumentatsioon}}. Kui dokumentatsiooni alamlehte pole veel olemas, tekib malli lehele link selle loomiseks.

Osad mallid sisaldavad oma liidetavas vikitekstis kategooriaid. Nende eesmärk on panna lehekülg, mis malli välja kutsub, teatud kategooria(te)sse. Nii tehakse sageli "vajab tähelepanu"-tüüpi kategooriatega (artiklite sisuline kategoriseerimine mallidega ei ole soovitatav). Kui mall paneb seda välja kutsuvale artikli kindlasse kategooriasse, siis tuleb mallis kategooria ümber kasutada silte <includeonly>...</includeonly>, et mall ise samasse kategooriasse ei satuks. Malli loomise ja katsetamise ajal kasuta mallis mõnd testkategooriat või ära kasuta ühtegi kategooriat.

Alias ehk paralleelnimi

Aliast saab luua ümbersuunamise tegemisega. Näiteks Mall:Valmis on ümbersuunamine mallile Mall:Korras. Saad kirjutada nii {{korras|Valmis!}} kui ka {{valmis|Valmis!}} – mõlemad variandid töötavad.

Piirangud mallidele

"Hõrendusjärgse kaasa arvatava suuruse" piirang (inglise keeles "Post-expand include size" limit). Kui mallid renderdatakse või teisendatakse HTML-koodi, mida kasutaja veebibrauseris näidatakse, siis kasutavad need mälu. Seda nimetatakse "hõrendusjärgseks kaasa arvatavaks suuruseks" ja selle maksimaalne suurus on 2 048 000 baiti. Näidu väärtus pannakse lehe HTML-koodi kaasa ja seda saab brauseris veebilehe lähtekoodi režiimis vaadata. See näeb välja umbes selline:

<!--
NewPP limit report
Preprocessor node count: 2382/1000000
Post-expand include size: 63476/2048000 bytes
Template argument size: 9517/2048000 bytes
Expensive parser function count: 2/500
-->

Antud näites on näha, et mallide hõrendamisel tekkiv tekst kasutab ära 63 kilobaiti 2-megabaidisest saadaolevast mälust.

Kuvamise probleem. Kui leheküljele liidetakse liiga palju malle, võib hõrendamisjärgne kaasa arvatav suurus piiri ületada. Kui see juhtub, siis piiri ületavad malle ei töödelda ja nende asemel tekib leheküljele vikilink (näiteks selline: Mall:mallinimi). Viga ilmneb peamiselt liiga paljude viitamismallide ja/või lipumallide kasutamisel. Probleemi lahendamiseks kasuta asendamist, vähenda mallide arvu leheküljel või tee ühest suurest leheküljest mitu väiksemat.

Programmeerimiskeel Lua

Alates 2013. aasta veebruarist saab Vikipeedias kasutada programmeerimiskeelt Lua, see tuleb kaasa MediaWiki laiendusega Scribunto. Lua programmikood pannakse malli sisse süntaksiga "{{#invoke:}}". Lua lähtekood asub lehekülgedel, mida nimetatakse mooduliteks. Mooduleid ei kasutata artiklites tavaliselt otse, vaid läbi mallide. Näiteks moodulit Moodul:Bananas saad välja kutsuda nii: {{#invoke:Bananas|hello}}. See kirjutab teksti "Hello, world!".

Mallide otsing

Malli nime järgi otsimiseks saad kasutada otsingut mallide nimeruumist:

Vaata ka

• Juhend:Malli dokumentatsioon
• Vikipeedia:Mallid
• Kategooria:Mallid