Einbinden anderer Seiten

für die Liste aller Seiten

Die (:include:)-Direktive ermöglicht das Einbinden (oder die "Transclusion") des Inhaltes anderer Wikiseiten in die aktuelle Wikiseite. Alle der unten aufgeführten Direktiven fügen nur den reinen Wiki-(Quell-)-Text ein. Insbesondere werden alle Seiten-Verweise der eingebundenen Seite auf die aktuelle Gruppe der aktuellen Seite bezogen, wenn nichts anderes angegeben ist.

Syntax

Die grundlegende Syntax ist

• (:include SeitenName:)
  bindet die ganze Seite mit dem Seitennamen SeitenName aus der gleichen Gruppe ein.
• {Gruppe/SeitenName$:STVar}
  fügt eine Seiten-Text-Variable aus einer Seite ein, Gruppe und SeitenName sind Optionen.

Die vollständige Syntax ist

• (:include vollerName#vonAnker#bisAnker lines=12..34 self=0 basepage=abc variable=Wert :)

Parameter

Die Direktive kann mehrere Namen-Parameter mit oder ohne Anker und mehrere Vorlagenvariablen-Parameter enthalten.

Benannte Seiten

Sie können das obige Verhalten nutzen, um eine Fehlermeldung anzuzeigen, wenn ein Einbinden scheitert. Legen Sie eine Seite an, z. B. Site.EinbindenGescheitert, die die Fehlermeldung enthält. Sie können jeden Seitennamen wählen. In der Include-Direktive hängen Sie dann diese Seite an das Ende der Seitenliste an:

     (:include Seite1 Seite2 Seite3 Site.EinbindenGescheitert:)

Ein etwas komplexerer Ansatz wird in der 'talk'-Seite beschrieben (auf englisch).

#von#bis-Anker

Lines=von..bis

Self=

Seiten-Text-Variablen

Basepage=

Wenn basepage= übergeben wird, werden alle relativen Verweise und alle Seitenvariablen relativ zur 'basepage' interpretiert. Wenn also jemand die Seite VorlagenName anlegt mit

Name: {$:Name}
Addresse: {$:Addresse},

wird die Direktive

den Inhalt von VorlagenName holen, dabei aber alle Seitenvariablen und Verweise als relativ zu SeitenName behandeln. Insbesondere werden die Werte von {$:Name} und {$:Addresse} von SeitenName geholt, auch Dinge wie {$Title} und {$LastModifiedBy} würden hier funktionieren.

Einsatz von Basepage

Die vornehmliche Aufgabe von Basepage ist, das Einbinden von Seiten auf eine Weise zu erlauben, die das Verhalten von 2.1.x nachahmt, wo Seitenvariablen und Links relativ zur aktuellen Seite interpretiert wurden. Das machen Sie mit:

  -oder-

Das erlaubt auch GroupHeader und GroupFooter, ihre Seitenvariablen relativ zur (umrahmten) aktuellen Seite zu sehen (anstatt relativ zum GroupHeader oder GroupFooter):

    ## PmWikis Standard-$GroupHeaderFmt-Einstellung
    $GroupHeaderFmt = 
        '(:include {$Group}.GroupHeader self=0 basepage={*$FullName}:)(:nl:)';

Andernfalls würde der Einsatz von {$Name} innerhalb eines GroupHeaders eben 'GroupHeader' anzeigen und nicht den Namen der aktuellen Seite.

Der basepage=-Parameter ist generell genug, dass er auch als Vorlagen-Maschine benutzt werden kann, sodass wir eine Vorlagenseite hernehmen können, die Variablen enthält, welche dann mit den Werten aus einer anderen Seite gefüllt werden:

Und natürlich kann eine einzelne Vorlagenseite mehrere Vorlagen, begrenzt durch Anker, enthalten, so dass wir am Ende bei einer Syntax landen, die der von Seitenlistenvorlagen auf unheimliche Weise^[1] ähnlich ist:

    (:include VorlagenSeite#abc basepage=DatenSeite :)

Passend dazu kann VorlagenSeite eine Syntax wie diese benutzen:

    
    [[#abc]]
    ... hier der Vorlagenkrimskrams ...
    [[#abcend]]

und es ist möglich die VorlagenSeite als Vorlage zu nutzen, ohne dass sie insgesamt angezeigt wird – gerade so wie wir es bei Site.PageListTemplates machen.

Angabe von Variablen als Parameter

Man kann auch Variablenwerte in der IncludeDirektive angeben und Bezüge zu den Variablen der Vorlage herstellen mit dem {$$variable1}-Format:

Das setzt voraus, dass eine Site $EnableRelativePageVars aktiviert hat, was seit PmWiki 2.2.0 angeraten wird – es war aber nicht Standard in Version 2.2.8 und früheren wegen der Kompatibilität mit Versionen 1.x.x.

Ich könnte zum Beispiel auf meiner Einfügeseite Folgendes haben:

[[#ivars]]
Hi, {$$Name}, wie geht es dir heute?
[[#ivarsend]]

Wenn man dann den obigen Abschnitt einfügt (der Abschnitt ist erreichbar durch den Abschnitt {$FullName}#ivars), ergibt sich dieses Verhalten:

(:include {$FullName}#ivars Name=Sam:)

Wenn ein Wert Leerzeichen enthält, gehört er in Anführungszeichen.

(:include {$FullName}#ivars Name="mein Freund":)

Siehe auch $EnableUndefinedTemplateVars.

Besondere Anweisungen

(:nl:) wirkt wie ein Zeilenvorschub im Quelltext, doch nur, wenn an der Stelle noch keiner ist.

Der Zweck von (:nl:) ist, Konstruktionen wie "(:include Page1:)(:nl:)(:include Page2:)" zu ermöglichen und dabei sicherzustellen, dass die erste Zeile von Page2 getrennt von der letzten Zeile in Page1 behandelt wird, ohne dabei unbeabsichtigt eine Leerzeile zu erzeugen.

Mehr Informationen in dieser Diskussion und dieser Diskussion (englisch).

(:nl:) ist nicht vorgesehen, einen Zeilenvorschub in der Ausgabe zu erzeugen!

Siehe auch

• Seiten-Text-Variablen Beschreibt die Verwendung von im Text der Seiten verwendeten Variablen
• Cookbook:IncludeUrl

Bemerkung zum Stil

Im Standard können eingebundene Seiten oder Zeilen nicht vom anderen Text unterschieden werden. Um einen visuellen Hinweis darauf zu geben, dass dieser Text besonders ist, kann man Wiki Styles anwenden. Zum Beispiel:

%define=leftborder border-left="2px solid #88f" margin-left="2px" padding="1px 0 3px 10px"%
Was ist PmWiki?
>>leftborder<< (:include PmWikiDe.PmWiki lines=1..9:) 
>><<
''Einen schönen Tag noch!''

Parameterbezüge

Alle an eine Include-Direktive übergebenen Parameter (ob es nun Schlüsselwörter sind oder nicht) sind von innerhalb der eingebunden Seite erreichbar als eine besondere {$$...}-Variable gleichen Namens. Dieses Feature kann ausgenutzt werden, um Extrainformationen zu liefern, wenn die eingebundene Seite angezeigt wird.

Anmerkung

• man kann auch (:include Meine/Seite#meinAnker lines=4:) schreiben, womit vier Zeilen, beginnend mit und einschließlich der Zeile mit dem Anker [[#meinAnker]], eingebunden werden.

Anmerkungen zum Einsatz von bedingten Auszeichnungen

Die (:include:)-Direktive wird erst ausgeführt, nachdem bedingte Textauszeichnungen ausgewertet wurden.
Deshalb kann man eine Seite als Teil einer Bedingung einbinden:

Aber (:include EineSeite#abschnitt:) prüft nicht, ob [[#abschnitt]] selbst Teil einer bedingten Textauszeichnung wie

ist. (:include EineSeite#abschnitt:) ignoriert eine solche Bedingung.

Wenn man in eingebundenen Seiten Variablen testet, kann der Kontext (Quelle oder Ziel) nützlich sein. Siehe Spezielle Verweise wegen der Details.

für die Liste aller Seiten