Navigation¶
Navigation structures (menu hierarchies and breadcrumbs) are defined
in XML files that accord to the Kiln menu schema (see
webapps/ROOT/assets/schema/menu/menu.rng
). These specify a
hierarchy of labels and their associated URLs (which may be external
to the Kiln site).
By default Kiln’s navigation is configured in the file
KILN_HOME/webapps/ROOT/assets/menu/main.xml
. It is possible to
have multiple menu files used in a single site, and even within a
single map:match
.
The structure of a menu is that of a list of items, with each item
being able to hold another list of items. However, it makes a
distinction between a kiln:menu
and a kiln:item
. The former
may or may not reference a resource, while the latter must. A
kiln:menu
may have children, while a kiln:item
may not.
It is important to understand that there is no necessary connection
between the position of a kiln:menu
or kiln:item
in the
hierarchy, and the URL it references. Specifically, the @href
of
an element, if it is not an absolute or root relative URL, is appended
to the ‘path’ of @root
values from its ancestors.
For example, given the following menu:
<root xmlns="http://www.kcl.ac.uk/artshums/depts/ddh/kiln/ns/1.0">
<menu href="text/" label="Texts">
<item href="intro.html" label="Introduction" />
<menu label="Reports" root="text/reports">
<item href="1.html" label="Report #1" />
</menu>
</menu>
</root>
The “Texts” item links to text/
, “Introduction” links to
intro.html
(not text/intro.html
), and “Report #1” links to
text/reports/1.html
. “Reports” is not a link at all.
Requiring explicit @root
values in order to provide a link
hierarchy allows for a hierarchical menu to map on to a less or
differently organised underlying URL structure.
The simpler form of the above example menu, with everything in a nice hierarchy, is:
<root xmlns="http://www.kcl.ac.uk/artshums/depts/ddh/kiln/ns/1.0">
<menu href="" label="Texts" root="text">
<item href="intro.html" label="Introduction" />
<menu label="Reports" root="reports">
<item href="1.html" label="Report #1" />
</menu>
</menu>
</root>
Note that there is no requirement to pin any @href
or @root
to
a root URL (/
). This will be handled automatically by the menu
processor. That includes, whether or not the references are root
relative or not, adjusting the URLs if Kiln is mounted at a URL other
than /
.
If a constructed URL is meant to reference the same server, but to a
path outside of Kiln’s context, start the @href
or @root
with
“//”.
Using kiln:url-for-match¶
Rather than explicitly specifying URLs via the @root
and @href
attributes, the kiln:url-for-match
function can be indirectly used
in a menu. Specify the id of the map:match
used to process the URL
in a kiln:menu
or kiln:item
’s @match
attribute, and if
any parameters are required they can be specified (whitespace
delimited) in the @params
attribute. For example:
<root xmlns="http://www.kcl.ac.uk/artshums/depts/ddh/kiln/ns/1.0">
<menu label="Texts" match="texts-home">
<item match="texts-intro" label="Introduction" />
<menu label="Reports">
<item label="Report #1" match="texts-report" params="1" />
</menu>
</menu>
</root>
This method is greatly preferable to using @href
for links within
Kiln.
Marking the active item¶
The menu XML that is returned by cocoon://_internal/menu/**.xml
can have a menu item matching a supplied URL marked as active. This is
useful for display a menu with the item that matches the current
position in the navigation structure highlighted.
To achieve this, supply a querystring to the Cocoon URL with a url
parameter containing the URL to mark as active:
<map:match pattern="*/text/**/*.html">
<map:aggregate element="aggregation">
<map:part label="tei" src="cocoon://internal/tei/preprocess/{2}.xml" />
<map:part src="cocoon://_internal/menu/{1}/main.xml?url={1}/text/{2}/{3}.html" />
</map:aggregate>
...
</map:match>
The appropriate li
element will be annotated with a class
attribute with the value “active”.
The supplied URL should be root relative, but without the initial “/”, as in the example above.
Note that it does not matter what the URL of the request is; the menu uses only the URL explicitly passed to it. This allows for the same menu item to be marked as active for a multitude of URLs.
Translation and switching languages¶
To supply a key for looking up the translation of a menu item’s label,
add an i18n:key
attribute to the item; translated strings are
supplied as usual in assets/translations/messages_<language
code>.xml
.
Menu items, by default, link within the current language context. In
order to have menu items that switch language context (ie, to point to
a URL with a different language code as the first part of the path),
supply a language
attribute to the menu item, whose value is the
language code the link should point to:
<item label="Recherche" language="fr" match="local-search" />
To link to the same URL only with a different language, use the
language_switch
attribute to specify the new language code:
<item label="English" language_switch="en" />
For linking to non-public URLs that do not have a language parameter (such as admin URLs), supply an empty language attribute.
For menus that are used in no language context (such as the admin’s
menu), the map:match
should reference the menu pipeline that takes
no language code:
<map:match pattern="admin/*.html">
<map:aggregate element="aggregation">
<map:part src="cocoon://_internal/menu/admin.xml?url=admin/{1}.html" />
</map:aggregate>
...
</map:match>