Helpo:Ŝablonoj kaj moduloj

< Helpo:Superrigardo < Ŝablonoj kaj moduloj

Utilo

Kaj ŝablonoj kaj moduloj laboras por la uzantoj kaj kontribuantoj. Komence nur ŝablonoj disponeblis kaj enhavis ripete uzatan tekston. Iom post iom ili evoluis kaj fariĝis preskaŭ programoj. Ili povas ricevi parametrojn, prilabori ilin kaj decidi laŭ ili. Pro la malfacila sintakso kaj limigitaj ebloj de ŝablonoj oni poste enkondukis modulojn dum jaro 2013. Kvankam eblas alvoki modulojn rekte el kapvortaj paĝoj oni laŭkutime ne faras tiel. Moduloj servas al ŝablonoj, kaj ŝablonoj servas al paĝoj kaj uzantoj. Do kontribuantoj plej ofte tute ne devas zorgi pri moduloj, sed devas pri ŝablonoj. Alvoku la ŝablonon laŭ ĝia dokumentaĵo, kaj la laboro estas iel farita, ofte far subŝablonoj aŭ moduloj.

Komparo pri kapabloj

Tasko	Ŝablonoj	Moduloj	Rimarkoj
kunigi signoĉenojn	jes	jes	tio sufiĉas por certaj regulaj verboj en certaj lingvoj, ekzemple "spela" en la sveda (spela,spelar,spelade) spela
disŝiri signoĉenojn	ne	jes	tio necesas eĉ por esperantaj regulaj verboj (ludi,ludas,ludis) ludi
eltrovi kvanton da paĝoj en nomspaco	ne	jes	vidu paĝon Helpo:Nomspaco
eltrovi ĉu paĝo ekzistas	limigite	limigite	multekosta, maksimume totale 500 tiaspecaj demandoj en unu paĝo
eltrovi ĉu kategorio ekzistas kaj kvanton da paĝoj ene de ĝi	limigite	limigite	2 apartaj multekostaj demandoj, maksimume totale 500 tiaspecaj demandoj en unu paĝo
eltrovi ĉu dosiero ekzistas, eĉ ĉe "Commons"	limigite	limigite	multekosta, maksimume totale 500 tiaspecaj demandoj en unu paĝo
uzi variablojn	ne	jes	tre ĉargrena limo en ŝablonoj, se io sama estas bezonata 10-foje, tiam necesas aparte generi tion 10-foje
matematiko	limigite	jes	variabloj ne disponeblas en ŝablonoj
logiko kaj disbranĉigo	limigite	jes	variabloj ne disponeblas en ŝablonoj
cikloj	ne	jes
ellegi antaŭan subtitolon do en kiu sekcio la alvoko trovĝias	ne	ne	bedaŭrinde, tio estas la kaŭzo kial preskaŭ ĉiuj ŝablonoj bezonas lingvokodon kiel parametron
ellegi ĉirkaŭaĵon de la alvoko	ne	ne	bedaŭrinde, eĉ tio multe utilus

Ŝablonoj

Ŝablonoj enhavas vikitekston same kiel aliaj paĝoj. Ili troviĝu preferinde (vidu sube) en la nomspaco Ŝablono:. Ŝablonon eblas alvoki kaj transdoni parametrojn al ĝi. La speciala detalo de vikiteksto en ŝablonoj estas kodo por transpreni parametrojn (tri krampoj), kaj diversaj funkcioj por utiligi tiujn, ekzemple {{#switch:.

Teknikaj specialaĵoj de la nomspaco "Ŝablono:"

La nomspaco "Ŝablono:" fakte multe similas al "kutimaj" nomspacoj kiel "Helpo:". La sola teknika apartaĵo estas ke la sintakso por alvoki ŝablonon tio estas transkluzivigi enhavon per {{...}} defaŭltas al la nomspaco "Ŝablono:".

Nomoj de ŝablonoj

Vikivortaro permesas minusklan komencliteron kaj estas usklecdistinga, do ekzemple "gr" kaj "Gr" estus du apartaj ŝablonoj. Vidu ankaŭ helpopaĝon "Paĝonomoj kaj uskleco". Do nomoj de ŝablonoj estas afero de gusto kaj interkonsento. Duraj reguloj ne ekzistas, sed prezentiĝas jenaj rekomendoj:

subtitolaj ŝablonoj (2,3,4 kaj 5) komencu per majusklo
ŝablono "IFA" havas tutmajusklan nomon
ceteraj ŝablonoj havu tutminusklan nomon, se ĝi enhavas propran nomon tiam la ŝablonnomo ne komencu per ĝi, ekzemple "Ŝablono:superrigardo regnoj Eŭropo eo"
evitu signojn krom literoj, ciferoj, streko "-" kaj spaco (do krampojn, komon, ...) kvankam multaj estas teknike permesitaj

Bedaŭrinde multaj ĝisnunaj ŝablonoj havas malfeliĉajn nomojn.

Komunaj parametroj

Kelkaj parametroj estas komunaj por pluraj aŭ multaj ŝablonoj, tio signifas ke ili havas saman nomon kaj saman funkcion.

Anonimaj

se la ŝablono urĝe bezonas lingvokodon tiam ĝi estu la plej frua anonima parametro kaj deviga

ekzemploj: {{superrigardo ŝakpecoj univ}}, {{t}}, {{deveno3}}, {{elpropra}}

Bedaŭrinde multaj ĝisnunaj ŝablonoj ne sekvas la regulon, precipe la ŝablono "Vortospeco".

Nomitaj

ling= lingvokodo nedeviga, defaŭlte (se la parametro mankas) eo aŭ aŭtodivenado, se la lingvokodo estas ĉiam aŭ ofte uzata, tiam la ŝablono transprenu ĝin per deviga anonima parametro anstataŭe

ekzemploj: {{vikipedio}}, {{aŭdo}}

dial= dialekto, defaŭlte (se la parametro mankas) neniu aŭ aŭtodivenado

ekzemploj: {{IFA}}, {{aŭdo}}

nenk=1 por enliniaj ŝablonoj, ne montru enkondukan tekston aŭ bildon, utila se oni alvokas ŝablonon plurfoje en unu linio, defaŭlte la enkonduka teksto aŭ bildo aperas

ekzemploj: {{IFA}}, {{aŭdo}}, {{ref-PMEG}}

sa= alia skribo de sama vorto

ekzemploj: {{t}}, {{deveno3}}

ts= transskribo

ekzemploj: {{t}}, {{deveno3}}, {{elpropra}}

not= rimarko

ekzemploj: {{tf-en-sb}}, {{t}}, {{deveno3}}, {{elpropra}}

Kaŝitaj

* "pagenameoverridetestonly="  paĝonomo (sen nomspaca prefikso)
* "fullpanaoverridetestonly="  plena paĝonomo (kun nomspaca prefikso, ekzemple "Vikivortaro:Provujo")
* "namespacoverridetestonly="  nomspaco (signoĉeno kun komenca minusklo aŭ MAJUsklo kaj sen ":" dupunkto, ekzemple "modulo" aŭ "Modulo", ARKAIKIGITA)
* "nsnumberoverridetestonly="  nomspaco (dekuma nombro, ekzemple "102")
* "protpageoverridetestonly="  protekta statuso ("0" aŭ "1", ĉio alia estas ignorata, transpasas ellegon de protekta nivelo, malofte uzata)
* "preeviewoverridetestonly="  antaŭrigarda flago ("0" aŭ "1", ĉio alia estas ignorata)
* "substituoverridetestonly="  substitucia flago ("0" aŭ "1", ĉio alia estas ignorata)
* "linkdqidoverridetestonly="  ligata Q-umo en vikidatumejo
* "tocforceoverridetestonly="  montro de enhavtabelo de kategorio ("on" aŭ "off", ĉio alia estas ignorata, transpasas ellegon de kvanto da objektoj en kategorio, malofte uzata)
* "trackingcategorieshiglow="  ebla valoro "true"
* "detxt="                     ebla valoro "true", videbligas plenan vikitekston (precipe alimaniere nevideblajn kategorienmetojn aŭ magiajn vortojn) por sencimigo
* "detrc="                     ebla valoro "true", videbligas algoritmajn paŝojn, enhavon de variabloj aŭ simile por sencimigo
* "caller="                    (nur moduloj) "true", ĉio alia estas ignorata
* "nocat="                     malpermeso de enkategoriigo, eblaj valoroj "true" aŭ "false", ĉio alia estas ignorata (ARKAIKIGITA favore al "pate")

Tiuj "kaŝitaj" parametroj estas konvencio en ĉi tiu vikio. Ili estas gravaj por evoluigado kaj testado de ŝablonoj kaj moduloj, kaj ilian dokumentaĵon, sed oni neniam uzu ilin dum "ordinara" alvoko de ŝablono el kapvorta aŭ aldona paĝo.

Moduloj

Moduloj ne enhavas vikitekston sed programkodon en lingvo LUA. Ili troviĝu nepre en la nomspaco "Modulo:". Modulon eblas alvoki kaj transdoni parametrojn al ĝi. Moduloj disponeblas ekde jaro 2013 kaj ili estas multe pli "saĝaj" ol ŝablonoj. Modulojn oni alvokas per la sintaksa funkcio {{#invoke:...|...|...}}.

Teknikaj specialaĵoj de la nomspaco "Modulo:"

La nomspaco "Modulo:" estas multe speciala. Moduloj povas havi subpaĝojn (apartigitajn per /) same kiel ceteraj paĝoj, sed la specialaĵo estas ke subpaĝoj de moduloj povas enhavi aŭ programkodon en lingvo LUA aŭ vikitekston de la dokumentaĵo. Alidirektoj ne ekzistas, movoj eblas sed neniam postlasas alidirektilon, ĉiuj aŭtokonfirmitaj (te plejmultaj registriĝintaj) uzantoj rajtas movi modulojn (se ili ne estas protektitaj). Kategoriigado (eĉ forigpropono) ne eblas per la modulo mem (ĉar ĝi ne ehhavas vikitekston), sed eblas per ĝia dokumentaĵa subpaĝo.

Skripteraroj

Cimoj en moduloj povas kaŭzi fuŝan rezulton, aŭ ruĝan plendadon sur kapvortaj paĝoj (ofte sed ne ĉiam videblan), kaj almeton de la paĝo al diagnoza Kategorio:Paĝoj kun skripteraroj (69 paĝoj).

Moduligo de ŝablonoj

Ŝablonojn eblas dividi en 3 grupoj laŭ ilia uzo de moduloj:

Klasikaj ŝablonoj entute ne uzas modulojn. Ĉi tio estis la sola eblo antaŭ jaro 2013 kiam moduloj ne ekzistis. La stilo daŭre estas utila por simplaj ŝablonoj, ekzemploj troveblas interalie en Kategorio:Ŝablonaro rimarka -eo- (4 paĝoj), kaj alia estas {{vortaro-titolo}}.
Transiraj aŭ miksaj ŝablonoj faras mem parton de la laboro kaj ankaŭ uzas modulojn. Unu ekzemplo estas {{protektomoŝa}}.
Tute moduligitaj ŝablonoj konsistas el nenio krom alvoko de modulo kiu efektivigas la tutan laboron. Unu ekzemplo estas {{ligilo-639-3-wp-sil}}.

Transkluzivigo, substituo kaj ceteraj uzmanieroj

Ŝablonojn kaj modulojn eblas uzi je pluraj manieroj.

La plej kutima estas transkluzivigo. La kodo de la koncerna ŝablono aŭ modulo estas denove prilaborata ĉiam kiam la paĝo estas ĝisdatigita. Ŝanĝo aŭ rompo de la ŝablono aŭ modulo tuj afekcias aŭ rompas ĉiujn paĝojn kiuj uzas ĝin kvankam en praktiko povas aperi malfruo ĝis ke la ŝanĝo aŭ rompo videblas. Se ŝablono aŭ modulo estas transkluzivigita, tiam oni ne ŝanĝu ĝin je maniero kiu negative afekcias iun el la "uzantoj". Se oni tamen devas fari tion, tiam nepras tuj ŝanĝi ĉiujn paĝojn kiuj uzas la ŝablonon aŭ modulon.

Alia maniero estas substituo. Substitui eblas ŝablonojn (atentu ke tio ne estas rekursiva), modulojn (nur plene kaj rekursive), kaj certajn parsilajn funkciojn kiel {{#if: kaj {{PAGENAME}}.

Limoj

Por protekti la servilojn prezentiĝas multaj teknikaj limoj. Ilin apenaŭ eblas atinigi per "simpla" vikiteksto, sed ŝablonoj estas iomete pli "danĝeraj" kaj moduloj eĉ pli. Ekzemple estas permesitaj maksimume 500 multekostaj funkcialvokoj sur unu paĝo, 10 sekundoj da tempo por ĉiuj moduloj sur unu paĝo, kaj ekzistas diversaj limoj pri memoro kaj komplekseco. La vortaristo ne zorgu pri ili sed la kodumisto zorgu.

Diagnozaj listoj kaj iloj rilataj al ŝablonoj kaj moduloj

Specialaĵo:Plej ligitaj ŝablonoj (listo inkluzivigas modulojn)
Specialaĵo:Neuzataj ŝablonoj (listo NE inkluzivigas modulojn, unuopaj okazoj de ŝablonoj aperantaj ĉi tie pravigeblas en certaj situacioj)

Kategorio:Paĝoj kun pluroblaj argumentoj en ŝablonvokoj (0 paĝoj) (estu malplena)
Kategorio:Paĝoj kun tro da multekostaj sintaksaj funkcio-vokoj (0 paĝoj) (estu malplena)

templatecount.toolforge.org/index.php?lang=eo&namespace=10&name=Ŝ (kvanto da transkluzivigoj, nur vikipedio subtenata)
linkcount.toolforge.org/?project=eo.wiktionary.org&page=Ŝablono:eht (kvanto da transkluzivigoj, ĉiuj vikioj subtenataj)

Dokumentaĵo de ŝablonoj kaj moduloj

Teorie samaj du ebloj disponeblas por kaj ŝablonoj kaj moduloj:

enmetita ene aŭ apude de la kodo sur sama paĝo
aparte sur dokumentaĵa subpaĝo

La ĉefa limo de moduldokumentaĵo ene de la kodo estas manko de tekstaj stiloj kaj ligiloj. Memteston eĉ ne eblas efektivigi. La dokumentaĵa subpaĝo estas nur konvencio ĉe ŝablonoj (havigita per speciala ŝablono {{doku}}), sed funkcio de la vikia softvaro ĉe moduloj.

Prezentiĝas argumentoj por kaj kontraŭ la du ebloj ĉe ŝablonoj:

Por sama paĝo:

pli simpla kaj komprenebla solvo
plifaciligas samtempan ĝisdatigon de la dokumentaĵo kiam oni redaktas ŝablonon
plifortigas la aspirindan devon havi koheran kaj sufiĉan dokumentaĵon ĉiam kaj ekde kreo de ŝablono

Kontraŭ sama paĝo:

kutimaj uzantoj ne povas kontribui al dokumentaĵo de altnivele protektitaj ŝablonoj
ĉe multe uzataj ŝablonoj, redakto de la dokumentaĵo kaŭzas nenecesan laboron por la servilo (laŭraporte, kaj la servilo, denove laŭraporte, ne kapablas detekti ke nur dokumentaĵo (inter <noinclude> kaj </noinclude>) estas ŝanĝita, kvankam tio teorie eblus)

Por subpaĝo:

[NE PLU VALIDAS] intervikiaj robotoj povas fari sian bontenan laboron sen nenecesaj ŝanĝoj de la ŝablono mem, eĉ se la ŝablono estas protektita (intervikiaj ligiloj ne plu estas uzataj, la ligadon prizorgas entute apartigita "wikidata" komuna vikia datumdeponejo)
[PLEJPARTE NE PLU VALIDAS] apartigo de komplika ŝablono de komplika dokumentaĵo plifaciligas redaktadon de ambaŭ (iam komplikaj ŝablonoj estas plejparte moduligitaj, do preskaŭ malplenaj, vidu supre, la apartigo jam okazis je alia maniero)
kutimaj uzantoj povas kontribui al dokumentaĵo de altnivele protektitaj ŝablonoj
ĉe multe uzataj ŝablonoj evitas nenecesan laboron por la servilo post redaktoj de la dokumentaĵo

Kontraŭ subpaĝo:

pli komplika solvo
estas dubinde ĉu indas permesi al kutimaj uzantoj redakti la dokumentaĵon de altnivele protektitaj ŝablonoj (kohera kaj sufiĉa dokumentaĵo necesas ekde kreo, la kreinto ne eksportu la respondecon al aliaj)
risko ke malpli sperta uzanto redaktas la dokumentaĵon erare supozante ke tio ŝangas la ŝablonon (tio ripete okazis ĉe kelkaj vikioj, plej ofte pri informkestaj ŝablonoj ofte uzataj ĉe vikipedio sed ne ĉe vikivortaro)
risko ke iu fiuzas la dokumentaĵan subpaĝon kiel dezirlisto por la protektita ŝablono, kaj fine la dokumentaĵo fariĝas nekohera kaj neutila
risko ke oni amase aldonas kodon {{doku}} al ŝablonoj erare supozante ke tio estas utila redakto kaj iu alia kreos la necesan enhavon (tio antaŭe ripete okazis ĉe ĉi tiu vikio)

La pli ofte uzata stilo ĉe plejmultaj vikioj estas aparta subpaĝo, sed tio estas heredaĵa kutimo enkondukita antaŭ pli ol 15 jaroj kiam la argumentoj por fari tiel estis ege pli multaj kaj duraj.

Ĉe moduloj la subpaĝo daŭre estas pli malpli rekte necesa por la supre menciitaj gravaj limoj de enmetita dokumentaĵo.

Memtesto

La dokumentaĵo priskribu la funkcion de la ŝablono aŭ modulo kaj montru kion ĝi rezultigas. Ebloj por atingi tion estas pluraj:

enhavi pli malpli kopion de la ŝablono en la dokumentaĵo
konstrui la ŝablonon tiel ke ĝi montras iomete utilan enhavon eĉ se rekte montrata anstataŭ vokata
memtesto per alvoko de la ŝablono el la dokumentaĵo, eĉ sur sama paĝo, eĉ plurfoje

La plej suba strategio do memtesto estas forte preferinda. Avantaĝoj:

la dokumentaĵo tiel aŭtomate restos almenaŭ parte kohera (post ŝanĝo de teksto en la ŝablono ne eblas forgesi efektivigi saman sanĝon en la dokumentaĵo)
la rezulto estas bona kaj utila, ne okazas rompitaĵoj kiel aktiva participo: {{{1}}}inta | {{{1}}}into aŭ gerundo: Angla Verboing
eblas testi kaj certigi ke la ŝablono bone funkcias post kreo, kaj daŭre funkcias post ĉiu ŝanĝo (senriska minimuma ŝanĝo kiu kaŭzas gravan rompon estas famaĉa sperto en la mondo de programado, do jes, oni atentu)