unparsed-entity-uri

The unparsed-entity-uri() function gives access to declarations of unparsed entities in the DTD of the source document.

For example, if the DTD contains the declaration:

  <!ENTITY weather-map SYSTEM "weather.jpeg" NDATA JPEG>

then the expression «unparsed-entity-uri('weather-map') » returns the URI «weather.jpeg » , expanded to an absolute URI by applying the base URI for the DTD.

Changes in 2.0

None.

Signature

Argument	Data Type	Meaning
name	xs:string	Specifies the name of the unparsed entity required. The value of the string should be an XML Name.
Result	xs:string	A string containing the URI (the system identifier) of the unparsed entity with the given name, if there is one. Otherwise, a zero-length string.

Effect

This function operates on the document containing the context node. An error is reported if the context item is undefined, or if it is not a node, or if it is a node in a tree whose root is not a document node.

If the document containing the context node includes an unparsed entity whose name is equal to the supplied string, then the system identifier for this unparsed entity is returned. In all other cases, it returns a zero-length string.

If the system identifier is given in the source XML as a relative URI, the XSLT processor should expand it into an absolute URI before returning it.

Usage

An unparsed entity is an entity defined in the DTD using a declaration of the form:

  <!ENTITY weather-map SYSTEM "weather.jpeg" NDATA JPEG>

It's the NDATA (meaning "not XML data") that makes it an unparsed entity; and because it is an unparsed entity, it can't be referenced using a normal entity reference of the form «&weather-map; » but must instead be referenced by name in an attribute of type ENTITY or ENTITIES , for example <forecast map="weather-map"> .

If you're using a schema-aware XSLT processor, and the document has been validated against a schema that defines the map attribute as being of type xs:ENTITY , then you can process the attribute using a rule such as:

  <xsl:template match="attribute(*, xs:ENTITY)">   <img src="{unparsed-entity-uri(,)}"/>   </xsl:template>

Without a schema, you are simply expected to know that the map attribute is of type xs:ENTITY , and expected to pick up the attribute value in a call such as «unparsed-entity-uri (@map) » . This call returns the absolute URI of the actual resource, that is, something like «file:///c:/document s/ forecasts/weather.jpeg » .

XSLT provides no way of finding out the notation name ( «JPEG » in our example) or the URI for the notation, so even if you have a schema that flags the attribute as one that contains an unparsed entity reference, you still have to know what kind of reference you are expecting.

This is not exactly in the spirit of section 4.4.6 of the XML specification, which states: "When the name of an unparsed entity appears as a token in an attribute of declared type ENTITY or ENTITIES, a validating processor must inform the application of the system and public (if any) identifiers for both the entity and its associated notation." However, unparsed entities are hardly XML's most widely used feature, so it is unsurprising that XSLT support for them should be incomplete.

The rules in the XSLT specification don't explicitly state this, but in practice, if you use a nonvalidating XML parser to process the source document, the parser isn't obliged to pass information to the XSLT processor about unparsed entities declared in the external subset of the DTD, and the unparsed-entity-uri() function is therefore likely to return a zero-length string. If this happens, try using a validating XML parser- assuming of course that the source document is valid.

Examples

Given the entity definition

  <!ENTITY weather-map SYSTEM "weather.jpeg" NDATA JPEG>

and the entity reference

  <FORECAST MAP="weather-map"/>

the following code will insert an <IMG> element into the HTML output.

  <xsl:template match="FORECAST">   <IMG HREF="{unparsed-entity-uri(@MAP)}"/>   </xsl:template>

unparsed-entity-uri