Migrating from 1.x

To upgrade from Struts Menu 1.x to Struts Menu 2.x, you need to change a few things:

  • Change the URI in your taglib declaration - we removed the "1.2" part. 
    <%@ taglib uri="http://struts-menu.sf.net/tag" prefix="menu" %>
  • Change the <plug-in> to use the new package name "net.sf.navigator." 
    <plug-in className="net.sf.navigator.menu.MenuPlugIn">
  • Change your menu-config.xml to use the new package name "net.sf.navigator." 
    <Displayer name="Simple"
  type="net.sf.navigator.displayer.SimpleMenuDisplayer"/>

Quick Start

Integrating Struts Menu into your application

Struts Menu can be easily integrated into your Struts application. Here are the steps you need to take to integrate this tag library.

Copy struts-menu.jar into your WEB-INF/lib directory. Add the plug-in settings to your struts-config.xml file. 

<plug-in className="net.sf.navigator.menu.MenuPlugIn">
  <set-property property="menuConfig" value="/WEB-INF/menu-config.xml"/> <!-- Default settings -->
</plug-in>

For Struts Menu 2.1+, you can put Jakarta's Standard Tag Library JAR in your WEB-INF/lib directory if you want to resolve EL expressions in menu-config.xml.

  1. You will need to declare your menu's attributes in a WEB-INF/menu-config.xml file. Here's a short snippet of what this might look like: 
    <Menu name="contactMenu" title="Contact" location="?Contact">
  <Item name="email" title="E-Mail" location="?EMail"/>
  <Item name="phone" title="Phone" location="?Phone"/>
</Menu>


    For a more thorough example, look in the sample app's web/WEB-INF directory for the menu-config file and trim it down to fit your needs. For a complete list of possible attributes, see the MenuBase class's javadocs.
  2. Add a taglib declaration to the top of your JSP: 
    <%@ taglib uri="http://struts-menu.sf.net/tag" prefix="menu" %>
  3. Add taglib code to render your menu in your JSP: 
    <menu:useMenuDisplayer name="TabbedMenu"
  bundle="org.apache.struts.action.MESSAGE">
  <menu:displayMenu name="Home"/>
  <menu:displayMenu name="About"/>
</menu:useMenuDisplayer>

The name="TabbedMenu" is defined in menu-config.xml towards the top: 

<Displayer name="TabbedMenu"
  type="net.sf.navigator.displayer.TabbedMenuDisplayer"/>

To use a customizeable Velocity template to render your menu, you will need to integrate Velocity into your webapp. To do this, perform the following steps:

  1. Make sure your menu-config.xml file has a "Velocity" displayer defined: 
    <Displayer name="Velocity" 
    type="net.sf.navigator.displayer.VelocityMenuDisplayer"/>
  2. Add Velocity JARs to your WEB-INF/lib directory. Download: velocity-1.4.jar and velocity-tools-view-1.0.jar.
  3. Change the displayer value to be "Velocity" in your JSP and the "config" attribute should point to a file (i.e. config="/templates/tabs.html") or config="tabs.html" if tabs.html is in your WEB-INF/classes directory.

There are many examples of using the Velocity displayer in the sample application as well as AppFuse. The example application will show you the CSS, JavaScript and image files you will need for each menu. Below are links to the Velocity templates currently available in Struts Menu.

All the relevant files you might need are available on this site:

For more information on hiding/displaying menu items based on roles, see the FAQs.

Using Struts Menu outside of Struts

In version 2.2+, the Menu Repository can now be loaded using a MenuContextListener:

<!--
   - Loads the menu-config.xml for struts-menu at startup,
   - by default from "/WEB-INF/menu-config.xml".
   - To override this, add a context-param named "menuConfigLocation"
   - web.xml file.
   -->
<listener>
    <listener-class>net.sf.navigator.menu.MenuContextListener</listener-class>
</listener>

Or if you're using Spring, it's even easier. Just add the following to your applicationContext.xml file:

<bean id="menu" class="net.sf.navigator.menu.MenuLoader">
  <property name="menuConfig" value="/WEB-INF/menu-config.xml"/> <-- default and optional -->
</bean>

Thanks to Dan Luputan for contributed code for the MenuLoader class.

Building from Source

To build this project from source, perform the following steps:

  1. Download and install Maven.
  2. Create a MAVEN_HOME environment variable that points to where you installed Maven. Then add $MAVEN_HOME/bin to your PATH.
  3. Navigate to the directory you've expanded the source to and execute "maven jar" to create target/struts-menu.jar.

To deploy the struts-menu example application, do the following:

  1. Download and install Tomcat.
  2. Create a CATALINA_HOME environment variable that points to where you installed Tomcat.
  3. Execute "maven deploy" to deploy the app to Tomcat.
  4. Open http://localhost:8080/struts-menu in your favorite browser

If you'd like to use Eclipse to build this project, see the Developer Guide Developer Guide.