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::
Link title
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::
Search
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.