net.sf.click.extras.control
Class Menu

java.lang.Object
  extended bynet.sf.click.control.AbstractControl
      extended bynet.sf.click.extras.control.Menu
All Implemented Interfaces:
Control, Serializable

public class Menu
extends AbstractControl

Provides a hierarchical Menu control.

Application menus are defined using a /WEB-INF configuration file located under the /WEB-INF directory or the root classpath. An example Menu configuration files is provided below.
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <menu>
    <menu label="Home" path="user/home.htm" roles="tomcat, role1"/>
    <menu label="User" path="user/home.htm" roles="tomcat, role1">
        <menu label="User Page 1" path="user/user-1.htm" roles="tomcat, role1"/>
        <menu label="User Page 2" path="user/user-2.htm" roles="tomcat, role1"/>
    </menu>
    <menu label="Admin" path="admin/admin-1.htm" roles="role1">
        <menu label="Admin Page 1" path="admin/admin-1.htm" roles="tomcat, role1"/>
        <menu label="Admin Page 2" path="admin/admin-2.htm" roles="tomcat, role1"/>
    </menu>
 </menu> 
To include the root menu item in your page, simply use the default Menu constructor:
 public class MenuPage extends Page {

     public Menu rootMenu = Menu.getRootMenu();

     public ActionLink logoutLink = new ActionLink(this, "onLogoutClick");

 } 
To render the configured Menu hierarchy you will need to use a Velocity #macro or Velocity code in your page. For example:
 #writeMenu($rootMenu) 
An example menu Velocity macro is provided below:
 #macro( writeMenu $rootMenu )

 <table id="menuTable" border="0" width="100%" cellspacing="0" cellpadding="0" style="margin-top: 2px;">
  <tr>
   <td>

 <div id="searchbar">
 <div class="menustyle" id="menu">
   <ul class="menubar" id="dmenu">
     #foreach ($topMenu in $rootMenu.children)
       #if ($topMenu.isUserInRoles() || $topMenu.isUserInChildMenuRoles())
         #if ($topMenu.children.empty)
           <li class="topitem">$topMenu</li>
         #else
           <li class="topitem">$topMenu
             <ul class="submenu"
             #foreach ($subMenu in $topMenu.children)
               #if ($subMenu.isUserInRoles())
                 ><li>$subMenu</li
               #end
             #end
             ></ul>
           </li>
         #end
       #end
     #end
     #if ($request.remoteUser)
         <li class="topitem"><a href="$logoutLink.href">Logout</a></li>
     #end
   </ul>
  </div>
 </div>

   </td>
  </tr>
 </table>

 #end 
This example uses J2EE role path based security to only display the menu items the user is authorized to see. If you not using this security feature in your application you should remove the macro isUserInRoles() checks so the menu items will be rendered.

Note individual menu items will render themselves as simple anchor tags using their toString() method. For more fine grain control you should extend your Velocity macro to render individual menu items.

Security

Menus support J2EE role based security via the isUserInRoles() method. When creating secure menus define the valid roles in the menu items. For example:
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <menu>
    <menu label="Home" path="user/home.htm" roles="user,admin">
       <menu label="Home" path="user/home.htm" roles="user,admin"/>
       <menu label="Search" path="user/search.htm" roles="user,admin"/>
    </menu>
    <menu label="Admin" path="admin/admin.htm">
       <menu label="Home" path="admin/admin.htm" roles="admin"/>
    </menu>
 </menu> 

Menu Configuration DTD

The Menu config file DTD is provided below:
 <!-- The Menu (menu.xml) Document Type Definition. -->
 <!ELEMENT menu (menu*)>
     <!ATTLIST menu label CDATA #IMPLIED>
     <!ATTLIST menu path CDATA #IMPLIED>
     <!ATTLIST menu target CDATA #IMPLIED>
     <!ATTLIST menu title CDATA #IMPLIED>
     <!ATTLIST menu imageSrc CDATA #IMPLIED>
     <!ATTLIST menu external (true|false) "false">
     <!ATTLIST menu separator (true|false) "false">
     <!ATTLIST menu roles CDATA #IMPLIED>
     <!ATTLIST menu pages CDATA #IMPLIED> 

Author:
Malcolm Edgar
See Also:
Serialized Form

Field Summary
protected  AccessController accessController
          The menu security access controller.
protected  List children
          The list of submenu items.
protected static String DEFAULT_CONFIG_FILE
          The menu configuration filename:   "/WEB-INF/menu.xml".
protected  boolean external
          The menu path is to an external page flag, by default this value is false.
static String HTML_IMPORTS
          The HTML imports statements.
protected  String imageSrc
          The image src path attribute.
protected  String label
          The menu display label.
protected  List pages
          The list of valid page paths.
protected  String path
          The menu path.
protected  List roles
          The list of valid role names.
protected static Menu rootMenu
          The cached root Menu as defined in menu.xml.
protected  boolean separator
          The menu separator flag.
protected  String target
          The target attribute.
protected  String title
          The tooltip title attribute.
 
Fields inherited from class net.sf.click.control.AbstractControl
actionListener, attributes, listener, listenerMethod, messages, name, parent, styles
 
Fields inherited from interface net.sf.click.Control
CONTROL_MESSAGES
 
Constructor Summary
  Menu()
          Create a new Menu instance.
protected Menu(Element menuElement, AccessController accessController)
          Create a Menu from the given menu-item XML Element.
  Menu(String name)
          Create a new Menu instance with the given name.
 
Method Summary
 AccessController getAccessController()
          Return the menu access controller.
 List getChildren()
          Return list of of submenu items.
 String getHref()
          Return the menu anchor HREF attribute.
 String getHtmlImports()
          Return the HTML head import statements for the CSS stylesheet (click/menu.css) and JavaScript (click/extras-control.js) files.
 String getId()
          This method returns null.
 String getImageSrc()
          Return the image src path attribute.
 String getLabel()
          Return the label of the Menu item.
 List getPages()
          Return the list of valid Page paths for the Menu item.
 String getPath()
          Return the path of the Menu item.
 List getRoles()
          Return the list of valid roles for the Menu item.
static Menu getRootMenu()
          Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, and which uses JEE Role Based Access Control (RBAController).
static Menu getRootMenu(AccessController accessController)
          Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, and which uses the provided AccessController.
 Menu getSelectedChild()
          Return the selected child menu, or null if no child menu is selected.
 String getTarget()
          Return the target attribute of the Menu item.
 String getTitle()
          Return the title attribute of the Menu item.
 boolean isExternal()
          Return true if the menu path refers to an external resource.
 boolean isSelected()
          Return true if the Menu item is selected.
 boolean isSeparator()
          Return true if the Menu item is a separator.
 boolean isUserInChildMenuRoles()
          Return true if any child menus have the user in one of their menu roles.
 boolean isUserInRoles()
          Return true if the user is in one of the menu roles, or if any child menus have the user in one of their menu roles.
protected static Menu loadRootMenu(AccessController accessController)
          Return a copy of the Applications root Menu as defined in the configuration file "/WEB-INF/menu.xml", with the Control name "rootMenu".
 void onDeploy(ServletContext servletContext)
          Deploy the menu.css and menu.js files to the click web directory when the application is initialized.
 void onDestroy()
          This sets the parent to be null.
 void render(HtmlStringBuffer buffer)
          Render the HTML representation of the Menu.
 void setAccessController(AccessController accessController)
          Set the menu access controller.
 void setExternal(boolean value)
          Set whether the menu path refers to an external resource.
 void setImageSrc(String src)
          Set the image src path attribute.
 void setLabel(String label)
          Set the label of the Menu item.
 void setListener(Object listener, String method)
          This method does nothing.
 void setPages(List pages)
          Set the list of valid Page paths.
 void setPath(String path)
          Set the path of the Menu item.
 void setRoles(List roles)
          Set the list of valid roles for the Menu item.
 void setSeparator(boolean separator)
          Set whether the Menu item is a separator.
 void setTarget(String target)
          Set the target attribute of the Menu item.
 void setTitle(String title)
          Set the title attribute of the Menu item.
 String toString()
          Return an HTML anchor tag representation of the menu item.
 
Methods inherited from class net.sf.click.control.AbstractControl
addStyleClass, appendAttributes, getActionListener, getAttribute, getAttributes, getContext, getControlSizeEst, getMessage, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, getTag, hasAttribute, hasAttributes, hasStyles, onInit, onProcess, onRender, registerActionEvent, removeStyleClass, renderTagBegin, renderTagEnd, setActionListener, setAttribute, setId, setName, setParent, setStyle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_CONFIG_FILE

protected static final String DEFAULT_CONFIG_FILE
The menu configuration filename:   "/WEB-INF/menu.xml".

See Also:
Constant Field Values

HTML_IMPORTS

public static final String HTML_IMPORTS
The HTML imports statements.

See Also:
Constant Field Values

rootMenu

protected static Menu rootMenu
The cached root Menu as defined in menu.xml.


accessController

protected AccessController accessController
The menu security access controller.


children

protected List children
The list of submenu items.


external

protected boolean external
The menu path is to an external page flag, by default this value is false.


imageSrc

protected String imageSrc
The image src path attribute. If the image src is defined then a <img/> element will rendered inside the link when using the Menu toString() method.

If the image src value is prefixed with '/' then the request context path will be prefixed to the src value when rendered by the control.


label

protected String label
The menu display label.


pages

protected List pages
The list of valid page paths. If any of these page paths match the current request then the Menu item will be selected.


path

protected String path
The menu path.


roles

protected List roles
The list of valid role names.


separator

protected boolean separator
The menu separator flag.


target

protected String target
The target attribute.


title

protected String title
The tooltip title attribute.

Constructor Detail

Menu

public Menu()
Create a new Menu instance.


Menu

public Menu(String name)
Create a new Menu instance with the given name.

Parameters:
name - the name of the menu

Menu

protected Menu(Element menuElement,
               AccessController accessController)
Create a Menu from the given menu-item XML Element.

Parameters:
menuElement - the menu-item XML Element
accessController - the menu access controller
Method Detail

getRootMenu

public static Menu getRootMenu()
Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, and which uses JEE Role Based Access Control (RBAController).

Returns:
the root menu item defined in the WEB-INF/menu.xml file or menu.xml in the root classpath
See Also:
RoleAccessController

getRootMenu

public static Menu getRootMenu(AccessController accessController)
Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, and which uses the provided AccessController.

Parameters:
accessController - the menu access controller
Returns:
the root menu item defined in the WEB-INF/menu.xml file or menu.xml in the root classpath

getAccessController

public AccessController getAccessController()
Return the menu access controller.

Returns:
the menu access controller

setAccessController

public void setAccessController(AccessController accessController)
Set the menu access controller.

Parameters:
accessController - the menu access controller

getChildren

public List getChildren()
Return list of of submenu items.

Returns:
the list of submenu items

isExternal

public boolean isExternal()
Return true if the menu path refers to an external resource.

Returns:
true if the menu path refers to an external resource

setExternal

public void setExternal(boolean value)
Set whether the menu path refers to an external resource.

Parameters:
value - the flag as to whether the menu path refers to an external resource

getImageSrc

public String getImageSrc()
Return the image src path attribute. If the image src is defined then a <img/> element will rendered inside the link when using the Menu toString() method.

If the src value is prefixed with '/' then the request context path will be prefixed to the src value when rendered by the control.

Returns:
the image src path attribute

setImageSrc

public void setImageSrc(String src)
Set the image src path attribute. If the src value is prefixed with '/' then the request context path will be prefixed to the src value when rendered by the control.

Parameters:
src - the image src path attribute

getLabel

public String getLabel()
Return the label of the Menu item.

Returns:
the label of the Menu item

setLabel

public void setLabel(String label)
Set the label of the Menu item.

Parameters:
label - the label of the Menu item

getPages

public List getPages()
Return the list of valid Page paths for the Menu item. If any of these page paths match the current request then the Menu item will be selected.

Returns:
the list of valid Page paths

setPages

public void setPages(List pages)
Set the list of valid Page paths. If any of these page paths match the current request then the Menu item will be selected.

Parameters:
pages - the list of valid Page paths

getPath

public String getPath()
Return the path of the Menu item.

Returns:
the path of the Menu item

setPath

public void setPath(String path)
Set the path of the Menu item.

Parameters:
path - the path of the Menu item

getRoles

public List getRoles()
Return the list of valid roles for the Menu item.

Returns:
the list of valid roles for the Menu item

setRoles

public void setRoles(List roles)
Set the list of valid roles for the Menu item.

Parameters:
roles - the list of valid roles for the Menu item

isSelected

public boolean isSelected()
Return true if the Menu item is selected.

Returns:
true if the Menu item is selected

isSeparator

public boolean isSeparator()
Return true if the Menu item is a separator.

Returns:
true if the Menu item is a separator

setSeparator

public void setSeparator(boolean separator)
Set whether the Menu item is a separator.

Parameters:
separator - the flag indicating whether the Menu item is a separator

isUserInRoles

public boolean isUserInRoles()
Return true if the user is in one of the menu roles, or if any child menus have the user in one of their menu roles. Otherwise the method will return false.

This method internally uses the HttpServletRequest function isUserInRole(rolename), where the rolenames are derived from the getRoles() property.

Returns:
true if the user is in one of the menu roles, or false otherwise

isUserInChildMenuRoles

public boolean isUserInChildMenuRoles()
Return true if any child menus have the user in one of their menu roles. Otherwise the method will return false.

This method internally uses the HttpServletRequest function isUserInRole(rolename), where the rolenames are derived from the getRoles() property.

Returns:
true if the user is in one of the child menu roles, or false otherwise

getTarget

public String getTarget()
Return the target attribute of the Menu item.

Returns:
the target attribute of the Menu item

setTarget

public void setTarget(String target)
Set the target attribute of the Menu item.

Parameters:
target - the target attribute of the Menu item

getTitle

public String getTitle()
Return the title attribute of the Menu item.

Returns:
the title attribute of the Menu item

setTitle

public void setTitle(String title)
Set the title attribute of the Menu item.

Parameters:
title - the title attribute of the Menu item

getHtmlImports

public String getHtmlImports()
Return the HTML head import statements for the CSS stylesheet (click/menu.css) and JavaScript (click/extras-control.js) files.

Returns:
the HTML head import statements for the control stylesheet and JavaScript files
See Also:
Control.getHtmlImports()

getHref

public String getHref()
Return the menu anchor HREF attribute. If the menu is referring to an external path, this method will simply return the path, otherwise it will return the menu path prefixed with the request context path.

If the path refers to a hash "#" symbol, this method will return a "#". It is useful to assign a "#" to the path of a menu item containing children, because most modern browsers will not submit the page if clicked on.

Returns:
the menu anchor HREF attribute

getId

public String getId()
This method returns null.

Returns:
null
See Also:
Control.getId()

setListener

public void setListener(Object listener,
                        String method)
This method does nothing.

Parameters:
listener - the listener object with the named method to invoke
method - the name of the method to invoke
See Also:
Control.setListener(Object, String)

onDeploy

public void onDeploy(ServletContext servletContext)
Deploy the menu.css and menu.js files to the click web directory when the application is initialized.

Parameters:
servletContext - the servlet context
See Also:
Control.onDeploy(ServletContext)

onDestroy

public void onDestroy()
This sets the parent to be null.

See Also:
Control.onDestroy()

render

public void render(HtmlStringBuffer buffer)
Render the HTML representation of the Menu.

Parameters:
buffer - the specified buffer to render the control's output to
See Also:
toString()

toString

public String toString()
Return an HTML anchor tag representation of the menu item. If the menu is a separator this method will return a HR tag <hr/>.

Note for more fine grained rendering control you should use a Velocity #macro to render the menu item.

Returns:
an HTML anchor tag representation of the menu item
See Also:
Object.toString()

getSelectedChild

public Menu getSelectedChild()
Return the selected child menu, or null if no child menu is selected.

Returns:
the selected child menu

loadRootMenu

protected static Menu loadRootMenu(AccessController accessController)
Return a copy of the Applications root Menu as defined in the configuration file "/WEB-INF/menu.xml", with the Control name "rootMenu".

The returned root menu is always selected.

Parameters:
accessController - the menu access controller
Returns:
a copy of the application's root Menu