Ajuda:Plantilles
| Nota: Quan modifiqueu aquesta pàgina, esteu acceptant que la vostra contribució es publiqui en el marc de CC0. Vegeu Pàgines d'ajuda de domini públic per a més informació. |
Si teniu textos estàndard que voldríeu incloure en diverses pàgines, la funció de plantilla de MediaWiki entra en joc. A diferència de les extensions i els fitxers de mitjans, no hi ha cap repositori central per a les plantilles. Les plantilles poden ser escrites de zero o, per estalviar duplicar el treball ja fet, exportades des d'un altre wiki (per exemple la Viquipèdia) i, a continuació, importades al wiki de destinació.
Utilització bàsica
Les plantilles són pàgines wiki estàndard amb un contingut dissenyat per a ser transclòs a l'interior d'altres pàgines.
Templates follow a convention that the name is prefixed with "Template:", assigning it to the template namespace; besides this, you can create them like any other wiki page.
Per transcloure una plantilla, feu servir claus dobles d'obertura i tancament {{nom de la plantilla}}.
L'ús més simple de plantilles és el següent: creeu una pàgina anomenada Template:Welcome que contingui:
Hola! Benvinguts al wiki.
Haureu creat la vostra primera plantilla! Si a continuació, inseriu el codi que segueix en una nova pàgina:
{{Welcome}}
Quan la nova pàgina es vegi el text "Hola! Benvinguts al wiki." apareixerà en lloc de {{Welcome}}. El contingut de la plantilla serà transclòs en l'altra pàgina, és a dir, que serà integrat a la pàgina.
A continuació, podeu inserir {{Welcome}} en qualsevol punt de qualsevol pàgina en la qual desitgeu donar la benvinguda a algú. Suposem que s'utilitza en 100 pàgines. Si a continuació, canvia el contingut de la plantilla per:
Ei! Benvingut/-da a aquest meravellós wiki.
i tornar a visitar alguna de les 100 pàgines en què es va utilitzar la plantilla, veurà el nou text en lloc de l'original. D'aquesta manera, s'ha canviat el contingut de 100 pàgines sense editar, ja que la plantilla esta transclosa en aquestes pàgines.
Aquest és el mecanisme bàsic. Hi ha diverses característiques addicionals de transclusió que enriqueixen aquest mecanisme i fer les plantilles molt útils.
Maneres d'invocar una plantilla
Les plantilles poden ser utilitzades en altres pàgines en les següents formes:
{{Nom}}— tal com s'ha descrit anteriorment, aquest text (comunament anomenat "crida de plantilla") se substituirà "dinàmicament" pel contingut de la pàgina anomenada Plantilla:Nom (un procés anomenat "transclusió") cada vegada que la pàgina amb la crida de la plantilla es carrega (és a dir, la visualitza un lector del wiki). Com que la crida de plantilla roman al codi font de les pàgines, qualsevol canvi posterior a Plantilla:Nom es veurà a la pàgina que conté la crida de plantilla. A més, la pàgina apareixerà entre les que enllacen ("Què hi enllaça") a la plantilla.{{subst:Nom}}— quan s'utilitza aquest tipus de crida de plantilla, se substituirà per una còpia estàtica del contingut de la Plantilla:Nom a partir del moment en què la pàgina que conté la crida de la plantilla és desada. És a dir, una còpia del contingut de Plantilla:Nom serà substituïda per la crida de plantilla. No es manté cap enllaç entre la pàgina i la plantilla, de manera que cadascuna es pot editar sense afectar una a l'altra. En efecte, hi ha poca diferència entre substituir el contingut d'aquesta manera i simplement escriure-la al codi font de la pàgina ("manualment"). Vegeu Ajuda:Substitució per a més informació.{{safesubst:Nom}}: es va introduir per permetre la substitució recursiva en els casos en què les plantilles contenen crides a altres plantilles o funcions d'analitzador. Vegeu Ajuda:Substitució per a més informació.{{msgnw:Nom}}- Aquesta mostra el contingut de la plantilla com a sintaxi wiki en brut (com ho fa<nowiki>) quan es visualitza la pàgina que la conté. Per exemple,{{msgnw:Template:Thankyou}}mostra:
<noinclude> <languages/> </noinclude> '''Un petit agraïment...''' per {{{reason|{{{1}}}}}}. Una abraçada, {{{signature|{{{2}}}}}} <noinclude> [[Category:Template examples{{#translation:}}|{{PAGENAME}}]] </noinclude>
De fet, una pàgina wiki ordinària també es pot utilitzar com a plantilla, simplement especificant l'espai de noms que on s'està, per la qual cosa:
{{Plantilla:NomDePàgina}}transclou la pàgina titulada Plantilla:NomDePàgina (equivalent a{{NomDePàgina}}){{Discussió:NomDePàgina}}transclou la pàgina titulada Discussió:NomDePàgina{{:NomDePàgina}}transclou la pàgina anomenada NomDePàgina (és a dir, a l'espai de noms principal){{subst::NomDePàgina}}substitueix el contingut de la pàgina anomenada NomDePàgina
Si l'espai de noms especificat no existeix, se suposa que el títol complet és una plantilla:
{{Foo:Bar}}transclou Template:Foo:Bar
Independentment de la sintaxi que s'utilitzi, el nom de la plantilla pot ser relatiu a la pàgina actual.
Per exemple, si es crida {{/bar}} a la pàgina foo, transclourà la pàgina foo/bar.
També es pot generar dinàmicament.
Per exemple, {{ {{foo}} }} crida Template:foo i interpreta el resultat com el nom d'una altra plantilla a cridar.
Paràmetres
Per enriquir el mecanisme de transclusió, MediaWiki permet paràmetres que es passen a una plantilla quan es transclou. Els paràmetres permeten que la plantilla tingui continguts diferents o diferents comportaments.
Suposeu que voleu inserir una petita nota d'agraïment a la pàgina de discussió d'altres usuaris, com ara:
Un petit agraïment...
per tot el vostre esforç.
Una abraçada, jo
La nota d'agraïment tindrà una raó (en aquest cas, "tot el vostre esforç") i una signatura ("jo"). El seu objectiu és que qualsevol usuari pugui donar les gràcies a altres usuaris, per qualsevol raó que sigui.
Per tal que la nota tingui un aspecte similar arreu on es faci servir, podeu definir una plantilla anomenada Template:Thankyou/ca, per exemple. Tot i que la nota hauria de tenir un aspecte semblant sempre que un usuari faci un agraïment a un altre usuari, el seu contingut específic (és a dir, el motiu i la signatura) serà diferent. Per aquest motiu, hauríeu de passar-los com a paràmetres. Si ignorem els elements restants per formatar el quadre i col·locar la imatge, el contingut bàsic de la plantilla serà aquest:
'''Un petit agraïment...'''
per {{{1}}}.
Una abraçada, {{{2}}}
Observeu l'ús de {{{1}}} i {{{2}}}. Aquesta és la manera d'identificar, dins de les plantilles, els paràmetres que es passaran en tant s'utilitza la plantilla. Tingueu en compte que, dins de la plantilla, cada paràmetre està envoltat per tres claus: {{{ }}}. Això és diferent de l'ús normal del nom de la plantilla.
Quan s'utilitza la plantilla d'una pàgina, s'omplen els valors dels paràmetres, separats pe caràcter de la barra vertical (|). MediaWiki permet que els paràmetres que es passen a la plantilla de tres maneres: anònimament, numerada, i amb nom; com veureu a continuació.
Paràmetres anònims
Per passar paràmetres sense nom, es posen els valors dels paràmetres de forma seqüencial:
{{Thankyou/ca|tot el vostre esforç|jo}}
En aquest cas, la plantilla {{Thankyou/ca}} rep els paràmetres {{{1}}}=tot el vostre esforç i {{{2}}}=jo, del que resulta:
Un petit agraïment...
per tot el vostre esforç.
Una abraçada, jo
L'ordre en que es passen els paràmetres anònimes és crucial per al seu comportament. Invertir l'ordre dels paràmetres, així:
{{Thankyou/ca|jo|tot el vostre esforç}}
donaria el següent resultat:
Un petit agraïment...
per jo.
Una abraçada, tot el vostre esforç
{{{1}}}, etc.) funciona "només" amb paràmetres sense nom. Els paràmetres identificats pel nom, tal com es mostra a continuació, no seran accessibles a la plantilla mitjançant números ordinals.
Paràmetres numerats
Per passar els paràmetres per número, cal identificar cada paràmetre a passar-li:
{{Thankyou/ca|2=jo|1=la vostra amistat}}
Aquesta vegada, la plantilla {{Thankyou/ca}} rep els paràmetres {{{1}}}=la vostra amistat i {{{2}}}=jo, tot i que s'han proporcionat en ordre invers, i produeix:
Un petit agraïment...
per la vostra amistat.
Una abraçada, jo
Exemples:
{{Thankyou/ca|1=afegint “=”|2=jo}}
produeix:
Un petit agraïment...
per afegint “=”.
Una abraçada, jo
Paràmetres amb nom
La tercera via per passar paràmetres és pel seu nom, en lloc de nombres. En aquest cas, el contingut de la plantilla es canviaria per:
'''Un petit agraïment...'''
per {{{reason}}}.
Una abraçada, {{{signature}}}
Dins de la plantilla, fem servir {{{reason}}} i {{{signature}}} per identificar cada paràmetre, en lloc d'un nombre. Per passar aquests paràmetres pel seu nom, cal identificar cada paràmetre en passar-l'hi:
{{Thankyou/ca|signature=jo|reason=ser qui sou}}
En aquest cas, la plantilla {{Thankyou/ca}} rep els paràmetres {{{reason}}}=ser qui sou i {{{signature}}}=jo del que resulta:
Un petit agraïment...
per ser qui sou.
Una abraçada, jo
Els paràmetres amb nom distingeixen entre majúscules i minúscules, de manera que:
{{Thankyou/ca|signature=jo|Reason=sent qui ets|reason=distingeix entre majúscules i minúscules}}
produeix:
Un petit agraïment...
per distingeix entre majúscules i minúscules.
Una abraçada, jo
L'avantatge d'utilitzar paràmetres amb nom a la vostra plantilla, a més de ser flexible en l'ordre que es poden passar els paràmetres, és que fa que el codi de la plantilla sigui molt més fàcil d'entendre si hi ha molts paràmetres.
Els espais i els salts de línia s'eliminen automàticament del principi i del final dels noms i valors dels paràmetres amb nom, però es conserven en els paràmetres sense nom.
Barreja de paràmetres amb nom i sense nom
Si la plantilla ho admet, es poden utilitzar tots dos tipus de paràmetres en una sola crida. El contingut de la plantilla hauria de ser canviada a:
'''A little thank you...'''
for {{{reason|{{{1}}}}}}.
Hugs, {{{signature|{{{2}}}}}}
Llavors, {{Thankyou|admetre els dos tipus de paràmetres|signature=Jo}}, a dins la frase, mostra:
Un petit agraïment...
per admetre els dos tipus de paràmetres.
Una abraçada, Jo
Aneu amb compte en fer això, perquè pot donar lloc a resultats contradictoris, ja que el recompte de paràmetres sense nom es basa només en els paràmetres sense nom, no en els paràmetres amb nom.
Per exemple, amb {{Thankyou|Jo|reason=admetre els dos tipus de paràmetres}} en resulta:
Un petit agraïment...
per admetre els dos tipus de paràmetres.
Una abraçada, {{{2}}}
Per això, la plantilla està codificada per preferir el paràmetre amb nom al paràmetre sense nom, cosa que fa que es perdi el "Jo" i no es mostri cap signatura.
Això fa que es mostri un valor per defecte de {{{2}}}, tal com s'explica a continuació.
Per exemple, amb {{Thankyou|reason=admetre els dos tipus de paràmetres|Jo}} en resulta:
Un petit agraïment...
per admetre els dos tipus de paràmetres.
Una abraçada, {{{2}}}
Tot i que "Jo" és el segon paràmetre, és el primer paràmetre sense nom, per la qual cosa s'assigna a {{{1}}} i {{{2}}} es deixa sense assignar.
Valors per defecte
Si no proporcioneu a una plantilla que transcloeu uns paràmetres que espera, d'aquesta forma:
{{Thankyou/ca}}
en l'exemple dels paràmetres numerats anterior s'arriba al següent:
Un petit agraïment...
per {{{1}}}.
Una abraçada, {{{2}}}
En el moment que no es passen els arguments, la plantilla presenta els propis paràmetres, en lloc dels seus respectius valors. En aquests casos, pot ser útil definir uns valors predeterminats per als paràmetres, és a dir, uns valors que es faran servir si no se li passa el valor. Per exemple, si el contingut de la plantilla es canviés a:
'''Un petit agraïment...'''
for {{{reason|tot}}}.
Una abraçada, {{{signature|jo}}}
llavors {{{reason|tot}}} defineix que si no es proporciona cap argument per al paràmetre {{{reason}}}, llavors s'utilitzarà el valor per tot. De la mateixa manera, definint {{{signature|jo}}}, el paràmetre per defecte de {{{signature}}} serà jo. Ara, la transclusió de plantilla sense passar cap argument, es tradueix en el següent:
Un petit agraïment...
per tot.
Una abraçada, jo
{{foo|bar=}} o {{foo|bar=|baz=qux}}, la plantilla foo considera que el paràmetre bar és "". Això és diferent d'ometre el paràmetre per complet, cosa que el deixa sense definir i activa el mecanisme de valor predeterminat descrit anteriorment.{{#if:{{{1|}}}|{{{1|}}}|undefined}} retorna indefinit si el paràmetre està indefinit o és buit, mentre que {{{1|undefined}}} només ho fa si el paràmetre està indefinit.Sovint s'utilitzen valors per defecte per especificar noms alternatius de paràmetres.
Per exemple, si teniu {{{a|{{{b|}}} }}}, la plantilla buscarà primer un paràmetre anomenat "a".
Si no està assignat, utilitzarà el paràmetre anomenat "b".
Si no s'assigna ni "a" ni "b", no presentarà res.
Passant paràmetres a altres plantilles
Si la sintaxi dels paràmetres en brut es genera mitjançant la crida a la plantilla anterior i després es passa a una altra plantilla, no s'interpreta com un paràmetre. Això significa que {{Thankyou2}}, que només crida {{Thankyou/ca}} sense paràmetres, no funciona: {{thankyou2|everything|me}} → Un petit agraïment... per {{{1}}}. Una abraçada, {{{2}}}
En comptes d'això, cal passar explícitament el paràmetre a l'altra plantilla, és a dir, si {{Thankyou3}} conté
{{thankyou|{{{1}}}|{{{2}}}}}
llavors funciona correctament: {{thankyou3|everything|me}} → Un petit agraïment... per everything. Una abraçada, me
Aquest exemple no preserva el buit vs. la indefinició en els valors dels paràmetres – necessitaríeu una sintaxi més complicada si volguessiu fer això.
Paràmetres buits vs. no definits
El {{t2demo|| a }} (vegeu {{T2demo}} ), amb una barra vertical doble, estableix al primer paràmetre a una cadena buida en lloc de deixar-lo sense definir.
Produeix la sortida start--middle- a -end, de manera similar a com {{t2demo|1=|2= a }} produeix start--middle- a -end.
D'altra banda, establir explícitament el paràmetre "2" a "a" fa que el primer paràmetre sense nom es deixi sense definir:
{{t2demo|2= a }} produeix start-{{{1}}}-middle- a -end
Si el segon paràmetre no s'ha de retallar, ha de ser sense nom.
Per tant, podeu assignar una cadena buida al primer paràmetre, però no el podeu deixar sense definir.
Fer que buit i sense definir siguin equivalents
Les bones pràctiques de codificació de plantilles permeten passar una cadena buida a un paràmetre que funciona igual que quan no s'ha assignat cap valor. Això fa que les coses siguin més fàcils i coherents.
Per exemple, utilitzar p= pot mostrar que una plantilla té un paràmetre "p" que encara no té un valor.
Per fer equivalents una cadena buida i un valor indefinit, utilitzeu els mètodes següents:
- Utilitzeu exclusivament
{{{p|}}}en lloc de{{{p}}}oq, on "q" és un valor no buit. - Utilitzeu comprovacions condicionals com ara
{{#if:{{{p|}}}|..{{{p}}}..|..}}, per assegurar-vos que{{{p}}}només s'utilitza quan té un valor.
Si per alguna raó voleu tractar els paràmetres no definits de manera diferent dels paràmetres buits o qualsevol altre valor possible, podeu comparar el mateix paràmetre dues vegades amb valors per defecte diferents, és a dir, {{#ifeq:{{{foo|bar}}}|{{{foo|baz}}}|parameter is defined|parameter is undefined}}
Ús de signes iguals en paràmetres sense nom
Els paràmetres sense nom poden incloure signes igual, però això s'ha de fer indirectament. Aquí teniu alguns mètodes que utilitzen template:T1demo:
- Valor per defecte per a un paràmetre sense definir
Assignació d'un valor per defecte a un paràmetre sense definir:
{{T1demo|{{{1| a=b }}}}}
Això es renderitza com: start a=b end.
- Ús de la funció d'anàlisi
{{=}}
Utilitzeu una funció d'anàlisi que inclogui de manera segura un signe igual:
{{T1demo| a{{=}}b }}
Això es renderitza com a: start a=b end.
- Entitats HTML
Substituïu el signe igual per una entitat HTML per a la visualització:
{{T1demo| a=b }}
Això es renderitza com a: start a=b end.
Això es renderitza correctament sense afectar els altres paràmetres.
Gestionar les claus i els claudàtors no aparellats
N. del T.: L'expressió no aparellat és una traducció no satisfactòria de unmatched. En aquest context vol assenyalar que volem que aquests símbols no comportin una acció interpretada per l'analitzador wiki, i que siguin representats com qualsevol altre caràcter habitual.
Les claus ({{, }}) o els claudàtors ([[, ]]) no aparellats han d'estar dins d'etiquetes nowiki o utilitzar entitats HTML:
- La representació de les claus té dues opcions:
- Utilitzeu
<nowiki>{{</nowiki>o{per a{ - Utilitzeu
<nowiki>}}</nowiki>o}per a}.
- Utilitzeu
- Utilitzeu
[per[i]per].
A continuació es mostren alguns exemples:
- Claus no aparellades
{{T1demo| <nowiki>{{</nowiki>content<nowiki>}}</nowiki> }}
Això representa correctament les claus sense trencar la plantilla.
- Claudàtors no aparellats
{{T1demo| text [link] more text }}
Això representa correctament els claudàtors sense trencar la plantilla.
Això es renderitza com:
start text [link] more text end
Els claudàtors no emparellats que no es col·loquen a les etiquetes de nowiki impedeixen l'expansió de la plantilla o es prenen com a claudàtors de tancament per a la crida a la plantilla.
A continuació es mostren alguns exemples:
{{T1demo|abc]]def[[ghi}}
Això no s'expandirà correctament a causa dels claudàtors no coincidents.
L'ús correcte:
{{T1demo|abc<nowiki>]]</nowiki>def<nowiki>[[</nowiki>ghi}}
Això es renderitza com:
startabc]]def[[ghiend
Claus o claudàtors generats per plantilles
Una tècnica alternativa per passar arguments amb claus o claudàtors no aparellats és embolicar-los en una altra plantilla. En aquesta situació (que existeix amb {{((}} i {{))}}) en aquest wiki), les claus o claudàtors no emparellats es representaran literalment i no es descodificaran com una altra crida de la plantilla. Per exemple:
{{t1demo|{{((}}t1demo{{))}}}}
en resulta: start{{t1demo}}end
Quan se substitueix una plantilla, les inclusions de la plantilla s'analitzen una vegada quan es produeix la substitució (amb les mateixes advertències explicades anteriorment) i després una segona vegada quan es representa el text wiki resultant. Per exemple:
{{subst:((}}t1demo|foo}}
s'expandirà en desar a:
{{t1demo|foo}}
que es mostrarà com a:
startfooend
Si el wikitext generat mitjançant el primer "subst" inclou la sintaxi "subst:", no es processarà en el mateix desament, però sí que ho farà en el següent desament. Aquesta tècnica es pot utilitzar per implementar substitucions recursives que requereixen diversos desaments a avaluar.
Ús de barres verticals en valors de paràmetres
Un valor de paràmetre no pot contenir una barra vertical (|), perquè s'interpretaria com el final d'aquest paràmetre i l'inici del següent paràmetre.
Això es pot solucionar mitjançant la funció d'anàlisi {{!}} o l'entitat HTML &124;.
Els dos mètodes per fer-ho tenen un comportament lleugerament diferent, que pot ser rellevant en alguns casos extrems, com ara quan una plantilla produeix sintaxi de taula wiki.
Exemple:
{{T1demo|abc|def}}
produeix:
startabcend
El "def" no es mostra perquè es tracta com a part d'un altre paràmetre sense nom, que la plantilla no utilitza.
{{T1demo|abc{{!}}def}}
produeix:
startabc|defend
El "def" es mostra correctament.
{{T1demo|abc|def}}
produeix:
startabc|defend
El "def" es torna a mostrar correctament.
Formatar les crides de plantilla utilitzant paràmetres addicionals
Com que les plantilles ignoren els paràmetres que es passen però no gestionen específicament, es poden utilitzar com una manera d'afegir espais en blanc addicionals o contingut no utilitzat a la crida de plantilla.
Per exemple:
{{template name|foo|bar|baz|mumble|quux}}
és equivalent a, suposant que la plantilla no reconeix SPACEN com a nom de paràmetre:
{{template name|SPACE1=
|foo|SPACE2=
|bar|SPACE3=Random stuff
|baz|SPACE4=
|mumble|SPACE5=
quux
}}
També és possible utilitzar el mateix nom per a cada espaiador (sovint la cadena buida), però això omplirà Category:Pages using duplicate arguments in template calls, que molts wikis prefereixen mantenir buides per detectar casos d'error de l'usuari.
Això es pot utilitzar per fer que la plantilla es renderitzi de manera similar a la seva sortida, com ara mostrant cada fila de la posició ca:Plantilla:Diagrama d'escacs per si sola, per fer que el wikitext també sembli un tauler d'escacs.
Ús de paràmetres de seguiment
Pot ser prudent que una plantilla afegeixi un enllaç o una categoria a una pàgina si s'utilitza un paràmetre o una combinació de paràmetres determinats, per tal de determinar fàcilment quines pàgines utilitzen un paràmetre determinat i, per tant, quins serien els impactes de canviar aquest paràmetre a la plantilla.
Procés d'avaluació
En general, els paràmetres de la plantilla se substituïxen a la plantilla després de la tokenització, però tal com són. No s'avaluen fins que s'utilitzen.
Això té algunes conseqüències:
- Si teniu una
Template:Startque conté{{mytemplatei unaTemplate:Endque conté|foo=bar}}i poseu{{start}}{{end}}en una pàgina, mytemplate no es transclou, perquè els tokens com ara "|" no es poden afegir mitjançant una plantilla i mantenen el seu significat especial a les plantilles. Encara podeu utilitzar plantilles per controlar el nom d'un paràmetre o plantilla, però no podeu dividir una crida de plantilla entre diverses plantilles. - Eliminació de codi mort: Si feu una crida de plantilla com ara
{{foo|{{DISPLAYTITLE:Bar}} }}iTemplate:Foono conté {{{1}}}, aleshoresDISPLAYTITLEno s'utilitza, ja que només s'avalua quan cal i no hi ha cap paràmetre per substituir-lo, de manera que mai s'avalua. Això sol entrar en joc quan s'utilitza Extensió:ParserFunctions, i es pot notar especialment quan s'utilitza en combinació amb la paraula màgicaint:que varia segons l'idioma de l'usuari. Això no és perfecte, i en alguns casos, fins i tot si no s'utilitza el resultat d'expandir una plantilla (perquè forma part d'una condició d'instrucció if, per exemple), el procés d'avaluació encara pot tenir efectes secundaris. Per exemple, qualsevol enllaç produït o altres plantilles utilitzades encara s'afegiran a Special:WhatLinksHere fins i tot quan no es mostrin.
Els paràmetres de la plantilla es passen per valor, cosa que significa que una plantilla no pot modificar els seus arguments. Els paràmetres es tracten com a matriu associativa i els noms dels paràmetres s'avaluen abans dels valors dels paràmetres. Si es dona el mateix nom de paràmetre més d'una vegada (sigui amb nom o sense nom), només s'utilitza l'última instància i la pàgina s'afegeix a Category:Pages using duplicate arguments in template calls.
Les crides de plantilla que comencen amb la paraula màgica subst: o safesubst: s'avaluen en una primera passada separada que només passa en temps de desament, juntament amb ~~~~ i els enllaços que utilitzen el truc de la barra vertical.
Si no es poden avaluar durant la primera passada, les crides a subst: s'ignoren i safesubst: es tracten com si fossin plantilles normals.
Moltes, però no totes, les funcions d'anàlisi, les etiquetes d'anàlisi i les pàgines especials transcloses no s'inclouen directament com les plantilles, sinó que se substitueixen per un "marcador de barres". Això significa que no es poden manipular els resultats amb funcions d'anàlisi com ara padleft: o funcions similars de les extensions, ja que veuen el marcador de barres en lloc del resultat de la funció d'anàlisi.
Recursivitat en plantilles
Incloure una plantilla dins d'ella mateixa no farà que MediaWiki entri en una recursivitat infinita.
MediaWiki aturarà la recursivitat amb el nom de la plantilla en negreta.
Per exemple, si el contingut de Template:Aaaa és a {{Aaaa}} z, es mostrarà com a «a a Template loop detected: Template:Aaaa z z».
Aquesta salvaguarda impedeix una expressió de plantilla potencialment útil on una plantilla autonormalitzi els seus propis arguments de crida.
En aquest exemple prohibit, template:d pot fer la crida com {{d|20200311}} o {{d|y=2020|m=3|d=11}}.
Si es crida de la primera manera, recorre a si mateixa amb la segona estructura d'arguments (obtinguda mitjançant funcions d'analitzador de cadenes), que després segueix una ruta de processament unificada.
{{#if:{{{1|}}}|{{d|y={{#sub:{{{1}}}|0|4}}|m={{#sub:{{{1}}}|4|2}}|d={{#sub:{{{1}}}|6|2}}}}|<!-- processing path with arguments y,m,d regardless of original call pattern -->}}
Si template:d es modifica per una recursió a template:d/2 i template:d/2 és una còpia manual idèntica de template:d, aquesta expressió funciona correctament, ja que la salvaguarda d'autorecursió funciona dinàmicament i no estàticament.
Una manera factible perquè el programari MediaWiki afluixi la regla d'autorecursió seria exigir que cada crida recursiva tingui un recompte d'arguments diferent de totes les crides actives anteriors, com a màxim una vegada recursivament amb el recompte d'arguments no decreixent. Això proporcionaria una forta garantia contra l'autorecursió infinita alhora que permetria expressions útils com el que es descriu aquí d'una manera flexible.
Si la ruta de processament és de baixa complexitat, una solució senzilla utilitzant només una plantilla és gestionar cada convenció de crida en una branca if/else separada, duplicant la lògica de la ruta de processament dins de cada cas. Si la ruta de processament és més complexa, cada cas d'estructura de crida pot delegar a una plantilla d'implementació amb una estructura de crida unificada que proporciona el comportament final de la plantilla.
Taules en paràmetres
Atès que el caràcter (|) i el signe (=) tenen significats diferents en les crides de plantilles i en les infotaules, per utilitzar la codificació wiki de taula en el valor d'un paràmetre de plantilla, generalment cal "escapar" d'aquests caràcters (és a dir, protegir-los de la interpretació com a codi wiki per part de la plantilla) utilitzant seqüències especials:
- la paraula màgica
{{!}}incorporada proporciona una versió "escapada" de|des de MediaWiki 1.24 - la paraula màgica
{{=}}incorporada proporciona una versió "escapada" de=des de MediaWiki 1.39
Abans de la introducció d'aquestes paraules màgiques, molts wikis utilitzaven plantilles per aconseguir les mateixes coses. En un wiki d'aquest tipus, les paraules màgiques tenen precedència sobre les plantilles amb el mateix nom.
Taula d'exemple
| A | B | C |
|---|---|---|
| A1 | B1 | C1 |
| A2 | B2 | C1 |
Codi de la taula:
{| class=wikitable
!A!!B!!C
|-
|A1||B1||C1
|-
|A2||B2||C1
|}
Codi de taula escapada:
{{{!}} class{{=}}wikitable
!A!!B!!C
{{!}}-
{{!}}A1{{!}}{{!}}B1{{!}}{{!}}C1
{{!}}-
{{!}}A2{{!}}{{!}}B2{{!}}{{!}}C2
{{!}}}
Tingueu en compte que la primera clau esquerre ({) s'interpreta com un caràcter literal de clau esquerre perquè va immediatament seguit de la paraula màgica {{!}}.
De la mateixa manera, l'última clau dreta (}) s'interpreta com un caràcter literal de clau dreta perquè va immediatament precedit de la mateixa paraula màgica.
Tanmateix, en alguns casos, aquests caràcters de claus causen problemes, de manera que alguns wikis també proporcionen plantilles per escapar aquests caràcters:
- la crida a la plantilla
{{(}}pot proporcionar una versió "escapada" de{ - la crida a la plantilla
{{)}}pot proporcionar una versió "escapada" de}
Alguns wikis van encara més enllà i proporcionen altres plantilles convenients com ara {{(!}} ({|), {{!)}} (|}), {{!!}} (||).
En un wiki d'aquest tipus, el codi es pot simplificar una mica a aquesta forma:
{{(!}} class{{=}}wikitable
!A!!B!!C
{{!}}-
{{!}}A1{{!!}}B1{{!!}}C1
{{!}}-
{{!}}A2{{!!}}B2{{!!}}C2
{{!)}}
Controlant la inclusió de la plantilla
Per defecte, el contingut d'una plantilla es mostra completament, tant quan es veu directament com quan s'inclou en una altra pàgina. La pàgina de la plantilla, quan es visualitza directament, apareix exactament com es renderitzaria la plantilla sense cap paràmetre. Si la plantilla requereix paràmetres per funcionar correctament, això provocarà una sintaxi del wikitext en brut o errors com a resultat de la seva manca. Per exemple:
- Si un paràmetre no té cap valor per defecte, es mostra com el text literal {{{1}}}, cosa que indica que la plantilla necessita un paràmetre.
- Si un paràmetre té un valor per defecte buit (s'escriu com a {{{1|}}}), no mostra res, cosa que aconsegueix l'efecte desitjat, però no dona claredat per a l'autodocumentació. L'ús d'un valor per defecte no buit com ara
{{{1|imatge}}}podria aclarir la funció d'un paràmetre, especialment per a plantilles que impliquen imatges. - Si es passa un paràmetre sense un valor per defecte a la funció d'anàlisi
#expr, es produeix un missatge d'error: "Error d'expressió: caràcter de puntuació no reconegut '{'." - Si una plantilla crea una taula, és útil que la pàgina de la plantilla mostri l'estructura de la taula en lloc del wikitext utilitzat per crear-la. Per fer això, la sintaxi de la taula no està inclosa en etiquetes, i cada element de la taula inclou les parts
<noinclude>...</noinclude>i <includeonly>...</includeonly>on calgui.
No obstant això, podeu controlar quines parts d'una plantilla es veuran i s'inclouran mitjançant les etiquetes <noinclude>, <includeonly> i <onlyinclude>.
Qualsevol cosa entre <noinclude> i </noinclude> es veurà només quan la pàgina de la plantilla s'està veient directament, però no quan està inclosa en una altra pàgina. Això és útil quan es vol incloure text o codi en una plantilla que no vol propagar-se a qualsevol de les pàgines en que s'inclogui, per exemple en:
- Enllaços a categories per tal de categoritzar la pròpia plantilla
- Enllaços interllengua a les plantilles similars en altres idiomes
- Text explicatiu sobre com utilitzar la plantilla És un patró comú en alguns wikis utilitzar una plantilla com ara {{Documentation}} per transcloure la documentació d'una subpàgina de la plantilla. Per exemple, Template:Void està documentada a Template:Void/doc.
De la mateixa manera, qualsevol cosa entre <includeonly> i </includeonly> es processarà i es mostra només quan s'està incloent a la pàgina, però no quan la pàgina de la plantilla s'està veient directament, i és útil en situacions com ara:
- La categorització de les pàgines que inclouen la plantilla. Nota: en canviar les categories aplicades per una plantilla d'aquesta manera, la categorització de les pàgines que inclouen aquesta plantilla no s'actualitza fins després d'una estona: això és gestionat per la cua de treballs. Per forçar-ne la re-categorització d'una pàgina en particular, obriu aquella pàgina per a l'edició i guardeu-la sense canvis.
- Assegurar-se que el codi de la plantilla no s'executa quan es veu la pàgina de plantilla per se. Normalment, això es deu al fet que espera paràmetres, i la seva execució sense paràmetres té un resultat no desitjat.
Tot el que estigui fora de les etiquetes <noinclude> i <includeonly> es processa i es mostra normalment; és a dir, tant quan la pàgina de la plantilla s'està veient directament com quan la plantilla està inclosa en una altra pàgina.
L'atenció és en el que és dins d'aquestes dues etiquetes.
En la transclusió es rebutja tot allò que és fora d'etiquetes <onlyinclude>.
Fins i tot s'hi rebutgen les seccions que estiguin etiquetades com a includeonly llevat que també estiguin etiquetades com a onlyinclude.
L'enfocament només se centra en el que hi ha dins d'aquesta etiqueta.
Per exemple, si una pàgina com Help:Templates/onlyinclude demo té el text wiki:
abc<onlyinclude>def</onlyinclude>ghi<includeonly>jkl</includeonly>
El resultat de transcloure'l és def.
Aquestes etiquetes també es poden imbricar.
Les tres etiquetes de transclusió parcials permeten totes les combinacions possibles del que es processa i es representa.
Els comentaris també hi juguen un paper.
Les etiquetes d'inclusió es respecten quan s'utilitza {{subst:templatename}}, però no es respecten quan s'utilitza {{msgnw:templatename}}, ja que això mostra el text wiki en brut sense cap processament.
Transclusió de seccions
Per transcloure diferents seccions d'una plantilla en pàgines diferents, podeu embolicar el contingut en etiquetes onlyinclude i utilitzar una instrucció if als paràmetres per seleccionar quina secció.
Considereu "Template:Example" amb aquest wikitext:
== Section 1 ==
{{#ifeq:{{{1|1}}}|1|
Content of section one.
}}
{{#ifeq:{{{1|2}}}|2|
== Section 2 ==
Content of section two.
}}
Això representarà ambdues seccions a la pàgina d'exemple i permetrà que altres pàgines transcloguin la primera secció amb {{example|1}} i la segona secció amb {{example|2}}.
Un altre enfocament és utilitzar la sintaxi de paràmetres literals:
{{{section1|
== Section 1 ==
Content of section one.
}}}
{{{section2|
== Section 2 ==
Content of section two.
}}}
Transcloure la primera secció amb {{example|section2=}} i la segona secció amb {{example|section1=}}.
Si no s'utilitza cap paràmetre, es mostraran ambdues seccions.
Un tercer enfocament és utilitzar Labeled Section Transclusion.
Organització de les plantilles
Per tal de que les plantilles siguin eficaces, els usuaris necessiten poder-le trobar, i saber com usar-les.
Per trobar-les, els usuaris poden:
- Clicar
Pàgines especials>Totes les pàgines - En la llista de
Espai de noms:, escollir Template i clicarVés-hi.
Per donar una informació d'ús, inclourem un exemple com aquest en la pàgina de la plantilla:
<noinclude>
== Ús ==
Benvinguda als usuaris:
{{Thankyou|raó=la vostra raó|signatura=la vostra signatura}}
</noinclude>
Llavors, un editor pot simplement copiar i enganxar l'exemple per utilitzar-ho en la plantilla.
Mentre editeu una pàgina, hi ha disponible una llista de totes les plantilles utilitzades al formulari d'edició, en una secció plegable titulada Pages incloses en aquesta pàgina: (també anomenada Pages inclòs en aquesta previsualització: o Pages inclòses en aquesta pàgina: segons el context).
Aquesta llista proporciona un enllaç convenient a la pàgina de la plantilla, així com informació sobre el seu estat de protecció.
Les plantilles redirigides es mostren en cursiva, amb l'objectiu de redirecció afegit com un element de llista separat.
Enllaçar amb una plantilla
Es pot enllaçar una pàgina de plantilla com qualsevol altra pàgina wiki. Per exemple, l'enllaç Template:Navbar es genera utilitzant el codi wiki [[Template:Navbar]].
En molts wikis, Template:Tl es pot utilitzar per proporcionar un enllaç a una plantilla formatada de manera que mostri el codi wiki de "claus dobles" necessari per transcloure la plantilla sense fer realment la transclusió.
Per exemple, el codi {{tl|Navbar}} es pot utilitzar per crear l'enllaç {{Navbar}}.
Aquesta construcció s'utilitza habitualment quan es fa referència a plantilles en la documentació de les plantilles, a les pàgines d'ajuda i a les pàgines de discussió.
El mateix efecte es pot aconseguir utilitzant {{[[Template:Navbar|Navbar]]}}, però l'enfocament {{Tl}} implica molta menys escriptura.
En qualsevol wiki, la plantilla Tl, si existeix, pot o no representar el text en un element "codi" o com a tipus monoespaiat.
Si no (com en aquest wiki), una altra plantilla amb un nom similar pot fer-ho.
Vegeu, per exemple, la secció "Vegeu també" de la nostra documentació Template:Tl.
N. del T.: En la Viquipèdia en català existeix la ca:Plantilla:Tl.
Nom de les plantilles
El nom d'una plantilla distingeix entre majúscules i minúscules, excepte el primer caràcter.
Podeu crear redireccions per a noms amb majúscules/minúscules alternatives.
Per exemple, si una plantilla s'anomena "AdminAbbr", podeu crear una redirecció anomenada "Adminabbr".
D'aquesta manera, la plantilla es pot cridar amb {{AdminAbbr}} o {{adminabbr}}.
Si un editor prefereix una barreja de majúscules i minúscules per a més claredat, pot utilitzar funcions com lc o uc.
Per exemple, en lloc de {{CURRENTINTERNETTIME}}, podria utilitzar {{ {{uc:CurrentInternetTime}} }}
Com que els noms de les plantilles s'interpreten de la mateixa manera que els noms d'altres pàgines, els subratllats se substitueixen per espais i qualsevol text després d'una xifra (el que seria una àncora en un enllaç estàndard) s'ignora.
Un subratllat _ pot ser una alternativa a un espai en blanc.
Possibles usos de les plantilles
Les plantilles es poden utilitzar per a qualsevol situació en què es vulgui que dues o més pàgines continguin un contingut idèntic o similar que s'editi en un sol lloc de forma independent. Es poden utilitzar per:
- Proporcionar elements estructurats en moltes pàgines, com ara infotaules, plantilles de manteniment, caixes de navegació, etc.
- Efectuar càlculs utilitzats com a eina de programació en diverses pàgines, com ara w:Template:Sum.
- Construir pàgines compostes que mostrin el contingut de diverses pàgines existents juntes, com ara w:WP:Village pump (all), que inclou contingut de cada secció de la w:WP:Village pump. El contingut d'aquestes pàgines es pot mostrar individualment o junt, però l'historial de revisions, la llista de seguiment, etc. només recolliran els canvis a les pàgines transcloses i al wikitext sense format de la pàgina composta en si, no els canvis implícits a la pàgina composta.
- Compartir contingut entre unes quantes pàgines relacionades. Per exemple, la llista a Help:Preferences#Beta features està duplicada a Beta Features#Current Beta Features. Tot i que a MediaWiki.org, que està construït amb Extension:LabeledSectionTransclusion, es podria haver fet utilitzant una plantilla.
- Emmagatzemar contingut referenciat diverses vegades a la mateixa pàgina, de manera que només s'hagi d'escriure i calcular una vegada. Per exemple, w:Template:Cite Monumentenregister/URL és cridat dues vegades per w:Template:Cite Monumentenregister en dos llocs diferents del seu codi; i, així, en utilitzar una altra plantilla significa que només s'ha d'escriure una vegada les instruccions contingudes en la plantilla cridada per dos cops des de la plantilla base.
- Utilitzar plantilles com a element de programació per generar un bucle: si Template:A crida Template:B 10 vegades amb paràmetres diferents, això simula rudimentàriament un bucle for. Si Template:B crida Template:C 10 vegades, teniu un bucle imbricat de 100 crides de Template:C. Però tingueu en compte que és fàcil topar amb els límits de les plantilles quan s'utilitzen plantilles com a construccions de programació avançades, i utilitzar Scribunto és generalment més clar i fàcil de seguir.
Còpia d'un wiki a un altre
És possible, si la configuració del wiki ho permet, transcloure plantilles d'altres wikis. Aquesta configuració està desactivada als wikis de Wikimedia. En cas contrari, cal copiar manualment la plantilla i les seves dependències del wiki d'origen al wiki de destinació per utilitzar-la.
Les plantilles sovint requereixen CSS o altres plantilles, perquè els usuaris sovint tenen de problemes en copiar plantilles d'un wiki a un altre. Els passos següents haurien de funcionar per a la majoria de plantilles.
Codi de MediaWiki
Si teniu drets d'importació (específicament importupload) en la nova wiki:
- Aneu a Special:Export del wiki original, i descarregueu un fitxer .xml amb la història completa de totes les plantilles necessàries, com segueix:
- Entreu el nom de la plantilla en el quadre de text gran, per exemple, "Plantilla:Benvinguda". Pareu especial atenció a les majúscules i els caràcters especials — si el nom de la plantilla no és exactament igual, l'exportació es pot seguir produint, però el fitxer .xml no tindrà les dades esperades.
- Seleccioneu la casella
Inclou les plantilles. - Seleccioneu la casella
Inclou només la versió actual, sense l'historial complet. - Cliqueu
Exporta.
- Aneu a Special:Import en el nou wiki i carregueu el fitxer .xml.
Si no té els drets d'importació sobre el nou wiki:
- Aneu a la plantilla que voleu copiar del wiki original. Aneu a la pàgina d'edició, i copieu tot el wikitext.
- En el nou wiki, aneu a la pàgina amb el mateix nom que la plantilla que heu copiat. Premeu Crea/edita i enganxeu el wikitext que heu copiat. Al resum d'edició de cada plantilla, enllaça a la pàgina original per a l'atribució.
- De tornada al wiki original i en la finestra d'edició, per sota de la caixa d'edició, mireu la llista de
Pages incloses en aquesta pàgina:. Per a cada plantilla que es mostra, seguiu aquestes instruccions. També ho heu de fer per a cadascuna de les plantilles utilitzades per cadascuna d'aquelles plantilles, i així successivament.
Això copiarà tot el codi necessari i serà suficient per a la majoria de plantilles.
Tingueu en compte que només s'exporten els elements de la pàgina analitzats en renderitzar la pàgina, per tant, les subpàgines de documentació no s'exporten com a part d'aquest procés.
Si no funciona, comproveu si hi ha enllaços vermells a la llista Pages incloses en aquesta pàgina:, a sota del quadre d'edició.
Si n'hi ha, repetiu els passos anteriors per a aquests també i copieu el codi dels mòduls.
Després d'importar de l'altre wiki la plantilla i totes les plantilles amb què enllaça, modifiqueu-la per adaptar-la al vostre wiki. Per exemple, per canviar un logo o treure categories redundants o enllaços vermells.
Extensions
Una extensió d'ús freqüent en les plantilles és ParserFunctions. Visiteu la pàgina de Extensió:ParserFunctions i comproveu si alguna de les funcions enumerades no s'utilitzessin en les plantilles que hàgiu copiat. Si és així, heu d'instal·lar l'extensió ParserFunctions. Per instal·lar-la, heu de tenir accés d'administrador al servidor del MediaWiki.
Una altra dependència que es pot utilitzar en les plantilles, especialment en les de la Viquipèdia, és Lua. Que hi hagi {{#invoke: }} en el codi d'una plantilla és un bon senyal que es fa servir.
En cas que s'utilitzi, cal instal·lar es requereix l'extensió Scribunto i també caldrà accés d'administrador.
Mireu aquella pàgina per obtenir més instruccions sobre la instal·lació i l'ús de l'extensió.
CSS i codi JavaScript
A més de codi de MediaWiki, moltes plantilles fan ús de CSS i algunes es basen en JavaScript per funcionar plenament. Si les plantilles copiadss no es comporten com s'espera, això en pot ser la causa. Per copiar el CSS i el JavaScript al wiki haureu de tenir privilegis d'administrador, perquè haureu d'editar els missatges del sistema en l'espai de noms "MediaWiki:".
- Busqueu l'ús de classes CSS (text com
class="foobar") en el text de la plantilla. Si aquestes classes apareixen aMediaWiki:Common.cssoMediaWiki:Vector.cssal wiki original, copieu aquestes classes aMediaWiki:Common.cssal wiki nou i comproveu si la plantilla ara està bé. - Si la plantilla copiada encara no funciona com s'espera, comproveu si hi ha codi en
MediaWiki:Common.jsoMediaWiki:Vector.jsal wiki original. Si és així, podeu provar de copiar-ho aMediaWiki:Common.jsal nou wiki. Normalment, és una bona idea copiar codi només de fonts de confiança i navegar pel codi per identificar i seleccionar les parts rellevants. Podeu trobar comentaris que us poden servir com a pistes per identificar la funcionalitat de cada part.
Redirecció
Si una pàgina utilitza una redirecció com a plantilla, la redirecció es resol abans de processar la plantilla i s'utilitza la destinació en lloc d'això. Això no funcionarà si la destinació no existeix (una redirecció trencada) o és ella mateixa una redirecció (una redirecció doble).
Una pàgina que només inclou una altra pàgina com a plantilla pot semblar una redirecció, però hi ha diverses diferències entre elles:
- L'encapçalament del resultat mostra el títol de la pàgina d'on prové.
- No es mostra el missatge "Redirigit des de".
- Els botons com ara modifica, mostra, discussió, historial, "què hi enllaça" i "última modificació" apunten a la pàgina de referència. Per accedir a la pàgina de destinació, utilitzeu un enllaç d'edició de secció i navegueu des d'allà.
- A menys que s'utilitzin etiquetes includeonly i/o noinclude, la pàgina de referència comparteix les mateixes categories que la pàgina de destinació.
- Les "redireccions dobles" funcionen quan una o totes dues són aquest tipus de pseudoredirecció.
Funcions d'anàlisi
MediaWiki també admet funcions d'anàlisi, que funcionen de manera similar a les plantilles, però segueixen una sintaxi lleugerament diferent:
- Les funcions d'anàlisi utilitzen un ":" en lloc de l'inicial "|".
- Una pàgina d'edició no mostra les funcions d'anàlisi utilitzades en aquesta pàgina.
- No hi ha cap funció "Què hi enllaça" per a les funcions d'anàlisi per identificar les pàgines on s'utilitzen.
- Les plantilles de funcions d'anàlisi generalment no accepten paràmetres amb nom, de manera que els signes igual generalment no tenen cap significat especial. Per exemple:
{{ #if: not blank | x=abc }}givesx=abc
Vegeu també
= Ús de plantilles generals
- Manual:Expr parser function syntax
- Help:Substitution
- w:Help:Template
- Manual:Advanced templates – descriu les tècniques fins i tot més avançades, com les crides de plantilla dinàmica i noms de paràmetres variables
- Help:Multiple-instance templates – sobre l'ús de diverses instàncies de la mateixa plantilla en una pàgina.
- Manual:Newlines and spaces#Automatic newline
Construccions especials utilitzades a les plantilles
- Ajuda:Paraules màgiques – coses de luxe que es troben en algunes plantilles
- Ajuda:Extensió:ParserFunctions – més funcions de control sofisticades, com ara #if i #switch
- Ajuda:Funcions d'anàlisi en plantilles – ajuda sobre com utilitzar les funcions d'analitzador a les plantilles
- Ajuda:TemplateData
- Ajuda:Extensió:ParserFunctions
- Extensió:Scribunto
Altra informació rellevant
- Help:ExpandTemplates
- Help:Cerques externes – un exemple d'ús especial de plantilla
- Manual:Importing Wikipedia infoboxes tutorial
- Extension:PageTemplates
- Manual:Creating pages with preloaded text – Ús de plantilles com a text inicial d'una pàgina
- Ajuda:Transclusió – incrustar pàgines de espais de noms que no siguin
Plantilla: - Manual:Template limits
- Ajuda:Què hi enllaça
- Special:Mostlinkedtemplates – mostra les plantilles amb més usos
- Special:Unusedtemplates – mostra les plantilles sense ús (encara que puguin estar substituïdes)
- Manual:$wgEnableScaryTranscluding – ús de plantilles d'altres wikis
- w:Wikipedia:Template namespace
- w:WP:Anatomy of a template
- w:Wikipedia:Transclusion costs and benefits
- Manual:Parser.php
- Help:Extension:TemplateSandbox – per previsualitzar els canvis a una plantilla a mesura que es renderitza en altres llocs
- Manual:HTML templates
Enllaços externs
- Repositori de plantilles de Miraheze – plantilles MediaWiki destinades a ús general.