Wikipedia:Sjabloonsandput en -toetsgevalle

in Wikipedia, die vrye ensiklopedie
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.
Software Development

Sjablone is ʼn 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[wysig bron]

Meeste beskermde sjablone behoort ʼn 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[wysig bron]

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[wysig bron]

  1. Veronderstel jou sjabloon word Sjabloon:X genoem. Skep ʼn 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.
  2. 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.
  3. Skep ʼn 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.
  4. Plaas die {{Toetsgevallekennisgewing}}-sjabloon boaan die bladsy indien die nie vooraf geplaas is nie, voeg ʼn paar toetsgevalle (sien hieronder) in en stoor die bladsy.
  5. 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; ʼn 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[wysig bron]

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

  1. 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".
  2. Speel rond met wysigings in die sandput. Indien jy bietjie kode het wat jy wil toets, stoor die bladsy.
  3. 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.
  4. Skrap die kasgeheue van die /toetsgevalle-blad om die resultate by te werk.
  5. 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[wysig bron]

Op die /toetsgevalle-blad behoort daar ʼn toetsgeval te wees vir elke onderskeie handeling van jou sjabloon. Byvoorbeeld, indien jou sjabloon ʼn 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 ʼn ander parameter, |datum= het, waar die gebruiker die datum kan verskaf, behoort daar ʼn 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 ʼn 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 ʼn kort sjabloonuitset wat op een reël sal pas kan dit handig wees om die toetsgevalle binne ʼn 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[wysig bron]

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

Basiese formaat[wysig bron]

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[wysig bron]

Dit is baie maal handig om vir sjablone met kort uitsette wat korrek belyn moet wees, van ʼn 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[wysig bron]

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:

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[wysig bron]

Sekere sjabloonkenmerke kan nie in /toetsgevalle-blaaie getoets word nie. Byvoorbeeld, ʼn sjabloon mag dalk net sekere teks lewer in die hoofnaamruimte, of dit kan verskillende resultate lewer wanneer in ʼn hoofblad gebruik word as wanneer dit in ʼn 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 ʼn nota aan die bokant van die /toetsgevalle-blad te los met ʼn uitleg van wat ook nodig is om getoets te word. Dit sal help om toekomstige bydraers hiervan bewus te maak.

Voorbeelde[wysig bron]

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[wysig bron]