Make URIs in the document absolute.
<p:declare-step type="p:make-absolute-uris"> <input port="source" primary="true" content-types="xml html" sequence="false"/> <output port="result" primary="true" content-types="xml html" sequence="false"/> <option name="match" as="xs:string" required="true"/> <option name="base-uri" as="xs:anyURI?" required="false" select="()"/> </p:declare-step>
The p:make-absolute-uris
step makes element and/or attribute values in the document appearing on the source
port absolute by applying a base
URI.
Ports:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The document to resolve the URIs in. |
|
|
|
|
| The resulting document. |
Options:
The p:make-absolute-uris
step takes the document appearing on its source
port and searches for elements and/or attributes as indicated by
the match
option. The values of these elements/attributes are taken as URIs and, if relative, resolved against a base URI as
specified in the base-uri
option. If there's no base-uri
option, the base URI of the element/attribute is
used.
Why is this useful? URIs in documents that are edited or received from the web are often relative. They point to other documents, for
instance images, that are elsewhere on disk or the web, in a location relative to the source document. For instance:
images/picture.jpg
. This allows for flexibility in the location of the documents. However, when processing these URIs and access
the referenced documents, the code needs to know how to resolve them into absolute ones. It is practical to arrange all this URI resolving in
advance, and this is what p:make-absolute-uris
is for.
There is an important thing to keep in mind when supplying a value for the base-uri
option:
When its value ends with a slash (/
), it points to a location. All URIs are resolved against that
location. For instance: file:///myapp/images/
When its value does not end with a slash, it points to a document. All URIs are resolved against the location of
this document. For instance, for a base-uri
value file:///myapp/images/logo.svg
, the URIs are resolved against the location
file:///myapp/images/
The Basic usage example shows this difference.
This example shows what happens to different kinds of URIs when resolved. The base-uri
value here points to a
location (because it ends with a /
).
Source document:
<URIs> <URI>image.jpg</URI> <URI>A/B/C/</URI> <URI>/image.jpg</URI> <URI>https://xprocref.org/index.html</URI> </URIs>
Pipeline document:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source"/> <p:output port="result"/> <p:make-absolute-uris match="URI" base-uri="file:///X/Y/Z/"/> </p:declare-step>
Result document:
<URIs> <URI>file:/…/…/image.jpg</URI> <URI>file:/…/…/file:/X/Y/Z/A/B/C/</URI> <URI>file:/…/…/image.jpg</URI> <URI>https://xprocref.org/index.html</URI> </URIs>
Just to show you the difference, this is what happens when you omit the final /
from the base-uri
option. Its
value, file:///X/Y/Z
, now points to a document called Z
. The URIs are resolved against the
location of this document.
Pipeline document:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source"/> <p:output port="result"/> <p:make-absolute-uris match="URI" base-uri="file:///X/Y/Z"/> </p:declare-step>
Result document:
<URIs> <URI>file:/…/…/image.jpg</URI> <URI>file:/…/…/file:/X/Y/A/B/C/</URI> <URI>file:/…/…/image.jpg</URI> <URI>https://xprocref.org/index.html</URI> </URIs>
p:make-absolute-uris
preserves all document-properties of the document(s) appearing on its source
port.
The match
option must match attributes or elements. If anything else is matched, error XC0023
is
raised.
A relative value for the base-uri
option is resolved against the base URI of the element on which this option is specified.
In most cases this will be the static base URI of your pipeline (the path where the XProc source containing the p:make-absolute-uris
is stored). This is very
probably not what you want.
If no base-uri
option is specified and an element/attribute matched has no base URI also, the result is
implementation-defined and therefore dependent on the XProc processor used.
This description of the p:make-absolute-uris
step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).
The formal specification for the p:make-absolute-uris
step can be found here.
The p:make-absolute-uris
step is part of categories:
The p:make-absolute-uris
step is also present in version:
3.0.