Gebruiker:Magere Hein/Kladblok/Handleiding sjablonen

Dit artikel geeft documentatie in het Nederlands over de manier waarop sjablonen werken. Dit artikel is een hulpmiddel; de gezaghebbende documentatie is in het Engels en te vinden op Meta. Deze handleiding is bedoeld om gebruikers en makers van sjablonen het leven gemakkelijker te maken.

Definities

• Een artikel is een willekeurige pagina op de Nederlandstalige Wikipedia.
• Een naamruimte is het geheel van artikels, waarvan de titel begint met dezelfde reeks tekens, gevolgd door een dubbele punt, samen een voorvoegsel. Zo vormen alle artikels die beginnen met het voorvoegsel "Help:" de naamruimte Help. Een uitzondering vormen de artikels, die geen voorvoegsel hebben, de hoofdartikels die de werkelijke inhoud van de encyclopedie vormen. Deze artikels worden samen de hoofdnaamruimte genoemd.
• De sjabloonnaamruimte is de naamruimte Sjabloon; de titels van artikelen erin beginnen met voorvoegsel "Sjabloon:". De sjabloonnaamruimte is lokaal voor elk Wikiproject. De naam ervan verschilt ook per project, zo heet de sjabloonnaamruimte op de Engelstalige Wikipedia Template.
• Een sjabloon is een artikel in de sjabloonnaamruimte.
• Een artikel maakt gebruik van en gebruikt een sjabloon door in de artikelbrontekst de titel van het sjabloon, zonder het voorvoegsel "Sjabloon:", tussen twee accoladen openen ("{{") en twee accoladen sluiten ("}}") te schrijven. In een artikel geeft bijvoorbeeld in de brontekst "{{Test}}" het gebruik van het sjabloon met de titel Sjabloon:Test aan.
• Een parameter is een extra gegeven voor het gebruik van een sjabloon in een artikel, geschreven in de artikelbroncode na de titel van het sjabloon en voorafgegaan door een sluisteken ("|"). Het sluisteken en de de tekst van de parameter maken geen deel uit van de titel van het sjabloon. Parameters kunnen de uitwerking van een sjabloon in een artikel beïnvloeden. Er is geen beperking aan het aantal parameters dat bij gebruik wordt meegegeven, noch aan het aantal parameters dat een sjabloon kan verwerken.
• Evaluatie is het proces in de serversoftware waarmee de tekst van een sjabloon wordt verwerkt aan de hand van eventueel meegegeven parameters. Het resultaat van de evaluatiefunctie is een reeks tekens, waarmee het sjaboongebruik in de brontekst vervangen wordt.

Doel

Een sjabloon is bedoeld om vaak gebruikte teksten op een eenvoudige manier in een artikel te gebruiken. Op zijn simpelst levert het gebruik van een sjabloon in een artikel altijd dezelfde tekst op. Zo geeft bijvoorbeeld Sjabloon:Leeswaarschuwing, gebruikt in een artikel als "{{Leeswaarschuwing}}" altijd als resultaat:

Een dergelijk sjabloon betekent bij de gebruik hetzelfde als de directive #include in de programmeertaal C of het PHP-statement include. Zoals het bovenstaande voorbeeld al toont, hoeft een sjabloon niet alleen tekst te bevatten, het kan ook opmaakinformatie en links bevatten. Dit soort sjablonen wordt in de Nederlandstalige Wikipedia veel gebruikt in de vorm van navigatiesjablonen.

Door parameters toe te voegen kunnen sjablonen flexibel worden gebruikt. Dit maakt zowel het gebruik als het maken van sjablonen ingewikkelder.

Werking

Wanneer in een artikel een sjabloon wordt gebruikt, dan wordt het artikel met de overeenkomstige naam (zo het bestaat) in de sjabloonnaamruimte geëvalueerd en vervangt bet resultaat alle tekst die uit die evaluatie volgt de tekst van het sjabloongebruik in de atikelbrontekst. Deze evalutie kan van 0 tot een zeer groot aantal tekens opleveren; er is geen maximum gedefinieerd. Een aantal van 0 betekent dat het gebruik geen effect heeft, het gebruikte sjabloon wordt vervangen door een lege string. Wanneer het gebruikte sjabloon niet bestaat, levert dat een rode tekst met de titel van het sjabloon op. Bijvoorbeeld, de brontekst "{{Naar ik mag hopen een onbestaand sjabloon}}" levert op: "{{Naar ik mag hopen een onbestaand sjabloon}}".

Sjablonen kunnen willekeurig veel tekens opleveren. Aangezien al die tekens door de webbrowser geladen moeten worden kan dat zeer lange pagina's opleveren. De maker of onderhouder van een sjabloon dient er voor te waken dat dat het gebruik van het sjabloon onwerkbaar kan maken.

In beginsel is het mogelijk dat een sjabloon een oneindig aantal tekens voortbrengt. Aangezien dat oneindig veel tijd vergt loopt die operatie nooit af. Ik heb het niet geprobeerd, maar de gevolgen ervan zijn op zijn minst een pagina die oneindig lang blijft laden in de browser. Niet doen, dus.

De evaluatie van een sjabloon geeft standaard de tekst van het sjabloon terug. Dit kan uitgebreid worden door het gebruik van parameters en van parserfuncties in het sjabloon.

Nesting

Een sjabloon is zelf een pagina en kan dus een sjabloon gebruiken. Dit is een veelgebruikte techniek om een aantal sjablonen een door hen gedeeld effect te vertonen. In de Nederlandstalige Wikipedia is een toepassing van nesting te vinden in de {{Infobox}}-sjablonen. Daarbij wordt gebruik gemaakt van een generiek sjabloon. Aangezien de aanleiding voor het schrijven van deze handleiding een poging was een nieuwe infobox te maken, worden voorbeelden van deze sjablonen in de verdere tekst gebruikt.

Er is geen limiet aan het aantal op deze manier geneste sjablonen, maar recursie is verboden. Wanneer een sjabloon zichzelf, direct of indirect, gebruikt wordt het gebruik op het tweede niveau door de evaluatiefunctie vervangen door een link met het HTML-foutcommentaar:

Parameters

Zoals al gezegd in paragraaf Definities kunnen parameters de uitwerking van een sjabloon in een artikel beïnvloeden. Het woord kunnen is hierbij met opzet gebruikt, want om die invloed te hebben moet in het sjabloon worden aangegeven dat het een of meer parameters heeft en hoe die gebruikt moeten worden. Wanneer in een artikel bij het gebruik van een sjabloon een of meer parameters worden meegegeven, waarvan het sjabloon geen weet heeft, dan worden die parameters genegeerd en hebben geen uitwerking. Het bovenstaande voorbeeld van Sjabloon:Leeswaarschuwing weet niets van parameters. Wanneer het gebruik ervan een parameter toevoegt, bijvooorbeeld "{{Leeswaarschuwing|De butler heeft het gedaan}}", dan levert dat als resultaat:

Kortom: identiek aan het gebruik zonder.

Een voorbeeld van nuttig gebruik van een parameter is het Sjabloon:Test. De inhoud van het sjabloon is:

Begin-{{{1}}}-Einde<noinclude>
[[Categorie:Wikipedia:Sjablonen beheerpagina|Test]]
</noinclude>

Door de evaluatiefunctie wordt alle tekst die begint met <noinclude> en eindigd met </noinclude> genegeerd. Het doel hiervan is dat zo het artikel tekst kan bevatten, die alleen voor mensenogen bedoeld is, in dit geval een categorie van het artikel. Ook uitleg over gebruik van het sjabloon kan zo worden toegevoegd.

Het voor het voorbeeld belangrijke gedeelte is dus: "Begin-{{{1}}}-Einde". Hierin definieert het gedeelte "{{{1}}}" de manier waamee het sjabloon de eerste parameter, indien aanwezig bij het gebruik, verwerkt. Wanneer er geen parameter wordt gebruikt, wordt de tekst "{{{1}}}" teruggegeven aan de evaluatiefuntie. Bijvoorbeeld: de artikelbrontekt "{{Test}}" geeft als resultaat: "Begin-{{{1}}}-Einde".

Wanneer er een of meer parameters door de artikelbrontekst gebruikt worden, vervangt de evaluatiefunctie de tekst in het sjabloon van "{{{" tot en met "}}}" met de tekst van de eerste parameter bij gebruik. De brontekst "{{Test|Hoera!}}", met als parameter "Hoera!" levert op: Begin-Hoera!-Einde. Alle parameters die gebruikt worden in de artikelbrontekst meer dan de eerste worden door de evaluatiefunctie genegeerd. De brontekst "{{Test|Hoera!|Jammer!}}", dus met twee parameters "Hoera!" en "Jammer!" levert op: "Begin-Hoera!-Einde".

Meervoudig gebruik

Een parameter kan meer dan eens worden gebruikt in een sjabloon. Het sjabloon

Begin-{{{1}}}-Midden-{{{1}}-Einde

zal bij gebruik in een pagina met brontekst "{{Test|Hoera!}}" als resultaat geven: "Begin-Hoera!-Midden-Hoera!-Einde"

Meer dan één parameter

Op eenzelfde manier kan een sjabloon meer dan één parameter gebruiken. Zo zal:

Begin-{{{1}}}-Midden-{{{2}}-Einde

bij gebruik in een pagina met brontekst "{{Test|Hoera!|Jammer!}}" als resultaat geven: "Begin-Hoera!-Midden-Jammer!-Einde"

Zie ook

• Wikipedia:Sjablonen: aanwijzijgen voor het gebruik van sjablonen
• Help:Gebruik van sjablonen: aanwijzingen voor het maken van sjablonen
• Help:Parserfuncties: een Nederlandstalig uitlegartikel met een selectie van parserfuncties