Laboratoire Méthodes Formelles PmWikiCa/Inclusió d'altres pàgines

< PageDirectives? | Índex de la documentació | InterMapes >

autores (intermedi)

La directiva (:include:) possibilita la inserció (o "transclusió") dels continguts d'altres pàgines a la pàgina actual. Totes les directives de sota executen una inclusió directa. En concret, si no s'indica el contrari, s'assumeix que qualsevol enllaç del text inclòs enllaça amb pàgines del grup wiki actual.

Sintaxi

La sintaxi bàsica és

(:include NomPagina:)

usant NomPagina s'inclou la totalitat d'eixa pàgina (del mateix grup).

{Grup/NomPagina$:PTVar}

inclou una variable d'una pàgina, on Grup i NomPagina són opcionals

La sintaxi completa és

(:include NomComplet#ancora-inici#ancora-fi lines=123 self=0 basepage=abc variable=valor :)

inclou una pàgina d'acord amb els paràmetres proporcionats. Els paràmetres són opcionals.

Paràmetres

La directiva pot tenir múltiples paràmetres NomPagina amb o sense àncores, i múltiples variables.

Les pàgines especificades

(:include NomPagina:)

(:include Grup.NomPagina:)

(:include Pagina1 Pagina2 Grup1.Pagina3 Grup2.Pagina4:)

Totes tres inclouen a dintre de la pàgina actual el text complet de la pàgina especificada. S'hi poden especificar múltiples pàgines, però només s'inclourà la primera disponible.

Podeu usar la característica citada a dalt per a 'mostrar un missatge d'error en cas de que la inclusió falli. Creeu una pàgina, p.ex. Site.IncludeFailed que contingui el missatge d'error. Podeu usar qualsevol nom per a la pàgina. Després afegiu-la al final de la llista de pàgines de l'include:

 (:include Pagina1 Pagina2 Pagina3 Site.IncludeFailed:)

Una aproximació lleugerament més complicada s'explica a la pàgina de discussió.

Àncores

`(:include NomPagina#desde#fins:)`	inclou les línies entre les àncores `[[#desde]]` i `[[#fins]]` de la pàgina NomPagina
`(:include NomPagina#desde#:)`	inclou totes les línies des de l'àncora `[[#desde]]` fins al final de la pàgina
`(:include NomPagina##fins:)`	inclou totes les línies des de l'inici de la pàgina fins a l'àncora `[[#fins]]`
`(:include NomPagina#desde:)`	ho inclou tot entre `[[#desde]]` i la següent àncora
`(:include NomPagina#:)`	ho inclou tot des de l'inici de la pàgina fins a la primera àncora

Nota: no s'han de ficar espais entre "#desde" i "#fins".

Nota: el text que és en la mateixa línia que l'ancora [[#fins]]] NO s'inclourà al text, fins i tot si precedeix l'àncora. Per xemple:

[[#desde]]algunes paraules a la primera línia

algunes paraules més a l'última línia [[#fins]]

Quan s'incloguen les línies de dalt amb (:include NomPagina#desde:) es mostrarà el text de la primera línia però no el de l'última.

(:include Pagina1 Pagina2 #desde#fins:)

Inclou els continguts entre [[#desde]] i [[#fins]] de la primera pàgina disponible, bé sigui Pagina1 o Pagina2.

Nota: cal ficar un espai entre "Pagina2" i "#desde#fins". Les mateixes àncores "#desde#fins" haurien d'estar presents a ambdós pàgines. Si no es troben les àncores indicades a la primera de les pàgines disponibles (bé Pagina1 o bé Pagina2), aleshores s'inclouran tots els continguts de la pàgina.

Açò no funciona correctament ara per ara (versió 2.2.33). Podeu trobar una solució a Cookbook:IncludeSection.

(:include Pagina1#desde1#fins1 Pagina2#desde2#fins2:)

Inclou els continguts de la primera pàgina disponible, bé sigui Pagina1 (entre [[#desde1]] i [[#fins1]]) o bé sigui Pagina2 (entre [[#desde2]] i [[#fins2]] )

Nota: Les versions anteriors de PmWiki, sense voler, permetien espais en blanc entre les àncores #desde i #fins. Les versions més noves ja no ho permeten. Per a tornar a habilitar aquest comportament "no-desitjat" afegiu açò al fitxer config.php o farmconfig.php:

Markup('includeanchors', '<include', '/(\\(:include.*?#\\w+)\\s+(#\\w+)/', '$1$2');

Lines=

(:include NomPagina lines=10:)

(:include NomPagina lines=5..10:)

(:include NomPagina lines=5..:)

Inclou les primeres 10 línies, les línies 5 a 10, o de la línia 5 en avant de NomPagina. Una "línia" es refereix en aquest context a una lína de codi. Per tant, una línia pot ser un paràgraf llarg (en la pantalla s'estén a més d'una línia), o una línia completament en blanc.

(:include Pagina1 Pagina2 Pagina3 lines=1..5:)

Inclou les primeres cinc línies de la primera pàgina disponible entre Pagina1, Pagina2, o Pagina3. Per a incloure text de diverses pàgines, feu servir un (:include:] independent per a cada pàgina.

Self=

(:include NomPagina self=0:)

El paràmetre self pot prendre el valor 0 o 1. Indica si la directiva té permís per incloure la pàgina actual. És útil quan NomPagina és una variable com ara bé {$Name} i voleu evitar que s'inclogui la pàgina actual.

Variables de text d'una pàgina

{Grup/NomPagina$:Var}

Inclou valors d'una llista de definicions com a variables de text des d'una pàgina (opcional). Aquestes es defineixen mitjançant una llista de definicions (:ítem:descripció), amb un caràcter de dos punts com a delimitador (ítem:descripció), o la marca especial ((:ítem:descripció:)).

Basepage=

(:include NomPagina basepage=NomPaginaBase:)

Inclou NomPagina, però tractant tots els enllaços relatius i les variables de NomPagina com a relatius a NomPaginaBase.

Per tant, si hom crea PlantillaNom com a

Nom: {$:Nom}
Adre&ccedil;a: {$:Adre&ccedil;a}

aleshores la directiva

(:include PlantillaNom basepage=NomPaginaBase:)

recuperarà els continguts de PlantillaNom, tractant les variables de pàgina i els enllaços com si fossin relatius a NomPagina. En concret, els valors de {$:Nom} i {$:Adreça} s'agafaran de NomPagina; passaria el mateix amb altres variables com {$Title} i {$LastModifiedBy}.

Ús de basepage

L'objectiu principal de basepage és permetre la inclusió de pàgines tal i com es feia en les versions 2.1.x, on les variables de pàgina i els enllaços s'interpretaven en relació a la pàgina mostrada. Això s'aconsegueix mitjançant:

(:include AlgunaAltraPagina basepage='' :)

-o-

(:include AlgunaAltraPagina basepage={*$FullName} :)

També permet que les pàgines GroupHeader i GroupFooter tractin les seues variables i enllaços de forma relativa a la pàgina que es mostra (enlloc de fer-ho en relació a GroupHeader i GroupFooter):

  ## PmWiki default $GroupHeaderFmt setting
  $GroupHeaderFmt = 
    '(:include {$Group}.GroupHeader self=0 basepage={*$FullName}:)(:nl:)';

De no ser així, l'ús de la variable IncludeOtherPages dintre de GroupHeader mostraria 'GroupHeader' i no pas el nom de la pàgina mostrada.

El paràmetre basepage= és suficientment general per a fer-se servir com a plantilla, de manera que pot agafar una pàgina --que fem servir com a plantilla-- que contingui variables i emplenar-les al moment amb els valors d'un altra pàgina:

(:include PaginaPlantilla basepage=PaginaDades :)

I, com sempre, una única PaginaPlantilla pot contenir diverses plantilles delimitades per àncores, de manera que al final acabem amb una sintaxi misteriosament similar^[1] a la de les plantilles per als llistats de pàgines:

    (:include PaginaPlantilla#abc basepage=PaginaDades :)

Així que PaginaPlantilla pot usar una sintaxi com:

    
    [[#abc]]
    ...ací van les coses de la plantilla...
    [[#abcend]]

i és possible mostrar PaginaPlantilla com una plantilla sense que s'interpreti... el mateix que fem amb Site.PageListTemplates.

^[1]D'acord, no és tan misteriós, ja que el codi de la plantilla de llistat de pàgines usa la mateixa funció que (:include:) per obtenir-ne les plantilles. Però tot i això és una comparació útil.

Especificar les variables com a paràmetres

Podeu especificar valors per a les variables directament a la sentència d'inclusió, i fer referència a les variables des de la plantilla usant el format {$$variable1}:

(:include PaginaPlantilla variable1="valor" variable2="valor2":)

Amb això assumim que el lloc té habilitat $EnableRelativePageVars, recomanat des de PmWiki 2.2.0 -- però deshabilitat per defecte en les versions 2.2.8 i anteriors.

Per exemple, a la pàgina inclosa ("plantilla") puc tenir:

[[#ivars]]
Hola, {$$Nom}, com estàs avui?
[[#ivarsend]]

Hola, {$$Nom}, com estàs avui?

Aleshores, incloent eixa secció de dalt (disponible via {$FullName}#ivars)) obteniu aquest resultat:

(:include {$FullName}#ivars Nom=Mariola:)

Hola, Mariola, com estàs avui?

Si el valor conté espais, tanqueu-lo entre cometes:

(:include {$FullName}#ivars Nom="el meu amic":)

Hola, el meu amic, com estàs avui?

Vegeu també $EnableUndefinedTemplateVars.

Vegeu també

Variables de text d'una pàgina Variables d'una pàgina que estan disponibles mitjançant marques de pàgina
Cookbook:IncludeUrl

Nota sobre l'ús d'estils

Per defecte, les pàgines o línies incloses no es poden distingir de qualsevol altre text de la pàgina. Per tal d'indicar visualment que aquest text és especial, podeu aplicar-hi Estils wiki. Per exemple:

%define=leftborder border-left="2px solid #88f" margin-left="2px" padding="1px 0 3px 10px"%
Què és PmWiki?
>>leftborder<< (:include PmWikiCa.PmWikiCa lines=1..4:) 
>><<
''Que tingueu un bon dia!''

Què és PmWiki?

PmWiki és un sistema per la creació i el manteniment de pàgines web basat en sistemes wiki.

Les pàgines de PmWiki tenen l'aspecte de qualsevol altra pàgina web, excepte pel fet de tenir un enllaç per a "editar" que permet modificar-les amb facilitat, així com afegir-ne de noves, usant unes regles d'edició. No és necessari saber HTML o CSS. L'edició de pàgines es pot deixar oberta al públic o restringir-la a un xicotet grup d'autores.

Que tingueu un bon dia!

Referències als paràmetres

Es pot accedir a qualsevol paràmetre que se li passa a una sentència d'inclusió des de dintre de la pàgina inclosa com una variable especial {$$...} del mateix nom. Podem usar aquest funcionalitat per a mostrar informació extra a l'hora de mostrar la pàgina inclosa.

Notes

També podeu usar (:include Meua/Pagina#meuaancora lines=4:) que comença, i inclou, la línia amb l'àncora [[#meuaancora]] i les tres línies següents.

Notes sobre l'ús amb ConditionalMarkup?

La directiva (:include ...:) es processa després que s'avaluïn les sentències condicionals.
Per tant podeu incloure una pàgina o una secció com a part d'una condició, com per exemple

(:if alguna condicio:)(:include AlgunaPagina#seccio:)(:ifend:)

Per contra, (:include AlgunaPagina#seccio:) no comprova si [[#seccio]] forma part d'una condició, com ara bé

(:if alguna condicio:)[[#seccio]]...[[#seccioend]](:ifend:)

(:include AlgunaPagina#seccio:) ignorarà per complet la condició.

Quan s'avaluen variables? a les pàgines incloses, el context de la pàgina (font o objectiu) pot resultar útil. Vegeu referències especials? per a més detalls.

Quin és el nombre màxim d'inclusions que poden haver a una pàgina?

Per defecte, PmWiki estableix un límit de 50 inclusions de pàgina, per tal de prevenir l'aparició de bucles infinits o altres situacions que puguin acaparar els recursos del servidor. (Dos d'aquestes pàgines incloses són GroupHeader i GroupFooter.) Una administradora? pot modificar-lo mitjançant la variable $MaxIncludes.

Hi ha alguna manera d'incloure continguts des d'un grup de pàgines sense especificar el nom exacte, p.ex. entre l'àncora X i Y des de totes les pàgines anomenades SiClasse-* ?

Es pot fer mitjançant Llistats de pàgines.

Sembla que hi ha un problema de visualització quan la pàgina inclosa conté la directiva (:title:).

En la instal·lació per defecte, l'últim títol de la pàgina sobreescriu els anteriors, així que podeu col·locar la directiva (:title :) al final de la pàgina, després de totes les inclusions. Vegeu també $EnablePageTitlePriority.