document

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

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

   

Kategorie: Assoziation und Auffindung von Nodes und Ressourcen

Herkunft: XSLT 1.0

Rückgabewert: Eine Sequenz aus Document Nodes externer XML-Dokumente

Aufruf/Argumente:

document($uri-sequenz, $base-node)

$uri-sequenz:
Obligatorisch. Das erste Argument der Funktion muss entweder unmittelbar ein URI eines externen Dokuments sein, oder ein Ausdruck, der als URI interpre­tiert werden kann. Hierbei kann es sich um einen relativen URI, einen absoluten URI oder um einen Fragment-Identifier handeln. In der Regel wird es ein String xs:string sein, der direkt als URI-Referenz behandelt werden kann.

Alternativ kann eine Sequenz aus mehreren Items (in XSLT 1.0 ein Nodeset aus einem oder mehreren Knoten) übergeben werden. Die Stringwerte aller in der übergebenen Sequenz enthaltenen Items müssen URI-Strings entsprechen und werden jeweils einzeln durch die document()-Funktion ausgewertet.

Ist eine URI-Referenz nicht auflösbar, wird entweder ein Fehler gemeldet, oder – jeweils pro betroffenes Item – eine leere Sequenz zurückgegeben.

Gilt dies für einen oder mehrere Knoten einer übergebenen Sequenz, so bedeutet dies, dass für die betreffenden Knoten kein Document Node erzeugt wird. Diese Knoten sind folglich in der insgesamt generierten Ausgabesequenz (der Vereinigungsmenge aller referenzierten Dokumente) nicht enthalten.

$base-node:
Optional. Falls als zweites Argument ein Knoten übergeben wird, so wird dessen Basis-URI eingesetzt, um relative URIs des externen Dokuments aufzulösen. Erforderlich ist dies, sofern der übergebene URI $uri nicht relativ zum Stylesheet (bzw. zum Basis-URI des Kontextknotens), bewertet werden soll.

Wird ein $base-node-Argument übergeben, so bezieht es sich auf alle durch das erste Argument referenzierten Dokumente. Handelt es sich beim Argument nicht um einen (einzelnen) Knoten, so wird ein Typfehler gemeldet. Wird für $base-node eine Knotensequenz übergeben, so wird nur deren erstes Item beachtet, sofern im XPath 1.0-kompatiblen Modus gearbeitet wird (XPath 1.0 compatibility mode). Ansonsten wird ebenfalls ein Typfehler gemeldet.

Anmerkung: Die in XPath 2.0 alternativ eingeführte Funktion fn:doc() besitzt kein $base-node entsprechendes zweites Argument. Zum Ausgleich kann dort jedoch zusätzlich die Funktion fn:resolve-uri() herangezogen werden.

Verwendungszweck:

Aufgabe der document()-Funktion ist es, in die XSLT-Verarbeitung ein oder mehrere andere externe XML-Dokumente einzubeziehen. Rückgabewert der Funktion ist eine Sequenz (in XPath 1.0 ein Nodeset), beste­hend aus den Document-Nodes des oder der entsprechenden Dokumente. Das Argument wird als Sammlung der URIs interpretiert, unter dem diese zu finden sind.

Der einfache Fall besteht darin, dass ein String, oder ein Node, dessen String­wert verwendet werden soll, übergeben wird, aus dem sich der URI genau eines externen Dokuments ergibt.

Wird als erstes Argument jedoch eine Sequenz übergeben, so wird jedes einzelne ihrer Items anhand der docu­ment()-Funktion aufgelöst. Für diejenigen Items, für die die Auflö­sung nach einem URI erfolgreich ist, wird der Ergebnissequenz ein Document Node hinzugefügt, die anderen werden nicht berück­sichtigt (je nach Implementierung kann auch eine Fehlermeldung erfolgen).

Anmerkung: Es besteht die potenzielle Gefahr, dass in referenzierten Dokumenten zum Quelldokument gleichlautende Elementna­men in anderer Bedeutung verwendet werden – für ihre Verarbeitung würden folglich ungewollt dieselben Templates eingesetzt wie für diejenigen des Quelldokuments.

Alternative Funktion fn:doc in XPath 2.0:
XPath 2.0 führt alternativ zu document() die vereinfachte Funk­tion fn:doc() ein, die als XPath-Core-Funktion auch außerhalb des XSLT-Kontexts nutzbar ist, also beispielsweise in XQuery. Die Funktion fn:doc() übernimmt nur ein Argument, nämlich einen URI-String. Ein Basis-URI kann ihr nicht übergeben werden.

Beispiel – Dynamisches Einbinden externer Quellen mit docu­ment():

Das Quelldokument:
Angenommen, zu einem Buch existieren Rezensionen in Form von externen XML-Dateien und es wird gewünscht, diese Rezensionen in Zusammenhang mit anderen Informationen über das Buch in ein Ergebnis­dokument auszugeben. Dies könnte auf Grundlage eines Dokuments ähnlich dem folgenden geschehen:

<buch>
  <!-- Verweise auf Rezensionen: -->
  <rezension datum="14.10.2006" quelle="Zeit" uri="rezensionen/zeit/14-10-2006/rez1.xml"/>
  <rezension datum="3.12.2006" quelle="Spiegel" uri="rezensionen/spiegel/3-12-2006/rez8.xml"/>
</buch>

Das Stylesheet:
Die Rezensionen können nun mit der document()-Funk­tion durch Übergabe ihrer jeweiligen im text-Attribut enthaltenen URI ins Ausgabedokument geholt werden; etwa so:

<xsl:template match="buch">
  <xsl:for-each select="rezension">
    <h2>Rezension in <xsl:value-of select="@quelle"/></h2>
    <xsl:apply-templates select="document(@uri)"/>
  </xsl:for-each>
</xsl:template>

Der Rückgabewert von document(@uri) ist eine Sequenz, bestehend aus einem Knoten – dem Document Node des externen Dokuments. Durch xsl:apply-templates wird in Folge das gesamte externe Dokument in den Verarbei­tungsprozess einbezogen und mit den, auch für das Hauptdokument zur Verfü­gung stehenden, Templates verarbeitet.

Ist eben dies nicht erwünscht, kann man ein mode-Attribut beim Aufruf von xsl:apply-templates einsetzen, also in folgender Form:

<xsl:apply-templates select="document(@uri)" mode="rezension"/>

Anschließend könnten Templates mit entsprechenden Modi zur Verfügung gestellt werden, die ausschließlich zur Verarbeitung externer Dokumente eingesetzt werden. Alter­nativ hierzu könnte man mit einem oder mehreren benannten Templates ar­beiten, an die das externe Dokument übergeben wird.

Funktionsdefinition:

XSLT 1.0:

document(object, node-set?) => node-set

XSLT 2.0:

document($uri-sequence as item()*) as node()*

document($uri-sequence as item()*,
         $base-node as node())      as node()*

Mögliche Kompatibilitätsprobleme XSLT 2.0 zu XSLT 1.0:
Die Funktion document() ist in XSLT 1.0 beim Datentyp des URI-Arguments nicht sehr spezifisch und lässt hier sowohl Strings als auch Nodesets zu. In XSLT 2.0 werden die Items der Eingabesequenz unabhängig von ihrem Daten­typ in den Typ xs:anyURI umgewandelt. Für jeden so ermittelten URI wird ein Document Node generiert, der in der Ausgabesequenz enthalten ist.

XPath 2.0 führt alternativ zu document() die weitgehend äquivalente, jedoch vereinfachte Funktion fn:doc() ein:

fn:doc($uri as xs:string?) as document-node()?

Die XPath 2.0-Funktion fn:doc() lässt für ihr (einziges) URI-Argument nur Strings zu. (Der ursprüngliche Plan, als Datentyp den XML Schema-Typ xs:anyURI zu fordern, wurde fallen gelassen. Der übergebene String muss jedoch lexikalisch xs:anyURI entsprechen.)

   

<< zurück vor >>
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