Customizing Lenya navigation items

In order to understand customizing navigation items in Lenya, you'll need to understand where that's possible. In the default publication's root directory, you'll see a directory called 'lenya'. It's here where you can add folders and files that override the global defaults set aside for all of Lenya.

One of the directories is 'navigation'. In there, you'll most likely see a file called tabs.xsl. This is a customized version of the tabs just for the default publication. But you can do others. Here's the list of the file names you can add in the 'navigation' folder that will override the global files:

Understanding the site tree

The site tree is the place where all the "nodes", or pages in your publication are stored, preserving the hierarchy. The XML file can be found by going to the content/authoring/ directory in the default publication and viewing the sitetree.xml file. Let's take a look at a chunk:

            <site>
                <node id="index">
                    <label xml:lang="en">Home</label>
                    <label xml:lang="de">Home</label>
                </node>
            
                <node id="tutorial">
                    <label xml:lang="en">Tutorial</label>
                    <label xml:lang="de">Tutorial</label>
            
                        <node id="new_doctype">
                            <label xml:lang="en">Create new doctype</label>
                        </node>
                </node>
            </site>
        

The above tells us that each page is characterized by a <node> tag. Each <node> tag has an "id" attribute, which is the name of the document. So, if this publication's address were http://www.someplace.com/, then the ID for the second node would make the address to page http://www.someplace.com/tutorial.html.

Each node has an inner element called <label>. The label tag's contents are the navigation title for the page. It's the link to the page that you see in menu of the site. The xml:lang attribute signifies the language for this label, and as you can see, this site has multiple supported languages: "en" for English, and "de" for German.

Nodes can be inside other nodes. In the example above, the "new_doctype" node is inside the "tutorial" node. This means that the "tutorial" page is a parent of the "new_doctype" page, so they fall underneath each other like so:

 
            1. Home 
            2. Tutorial 
                a. Create new doctype
        

Order is also important - the order of the nodes in the sitetree file is the order in which the pages are displayed in the hierarchy of the site.

The nav: namespace

An XML namespace was created for users to grab these nodes with the appropriate information. So, for example, you can reference a node in your XSL using nav:node. Once you reference the node, you can reference it's label too: nav:label. There's some other items you can reference when you are pointing at a specific node:

Hiding navigation items can be helpful for situations like form submission/confirmation pages. You don't want the user to go to that page right away from within the site's menu, so you hide it, letting the programming of the form's input redirect the user to that page instead. Other examples abound.

Using your new-found knowledge

Let's try putting together a simple menu.xsl file that creates our own simple markup. The contents are below:

            <?xml version="1.0" encoding="UTF-8" ?>
            
            <xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:nav="http://apache.org/cocoon/lenya/navigation/1.0"
                xmlns="http://www.w3.org/1999/xhtml"
                exclude-result-prefixes="nav">
            
            <xsl:template match="nav:site">
            
                <ul>
            
                <!-- loop through all top-level items and return as list items -->
                <xsl:for-each select="/*/nav:node[@visibleinnav = 'true']">
                    <xsl:when test="@current = 'true'">
                        <li class="current"><a href="{@href}"><xsl:apply-templates select="nav:label"/></a></li>
                    </xsl:when>
                    <xsl:otherwise>
                        <li><a href="{@href}"><xsl:apply-templates select="nav:label"/></a></li>
                    </xsl:otherwise>
                </xsl:for-each>
            
                </ul>
            </xsl:template>
            
            <xsl:template match="nav:label">
                <xsl:value-of select="."/>
            </xsl:template>
            
            </xsl:stylesheet>
        

OK, so let's dissect this one. You always start with your XML prologue and stylesheet tags (notice how the root stylesheet tag references the nav namespace?). Then, one template is created to match the <site> tag - that's the root tag that wraps around all the <node> tags in our sitetree.xml file.

Give it a try

You now pretty much have the basics for putting together your own custom navigation. There are those that feel our methods for generating the menus are incorrect and that we should grab the nodes that we need in one fell swoop instead of looping through each one, but this was the only method we could find where wewould achieve the coding standards we wanted. Go experiment and have fun!