Wikipedia:Sjabloonsandput en -toetsgevalle

Hierdie bladsy is 'n Wikipedia-gebruiksgids wat prosesse of prosedures van sekere aspekte van Wikipedia se norme en standaarde uitlê. Hierdie blad is nie deel van Wikipedia se beleide en riglyne nie; waar inligting teenstrydig is met die inhoud van hierdie essay, neem daardie inligting asseblief in ag.

Kortpaaie:

Hierdie artikel of onderafdeling van die artikel is onder ontwikkeling.
As u wil bydra tot die ontwikkeling daarvan, spring gerus in, maar moet dit asseblief nie uitvee nie.

Sjablone is ŉ kragtige kenmerk van MediaWiki, maar foute kan maklik gemaak word, selfs deur gesoute gebruikers. Ingewikkelde sjablone moet dus van sandputte en toetsgevalle vergesel word om foute te help voorkom.

Sandput- en toetsgevallesubladbenaming

Meeste beskermde sjablone behoort ŉ sandput- en toetsgevallesubblad te hê. Die bladsye moet van die standaardbenaming gebruik maak. Sjablone met reeds bestaande dokumentasiesubblaaie sal outomaties skakels na die sandput- en toetsgevalleblaaie insluit (en verskaf "skep"-skakels indien hulle nie bestaan nie). Meeste sjablone kort nog behoorlike dokumentasie-, sandput- en toetsgevalleblaaie. Dit is tans onder ontwikkeling en enige bydraer kan hiermee help deur van die riglyne in hierdie artikel gebruik te maak.

Byvoorbeeld, hier is die subblaaie vir {{Kode}}:

Sjabloon	Skakel
Hoofsjabloon	Sjabloon:Kode
Sjabloon se sandput	Sjabloon:Kode/sandput
Sjabloon se toetsgevalleblad	Sjabloon:Kode/toetsgevalle

Vir watter soort sjablone

Dit word aanbeveel dat die toetsgevallepatroon toegepas word op sjablone wat gebruik maak van ontlederfunksies wat heel verskillendlykende uitsette genereer, soos die wat baie parameters inneem, of die met heelwat vertakkings van die #switch-operator.

By navigasiekaste waarvan die uitsette bykans eenders is in elke getranskludeerde bladsy, is die voordele nie noodwendig die tyd en moeite werd nie.

Enige sjabloon wat na duisende bladsye getranskludeer word, behoort uit die aard van die saak getoets te word voor die wysigings vasgelê word.

Hoe om /sandput- en /toetsgevalle-subblaaie te skep

Veronderstel jou sjabloon word Sjabloon:X genoem. Skep ŉ subblad met die naam Sjabloon:X/sandput. Indien die hoofsjabloon gebruik maak van die {{dokumentasie}}-sjabloon, kan jy dit doen via die skakel onder aan die dokumentasiekas. Jy kan dit ook in die soekkassie intik of direk in die URL-kassie van jou webblaaier. Let op dat "/sandput" alles in kleinletters is.
Kopieer al die inhoud vanaf die hoofsjabloon, insluitende <noinclude>-merkers en die {{Dokumentasie}}-sjabloon indien dit ook daar is. Stoor dit dan die nuwe bladsy. Jou wysigingsopsomming behoort iets te wees soos "skep nuwe sandputweergawe van Sjabloon:X".
- Neem kennis: Indien jy die "spieël"-skakel onderaan die dokumentasiekas gebruik, sal merkers soos <noinclude> en hul inhoud ontbreek. Dit sal beter wees om met die hand te kopieer en plak.
Skep ŉ ander subblad met die naam Sjabloon:X/toetsgevalle. Dit kan ook, soos met die sandput, geskep word deur op die skakel vir toetsgevalle te klik onderaan die dokumentasiekas, asook deur die naam in die soekkassie in te tik of in die URL-kassie van jou webblaaier. Let ook hier op dat "/toetsgevalle" net kleinletters het.
Plaas die {{Toetsgevallekennisgewing}}-sjabloon boaan die bladsy indien die nie vooraf geplaas is nie, voeg ŉ paar toetsgevalle (sien hieronder) in en stoor die bladsy.
Voeg jou eksperimentele kode in Sjabloon:X/sandput in. Stoor die bladsy om jou kode te toets, en gaan dan na die /toetsgevalle-blad. Dit kan meermale nodig wees om die /toetsgevalle-bladsy se kasgeheue te skrap sodat die bygewerkte resultate getoon kan word; ŉ skakel hiervoor is ingesluit by die {{Toetsgevallekennisgewing}}-sjabloon. Na die blad geskrap is, kan resultate van die hoofsjabloon vergelyk word met die resultate van die sandput, en indien alles reg vertoon kan die hoofsjabloon bygewerk word. Wees egter bedag op toetsgevalle wat ontbreek en kode wat slegs in sekere naamruimtes of bladsye getoets kan word.

Hoe om bestaande /sandput- en /toetsgevalle-blaaie by te werk

Om ŉ wysiging te maak in ŉ sjabloon wat reeds /sandput- en /toetsgevalle-subblaaie het, word ŉ soortgelyke proses as hierbo gevolg.

Die /sandput het nie noodwendig die nuutste weergawe van die sjabloonkode nie, so voor jy die wysiging aanbring moet dit eers met die hoofsjabloon gesinkroniseer word. Kopieer die volledige inhoud vanaf die hoofsjabloon na die /sandput-blad en stoor die bladsy. Jou wysigingsopsomming behoort te lees as "sinkroniseer met die hoofsjabloon", of net "sinkroniseer".
Speel rond met wysigings in die sandput. Indien jy bietjie kode het wat jy wil toets, stoor die bladsy.
As jy enige nuwe kenmerke bygevoeg het of parameters gewysig het, behoort jy nuwe toetsgevalle in die /toetsgevalle-subblad te plaas om getoets te word. Neem ook in ag dat die bestaande toetsgevalle nie noodwendig volledig is nie. Dit is in die haak om die toetsgevalle oor te skryf indien hulle nie in lyn is met wat jy probeer bereik nie. Neem egter bydraers in ag wat die toetsgevalle na jou mag gebruik.
Skrap die kasgeheue van die /toetsgevalle-blad om die resultate by te werk.
Maak seker dat die resultate van die toetsgevalle korrek is. Indien alles blyk goed te wees kan die kode van die sandput na die hoofsjabloon gekopieer word.

Voeg toetsgevalle by

Op die /toetsgevalle-blad behoort daar ŉ toetsgeval te wees vir elke onderskeie handeling van jou sjabloon. Byvoorbeeld, indien jou sjabloon ŉ banierboodskap genereer en die parameter |kursief=ja laat die teks in kursief vertoon, behoort jy een toetsgeval te plaas vir die normale boodskap en een vir die kursiefgedrukte boodskap. Indien die sjabloon ŉ ander parameter, |datum= het, waar die gebruiker die datum kan verskaf, behoort daar ŉ derde toetsgeval daarvoor wees. Jy moet poog om deeglik te wees en gevalle te verskaf vir al die maniere waarop gebruikers jou sjabloon kan gebruik; dit is in heelwat gevalle egter onprakties om toetsgevalle vir elke onderskeie parameterkombinasie te plaas, so kies die mees relevante toetsgevalle met sorg. Daar is ŉ hele aantal verskillende toetsgevalstyle wat jy kan gebruik. Watter een jy gebruik word bepaal deur die aard van die sjabloon waaraan jy werk. Byvoorbeeld, vir ŉ kort sjabloonuitset wat op een reël sal pas kan dit handig wees om die toetsgevalle binne ŉ wiki-tabel te plaas, en vir lang smal sjablone soos inligtingskaste is dit meestal beter om hulle langs mekaar te vertoon met behulp van {{sj|Toetsgevaltabel}.

Formatering met die hand

Formatering met die hand verskaf ŉ groot mate van buigbaarheid, maar sorg moet geneem word om sekere te maak dat al die sjabloon se parameters reg ingevoer word. ŉ Fout by een van die toetsgevalle is soms moeiliker om op te spoor as ŉ fout in die sjabloon self.

Basiese formaat

Hierdie formaat werk goed vir baniersjablone en langerige teks soos aanhalings. Neem kennis dat jy hierdie soort toets outomaties kan formateer met behulp van Sjabloon:Toetsgeval en ander soortgelyke sjablone.

== Beskrywende titel ==
 
* <code><nowiki>{{sjabloon|param1=waarde1|param2=waarde2}}</nowiki></code>
 
'''Hoof'''
 
{{sjabloon|param1=varde1|param2=waarde2}}
 
'''Sandput'''
 
{{sjabloon/sandput|param1=waarde1|param2=waarde2}}

Elke waarde van sjabloon, param1, waarde1 ens. Moet identies wees.

Vir sjablone wat van die "float" CSS-eienskap gebruik maak, moet jy die {{clear}}-sjabloon gebruik om te keer dat die resultate opeenhoop:

== Beskrywende titel ==
 
* <code><nowiki>{{sjabloon|param1=waarde1|param2=waarde2}}</nowiki></code>
 
'''Hoof'''
 
{{sjabloon|param1=waarde1|param2=waarde2}}
 
{{clear}}
 
'''Sandput'''
 
{{sjabloon/sandput|param1=waarde1|param2=waarde2}}
 
{{clear}}

Wiki-tabel

Dit is baie maal handig om vir sjablone met kort uitsette wat korrek belyn moet wees, van ŉ wiki-tabel gebruik te maak vir die formatering van toetsgevalle.

Skop die tabel as volg af:

{| class="wikitable"
|-
! Kode
! Hoof
! Sandput

Elke nuwe toetsgeval kan as volg bygevoeg word:

|-
| <code><nowiki>{{sjabloon|param1=waarde1|param2=waarde2}}</nowiki></code>
| {{sjabloon|param1=waarde1|param2=waarde2}}
| {{sjabloon/sandput|param1=waarde1|param2=waarde2}}

Sluit die tabel as volg af:

|}

Outomatiese formatering

Daar is verskeie sjablone wat jou help om toetsgevalle outomaties te formateer. Met hierdie sjablone word parameters en waardes net eenmaal ingevoer maar steeds getoets vir beide die hoof- en sandputsjablone. Dit voorkom probleme met foute in toetsgevalleparameters en maak dit makliker om toetsgevalleblaaie te onderhou. Hierdie sjablone sluit in:

Sjabloon:Toetsgeval, vir algemene toetsgevalle
Sjabloon:Toetsgevaltabel, vir lang smal sjablone soos inligtingskaste
Sjabloon:In-lyn toetsgeval, vir lang en smal sjablone soos inligtingskaste
Sjabloon:Toetsgeval-nowiki, vir sjablone met ingewikkelde oproepmetodes
Sjabloon:Opvoubare toetsgeval, om sjablone te laat opvou indien die hoof- en sandputsjablone dieselfde resultaat lewer

Neem kennis dat al hierdie sjablone opvoubare toetsgevalle kan lewer, maar Sjabloon:Opvoubare toetsgeval het die kenmerk outomaties ingestel. Gaan loer na die individuele sjabloonblaaie vir gedetailleerde dokumentasie.

Toetse wat nie in /toetsgevalle-blaaie gedoen kan word nie

Sekere sjabloonkenmerke kan nie in /toetsgevalle-blaaie getoets word nie. Byvoorbeeld, ŉ sjabloon mag dalk net sekere teks lewer in die hoofnaamruimte, of dit kan verskillende resultate lewer wanneer in ŉ hoofblad gebruik word as wanneer dit in ŉ subblad gebruik word. Vir die soort toetse kan jy gebruik maak van die "Wys voorskou van hierdie sjabloon"-funksie onderaan die wysigingskas in sjabloonblaaie. Om hierdie funksie uit te brei kan jy en:User:Jackmcbarn/advancedtemplatesandbox.js installeer, waarna dit in enige naamruimte beskikbaar sal wees, en jou ook toelaat om die titel van die sjabloon asook die voorskoublad te spesifiseer. Dit beteken dat jy die sandputsjabloon kan wysig, maar bladsye vooraf kan besigtig asof jy eintlik binne die hoofnaamruimte besig is met wysigings.

Indien jy aan enige toetse kan dink wat nie in die /toetsgevalle-blad uitgevoer kan word nie, kan dit van groot hulp wees om ŉ nota aan die bokant van die /toetsgevalle-blad te los met ŉ uitleg van wat ook nodig is om getoets te word. Dit sal help om toekomstige bydraers hiervan bewus te maak.

Voorbeelde

Basiese formaat: Sjabloon:Aanhaling, Sjabloon:Aanhaling/sandput en Sjabloon:Aaanhaling/toetsgevalle
Wiki-tabel: Sjabloon:Diff, Sjabloon:Diff/sandput en Sjabloon:Diff/toetsgevalle
Toetsgevalle-tabel: Sjabloon:Inligtingskas Nedersetting, Sjabloon:Inligtingskas Nedersetting/sandput en Sjabloon:Inligtingskas Nedersetting/toetsgevalle

Sien ook

Wikipedia:Hoërisiko-sjablone
Hulp:Sjabloon – algemene hulp met sjabloonkode
Wikipedia:Sjabloonbeperkings – tegniese beperkings op sjabloongebruik