URL matching¶
Kiln provides a mechanism for generating full URLs to Kiln resources
based on the ID of a sitemap’s map:match
element. Since the actual
URL is specified only in the map:match/@pattern
, it can be changed
without breaking any generated links, provided the number and order of
wildcards in the @pattern
are not changed. If they are, then at
least it is easy to find all references to that map:match
by
searching the XSLT for its @id
.
To use this functionality, include the XSLT
cocoon://_internal/url/reverse.xsl
and call the
kiln:url-for-match
function, passing the ID of the map:match
to generate a URL for, a sequence containing any wildcard parameters
for that URL, and a Boolean indicating whether to force the URL to be
a cocoon://
URL. For example:
<a href="{kiln:url-for-match('local-tei-display-html', ($language, 'Had1.xml'), 0)}">
<xsl:text>Link title</xsl:text>
</a>
This generates a root-relative URL based on the @pattern
value of the
map:match
with the ID “local-tei-display-html”. If the identified
map:match
is part of a pipeline that is marked as
internal-only="true"
, the generated URL is a cocoon://
URL.
If no wildcard parameters are required, pass an empty sequence:
<a href="{kiln:url-for-match('local-search', (), 0)}">Search</a>
If the third argument is true (eg, 1), then regardless of whether the
pipeline the match belongs to is internal or not, the generated URL
will be a cocoon://
URL. This should be used when the generated
URL will be used for situations in which the URL is evaluated without
a webserver context, such as XIncludes.
Be sure to declare the kiln namespace
(http://www.kcl.ac.uk/artshums/depts/ddh/kiln/ns/1.0
), or else the
call will be treated as a plain string.
Warning
Neither Kiln nor Cocoon performs any checks that the
id
values you assign to map:match
elements are unique,
either within a single sitemap file or across multiple sitemaps. If
the same ID is used more than once, the first one (in sitemap
order) will be used by the url-for-match
template.
Warning
When developing in Kiln, be aware that all of the sitemap files must be well-formed XML, or this XSLT will not produce any results. This may lead to odd problems throughout the site that have no connection with the invalid sitemap.