xsl:call-template

(Auszug aus "XSLT 2.0 & XPath 2.0" von Frank Bongers, Kapitel 6.)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

 

Der Befehl xsl:call-template ruft – vergleichbar einer Subroutine – eine benannte Template-Regel auf. Hierbei können an die aufgerufene benannte Template-Regel auch Parameterwerte übergeben werden.

Klassifizierung Instruktion
Funktionsgruppe Template-Regeln und Aufruf
Einführung XSLT 1.0

Position im Stylesheet und erlaubte Inhalte:

xsl:call-template ist eine Instruktion und erscheint deshalb innerhalb eines Templateblocks. Das Element kann leer sein, wird aber in der Regel ein oder mehrere xsl:with-param-Instruktionen enthalten. Damit ist eine Parameterübergabe an das aufgerufene Template – sofern dort xsl:param-Elemente mit korrespondierenden Namen existieren – oder die Hinzufügung von Tunnelparametern zum Tunnelstrom möglich.

Attribute:

Es gelten die Standardattribute. Die Instruktion xsl:call-template besitzt ein obligatorisches Attribut name, dessen Wert ein QName sein muss.

name

Wert

QName

Verwendung

Obligatorisch

Einführung

XSLT 1.0

Der Wert des name-Attributs ist ein »quali­fied name«, kann also gegebenenfalls einen Namensraum besitzen. Der übergebene QName muss dem QName eines im Stylesheet befindlichen benannten Temp­lateblocks entsprechen. Existiert kein solches Template, so gilt dies als statischer Fehler (ERR XTSE0650).

Der Bezeichner des aufgerufenen Templates muss explizit festgelegt werden, etwa um »nach Bedarf« auf unterschiedliche Temp­lateblöcke zu verweisen. Es besteht daher nicht die Möglichkeit, den Bezeich­ner durch eine zur Laufzeit ausgewertete Variable zu ersetzen.

Verwendungszweck:

Die Instruktion xsl:call-template dient dazu, aus einem Templateblock heraus ein anderes Template über dessen Namen explizit aufzurufen. Vergleichbar ist dies mit dem Aufruf einer Subroutine. So kann ein benanntes Template auch unabhängig vom aufrufenden Kontext fest­gelegte Arbeiten verrichten oder Inhalte ins Ergebnisdokument ausgeben.

Der Aufruf eines benannten Templates unterscheidet sich vom impliziten Auf­ruf einer Template-Regel durch von xsl:apply-templates zusammengestellte Sequenzen. Die aktuelle Template-Regel – und damit der Current Node des auf­rufenden Templates – bleibt durch xsl:call-template unverändert. Der Pro­zessor kann im aufgerufenen Template also weiterhin auf denselben aktuellen Knoten zugreifen.

Alternativ kann eine zu verarbeitende Sequenz mittels Parameter (siehe unten) übergeben werden. Diese Möglichkeit macht xsl:call-template in Verbin­dung mit sich selbst wieder aufrufenden benannten Templates zum zentralen Element für rekursive Templateverarbeitung.

Zwar kann ein benanntes Template – wie jedes andere Template auch – Inhalte in die aktuelle Resultatsequenz der Transformation ausgeben. Die Rückgabe eines Ergebniswertes an den Ort des Aufrufes durch xsl:call-template ist jedoch nicht unmittelbar möglich, da eine Funktionalität wie »return« nicht vorgesehen ist. Als Ersatz umgibt man xsl:call-template mit einer Variab­lendefinition xsl:variable, die den Output des Templates auffängt.

Keine Templatemodes bei benannten Template-Regeln:

Die Instruktion xsl:call-template besitzt im Gegensatz zu xsl:apply-templates kein mode-Attribut. Es besteht also nicht die Möglichkeit, zwei gleich benannte Tem­plates etwa durch deren Modi zu unterscheiden. Da die Steuerung also allein über den Namen stattfinden muss, dürfen im Stylesheet keine zwei gleich benannten Templates mit gleicher Importpräzedenz auftreten.

Hinweis – mode-Attribut nur gleichzeitig mit match-Attribut
Besitzt ein benanntes Template zusätzlich ein match-Attribut, so darf es auch ein mode-Attribut besitzen. Das mode-Attribut hat dann aber ebenfalls nur bei Verwendung dieses Templates als Template-Regel eine Bedeutung, nicht bei dessen Aufruf mittels xsl:call-template.

Übergabe von Parameterwerten:

Die Instruktion xsl:call-template kann ein oder mehrere xsl:with-param-Elemente beinhalten, die an korrespondierende xsl:param-Instruktionen in der benannten Template-Regel je einen Wert übergeben können. Dabei dürfen keine zwei xsl:with-param-Elemente denselben Bezeichner verwenden.

In zwei Fällen können in XSLT 2.0 in Zusammenhang mit Wertübergaben aus xsl:call-template heraus statische Fehler auftreten, die die Verarbeitung des Stylesheets verhindern:

  1. Es wird versucht, einen Wert an einen Parameter zu übergeben, der im Ziel­template nicht existiert (ERR XTSE0680).
  2. Es wird unterlassen, einen Wert an einen Parameter im Zieltemplate zu überge­ben, dessen required-Attribut auf "yes" steht (ERR XTDE0700).

Vorsicht bei Wertübergabe an nicht-existente Parameter
In XSLT 2.0 ist es ein statischer Fehler, wenn in der adressierten Temp­late-Regel keine zu einer xsl:with-param-Instruktion korrespondierenden xsl:param-Elemente vorhanden sind (ERR XTSE0680). Dies gilt jedoch nicht, wenn der Prozessor im rückwärtskompatiblen Modus betrieben wird, oder es sich bei dem übergebenen Parameter um einen Tunnelparameter handelt. XSLT 1.0 verhält sich grundsätzlich gutmütiger und ignoriert den entsprechenden Versuch einer Wertübergabe.

Beispiele:

Beispiel 1 – Benannte Template-Regel mit passendem Aufruf:

<!-- ein benanntes Template: -->
<xsl:template name="mein_template" match="egal">
  ...
</xsl:template>
<!-- wird aufgerufen durch: -->
<xsl:template select="/">
  <xsl:call-template name="mein_template"/>
</xsl:template>

Die Positionen von benannter Template-Regel und Aufruf in der Dokumentrei­henfolge des Stylesheets sind irrelevant, da Templatenamen und -inhalte sofort nach Einlesen des Stylesheets abgespeichert sind. Eine dynamische Zuweisung der aufzurufenden Namen ist im Hinblick auf Eindeutigkeit bei der Verarbei­tung verboten (die Prüfung der Bezeichner erfolgt im statischen Kontext).

Beispiel 2 – Auffangen des Templateresultats in einer Variable:

...
<xsl:variable name="rueckgabewert">
  <xsl:call-template name="berechne-was">
    <xsl:with-param name="die-werte" select="$werte"/>
  </xsl:call-template>
</xsl:variable>
<!-- Rückgabewert ausgeben -->
Das Ergebnis ist <xsl:value-of select="$rueckgabewert"/>
...

Hinweis – Inhalt von xsl:variable wird nicht direkt ausgegeben
Der Inhalt eines Elements xsl:variable wird nie direkt in das Ergebnisdokument ausgegeben, sondern stets als temporärer Baum (temporary tree) in der Variablen gespeichert.

Beispiel 3 – Rekursion durch Aufruf benannter Templates:

<!-- erster Aufruf des benannten Templates -->
...
<xsl:call-template name="rekursiv">
  <xsl:with-param name="verarbeiten" select="$anfangswert"/>
</xsl:call-template>
...
<!-- das rekursive Template -->
<xsl:template name="rekursiv">
  <xsl:param name="verarbeiten" select="defaultwert"/>
  <!-- irgendeine Verarbeitung speichert in "$restwert" -->
  ...
  <!-- das Template ruft sich selbst auf: -->
  <xsl:call-template name="rekursiv">
    <xsl:with-param name="verarbeiten" select="$restwert"/>
  </xsl:call-template>
</xsl:template>

Achtung – Vorsicht vor Endlosschleifen bei rekursivem Aufruf
Es muss darauf geachtet werden, hier keine Endlosschleife zu erzeugen. Für eine anwendbare Version dieses Beispiels muss eine entspre­chende Abbruchbedingung eingearbeitet werden, beispielsweise mittels xsl:if.

Elementdefinition:

XSLT 1.0:

<!-- Category: instruction -->
<xsl:call-template 
     name = qname>

     <!-- Content: xsl:with-param* -->

</xsl:call-template>

XSLT 2.0:

<!-- Category: instruction -->
<xsl:call-template
     name = qname>

     <!-- Content: xsl:with-param* -->

</xsl:call-template>
Tipp der data2type-Redaktion:
Zum Thema XSLT bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © Galileo Press, Bonn 2008
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "XSLT 2.0 & XPath 2.0 ― Das umfassende Handbuch" denselben Bestimmungen wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


Galileo Press, Rheinwerkallee 4, 53227 Bonn