net.sf.click.extras.control
Class Menu

java.lang.Object
  net.sf.click.control.AbstractControl
      net.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