xsl:include

(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

 

Das Toplevel-Element xsl:include dient dazu, die Deklarationen und Template-Regeln eines Stylesheets in ein anderes einzufügen. Die Inkludierung entspricht von der Wirkung einer physischen Kopie der Inhalte in das Hauptstylesheet an der Stelle der Deklaration.

Klassifizierung Deklaration
Funktionsgruppe Stylesheetstruktur
Einführung XSLT 1.0

Position im Stylesheet und erlaubte Inhalte:

xsl:include darf nur als Kindelement von xsl:stylesheet oder xsl:transform auftreten. Eine Reglementierung in Bezug auf die Position gegenüber den anderen Toplevel-Elementen gibt es im Gegensatz zu xsl:import nicht, sodass xsl:include auf dieser Hierarchieebene an beliebiger Stelle und in beliebiger Anzahl im Stylesheet (jedoch nicht vor eventuellen xsl:import) auftreten darf. Es dürfen beliebig viele xsl:include-Anweisungen im Dokument auftreten. Das Element ist stets leer.

Attribute:

Es gelten die Standardattribute. Die Deklaration xsl:include besitzt außerdem ein obligatorisches Attribut href.

href

Wert

uri-reference

Verwendung

Obligatorisch

Einführung

XSLT 1.0

Das obligatorisch zu setzende href-Attribut enthält als Wert einen relativen oder absoluten URI-String. Ein relativer URI wird dabei gegen den Basis-URI des inkludierenden Stylesheets aufgelöst.

Verwendungszweck:

Die Anweisung xsl:include bewirkt eine Einfü­gung der Deklarationen und Template-Regeln eines externen XSLT-Stylesheets in das Hauptstylesheet. Die Template-Regeln und Deklarationen des inkludierten Stylesheet besitzen dabei exakt die gleiche Importpräzedenz wie jene lokal im inkludierenden Stylesheet vorhandenen. Sie verhalten sich somit genau so, als ob sie real anstelle der xsl:include-Anweisung in das Hauptstylesheet einge­fügt wären.

Hinweis – Erstellung kompatibler Stylesheets
Soll ein Stylesheet erstellt werden, das sowohl unter XSLT 1.0 als auch unter XSLT 2.0 ausgeführt werden soll, so ist es empfehlenswert, zwei unterschiedliche Hauptmodule (principal stylesheet modules) zu schreiben, die den Versionsstand version="1.0" respektive version="2.0" angeben und lediglich als Einstiegsmodule dienen.
Mittels xsl:import bzw. xsl:include können von dort aus nun die jeweils gewünschten Module geladen werden (auch verschiedene). Jedes der Module kann nun einen individuellen Versionsstand besitzen, der auf »1.0« oder »2.0« steht, je nachdem, ob XSLT 2.0-Instruktionen enthalten sind oder nicht.

Keine Selbstinklusion
Ein Stylesheet darf sich nicht unabsichtlich, weder direkt noch indirekt, selbst inkludieren – dies bewirkt eine Fehlermeldung. Analog zu xsl:import ist ein entsprechender Zirkelbezug verboten und gilt als statischer Fehler (ERR XTSE0180).

Lösung im Konfliktfall
Treten durch eine Inklusion mehrere identische Template-Regeln auf, so wird der XSLT-Parser diese entsprechend ihrer Stellung in der Dokumentreihenfolge behandeln. In der Regel gilt die an letzter Stelle im Stylesheet stehende Template-Regel (Deklarationsreihenfolge), sodass die Inkludierungsanweisung sinnvollerweise an den Anfang des Stylesheets plat­ziert werden sollte. Dies erlaubt dem XSLT-Prozessor bei versehentlichen Dopplungen, den lokalen Template-Regeln den Vorrang zu geben.

Eine Ausnahme in Bezug auf die Positionierung der externen Inhalte sind durch Inklusion eingefügte xsl:import-Deklarationen. Diese werden nicht zusammen mit den anderen Deklarationen und Template-Regeln anstelle der xsl:include-Anweisung eingefügt, sondern zwischen die lokal vorliegenden Import-Anweisungen und die auf diese folgenden Toplevel-Elemente. Es ist zu beachten, dass die als letzte auftretende Import-Deklaration die höchste Importpräzedenz besitzt, eine durch Inklusion eingefügte entsprechende Deklaration daher Vorrang vor lokal vorhandenen hat.

Inklusion von globalen Parameter- und Variablendeklarationen
Vorsicht ist geboten bei der Inklusion von globalen Parameter- und Variablendeklarationen xsl:param und xsl:variable. Hier dürfen keinesfalls globale Deklarationen eingefügt werden (also Parameter oder Variable im Toplevelbereich), die gleichnamig zu bereits im inkludierenden Stylesheet definierten sind, oder zu solchen Deklarationen, die ebenfalls durch Inklusion weiterer Stylesheets eingefügt werden. Der Hintergrund hierzu ist, dass in diesem Fall keine Importpräferenz greifen kann, da inkludierte Deklarationen prinzipiell gleichrangig sind! Namensdoubletten bewirken daher einen statischen Fehler (ERR XTSE0630). Auf Template-Regeln bezogene lokale Variablen und Parameter sind in dieser Beziehung unkritisch.

Inklusion von Funktionsdeklarationen
Eine Inklusion von Stylesheetmodulen, die Funktionsdeklarationen xsl:function enthalten, ist möglich, solange dadurch nicht Dopplungen auftreten, die gleichzeitig den Funktionsbezeichner und die Parameterzahl (arity) betreffen. Gleichnamige Funktionen verschiedener Parameterzahl sind gestattet. Unerlaubte Dopplungen hingegen ergeben einen statischen Fehler (ERR XTSE0770).

Inklusion von Schlüsseldeklarationen
Auch xsl:key-Deklarationen können zusammen mit einem externen Stylesheet inkludiert werden. Das Prinzip der Importpräzedenz spielt hier keine Rolle – alle Keys sind gültig. Bei der Referen­zierung mit key() ist darauf zu achten, dass jenes Dokument »im Fokus« ist, in dem sich die zu durchsuchenden Elemente befinden.

Basis-URI ist modulbezogen
Die eingefügten Template-Regeln und Deklarati­onen behalten ihren Basis-URI, was dann wichtig ist, wenn sie weitere xsl:include oder xsl:import-Anweisungen beinhalten oder dort innerhalb von XPath-Ausdrücken die document()-Funktion verwendet wird.

Namensraumdeklarationen sind modulbezogen
In den externen Stylesheet­modulen definierte Namensräume beziehen sich weiterhin nur auf die inklu­dierten Template-Regeln und Deklarationen. Dies gilt auch für durch exclude-result-prefixes ausgeschlossene Namensräume, mit extension-element-prefixes deklarierte Namensräume von Erweiterungsfunktionen sowie durch xsl:exclude-result-prefixes für Literal Result Elements von der Kopie ins Ergebnisdokument ausgeschlossene Namensräume. Gleichermaßen werden auch die Namensraumdeklarationen des inkludierenden Stylesheets nicht auf die eingebetteten Regeln ausgedehnt.

Beispiele:

Beispiel 1 – Inklusion eines Stylesheetmoduls:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
  <xsl:include href="beispiel_include.xsl"/>
  <xsl:template match="/">
    ...
  </xsl:template>
</xsl:stylesheet>

In das Hauptstylsheet wird ein externes Stylesheetmodul inkludiert.

Beispiel 2 – Alternative Inklusion mittels use-when-Attribut

Interessant ist die Möglichkeit in XSLT 2.0, mittels des use-when-Standardattributs bedingte Inkludierungen vornehmen zu können:

<xsl:include href="beispiel_include_1.xsl" use-when="system-property('xsl:vendor')='Altova'"/>
<xsl:include href="beispiel_include_2.xsl" use-when="system-property('xsl:vendor')='Saxonica'"/>

Je nachdem, welcher Prozessor das vorliegende Stylesheet ausführt, werden unterschiedliche Stylesheetmodule inkludiert. Dies gilt jedoch nur für Prozessoren, die XSLT 2.0 unterstützen – ein XSLT 1.0-Prozessor im vorwärtskompatiblen Modus würde das use-when-Attribut ignorieren und beide Inklusionen vornehmen.

Elementdefinition:

XSLT 1.0:

<!-- Category: top-level-element -->
<xsl:include 
     href = uri-reference 
/>

XSLT 2.0:

<!-- Category: declaration -->
<xsl:include
     href = uri-reference 
/>
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