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>