Open Source Network Blog

Jisse Reitsma

Jisse Reitsma is co-founder of Jira ICT, wrote a book on Joomla! Templates, teaches many courses and programs in Joomla!, Magento and Drupal. Authors profile

Joomla! 1.5 ships with splitmenu functionality, which allows you to display a multi-level menu-hierarchy with different menu-modules. This allows for advanced menu-structures based on just a single menu tree. Splitmenu is based on the Menu Module-parameters startlevel and endlevel. There are some shortcomings though in this functionality. In this tutorial we will overcome these problems by writing our own better version of splitmenu.

Shortcomings of Joomla! splitmenu

The Joomla! 1.5 splitmenu functionality has some shortcomings. For instance, the whole functionality should be part of the template, because it deals with the presentation of the site. But instead you need to know a great deal of Joomla! Administration, before you can implement this feature on your site. Many template manufacturors overcome this problem by shipping their own splitmenu-functionality in their template. This tutorial explains how, but improves the methods seen by the author so far.

Another example: The title of the submenu is always static. Let's say you have a top-menu with the items Home, Products and Company. If you click on Products the submenu appears on the left-side, but it has to have a title like Submenu or something else you have configured for this menu-module, while you ofcourse expect the title to be Products. Again, this tutorial will show you how to overcome this problem.

Moving from <jdoc> to PHP

The code in this tutorial could be placed in your template. It will produce the HTML of a menu, so this allows you to migrate from the <jdoc> tag to PHP-code. Take for instance the following example:

<jdoc:include type="modules" name="top" style="xhtml" />

We will assume that the only reason for this position "top" is to allow a menu-module to be configured at this spot. It is a horizontal menu with about four or five menu-items, and is based on a <div> tag (that's why the "style" is set to "xhtml"). The menu-module needs to be configured to have a startlevel of 0 and an endlevel of 1. This means it will only include the uppermost menu-items. As menu-name we choose globalmenu which is our main menu-structure (but it could also be mainmenu).

Now let's put together the PHP-code. First of all we are going to include some code at the top of the template, just after the _JEXEC check.

<?php
defined( '_JEXEC' ) or die( "Please die" );
$document = &JFactory::getDocument();
$renderer = $document->loadRenderer( 'module' );

$topmenu_module = JModuleHelper::getModule( 'mod_mainmenu' );
$topmenu_module->params = "menutype=globalmenu\n"
    . "startLevel=0\n"
    . "endLevel=1";
$options = array( 'style' => "raw" );
$topmenu = $renderer->render( $topmenu_module, $options );
?>

The menu was initialized through a new module-instance $topmenu_module, which received the proper parameters startLevel and endLevel. This module-instance is parsed through a renderer to create HTML-output. The $topmenu now contains the HTML-structure of the menu.

Now we can replace our <jdoc>-tag with the following code:

<div class="module"><?php echo $topmenu; ?></div>

You can test the output in your template. It should show you the contents of your globalmenu menu.

Creating the submenu

The submenu is created in almost the same way. We initialize a module-instance $submenu_module, give it the proper parameters and render it. Note that the startLevel and endLevel change:

$submenu_module = JModuleHelper::getModule( 'mod_mainmenu' );
$submenu_module->params = "menutype=globalmenu\n"
    . "startLevel=1\n"
    . "endLevel=9";
$options = array( 'style' => "raw" );
$submenu = $renderer->render( $submenu_module, $options );

And to output the HTML:

<div class="module">
    <h3>Submenu</h3>
    <?php echo $submenu; ?>
</div>

We could also simulate a "rounded" style by including more <div> tags:

<div class="module"><div><div><div>
    <h3>Submenu</h3>
    <?php echo $submenu; ?>
</div></div></div></div>

Changing the submenu title dynamically

What you can see in the HTML-block of our submenu, is that it has a <h3> tag (which is fine) but includes a static title (which is not fine). We need some extra PHP-code to generate a dynamic title. We assume here that because the topmenu and submenu are derived from the same menu-tree, we need to fetch the item from the topmenu which is now active.

$menu = JSite::getMenu();
$active_item = $menu->getActive();
$parent_id = $active_item->tree[0];
$parent_item = $menu->getItem($parent_id);
$submenu_title = $parent_item->name;

Instead of these lines we can also write the following on one line - assuming we run PHP5:

$submenu_title = JSite::getMenu()->
getItem(JSite::getMenu()->getActive()->tree[0])->name;

But probably it does not make it easier to understand.

The final step is to replace the static title with our dynamic variable.

<div class="module"><div><div><div>
    <h3><?php echo $submenu_title; ?></h3>
    <?php echo $submenu; ?>
</div></div></div></div>

And there we have our complete splitmenu functionality. It doesn't require us to rewrite the full mod_mainmenu functionality, while it gives us much more flexibility when building custom templates.