This document is work in progress.

This document is not complete yet, and many parts of the code explained has not been implemented yet. To discuss the content of this subsystem, please use general@lists.ops4j.org mailing list.

Overview

Pax Wicket Menus is a subsystem that simplifies the creation of menus in Pax Wicket.

Menus are created by the main application in Pax Wicket, i.e. the bundle that owns the PaxWicketApplicationFactory. But the content of the Menus are potentially contributed by bundles that the owner bundle doesn't know about. The Menu becomes a kind of extension point, and it is defined by an applicationName, menuId and menu groups.

In practical terms, the contributing bundle will register each MenuItem as an OSGi service and each Menu instance will track for the MenuItems with the rigth applicationName and menuId.

By creating a MenuItem and announce that MenuItem into the OSGi Framework, the corresponding Menu instances will be populated by the registered MenuItem.

MenuItem consists of

Application Name (required)
Caption (required)
PageLink (optional)
Action (optional)
Image (optional)
Classifier
Group Identifier
Identifier

MenuItem functionality

Caption

All MenuItem instances must have a Caption. Even if the Caption is not shown for normal graphical browser, it must exist for text based browsers and the ALT attribute in links.

Link

The Link is optional and the primary way to navigate. Assign a PageLink instance to the Link of the MenuItem to create a menu item that brings up a new page.

Action

Action exist to delegate the action of the menu click back to the server. Implement the onClick method of the abstract MenuAction class to do your stuff.

Image

The MenuItem can have a Image associated to it. If there is both an Action and a Caption defined both will be wrapped with the Link (if any) and the Image will be created in front of the Caption by default. Call setAlignment( Alignment.after ) to render the Image after the

Classifiers

You can optionally define a classifier. This string will be assigned to the CLASS attribute of the element in the menu. If you create the menu item with a classifier helicopter then the rendered MenuItem HTML element will have a

<span CLASS="helicopter">

.

Group Identifier

Usages of MenuItem

Caption + Link

This is probably the simplest case.

PageLink link = new PageLink( "item", ProductsPage.class ); 
    MenuItem item = new MenuItem( "MyApplication", "Products" );
    item.setLink( link );
    item.attachTo( "MainMenu" )

All PageLinks must have a ID that is item.

Caption + Action

If you want the server to be called when the MenuItem is clicked, you need to define a callback instead.

MenuAction action = new MenuAction()
    {
        public void onClick( Page page, Menu menu, MenuItem item )
        {
            // Do your stuff here.
        }
    };
    MenuItem item = new MenuItem( "MyApplication", "Products" );
    item.setAction( action );
    item.attachTo( "MainMenu" )

Menu functionality

The Menu has a default implementation, but typically one wants a special generated menu, in which case you create a subclass of Menu and a HTML template for that. The Menu will detect all MenuItem instances that are attched to the Menu with the given name.

Menu Usage

Typical usage of a Menu would be to;

MyPage.java

public class MyPage extends WebPage
{
    public MyPage()
    {
        Menu menu = new MyMenu( "MainMenu" );
// NOT DONE!!!
    }
}

MyPage.html

<html>
<body>
<div wicket:id="MainMenu" >Menu Panel will go here</div>
</body>
</html>

MyMenu.java

public class MyMenu extends Menu
{
    public MyMenu( String application, String menuName )
    {
        super( application, menuName );
    }
   // NOT DONE!!
}

MyMenu.html

<html>
<wicket:panel>
<div class="menu">
<ul>
  <li wicket:id="item">Menu item here</li>
</ul>
</div>
</wicket:panel
</html>

Classes

MenuItem

MenuItem.java

package org.ops4j.pax.wicket.toolkit.menu;

import wicket.markup.html.image.Image;
import wicket.markup.html.link.PageLink;

public class MenuItem
{
    public MenuItem( String applicationName, String menuId, String caption );

    public String getCaption();

    public void setCaption( String caption );

    public PageLink getLink();

    public void setLink( PageLink link );

    public MenuAction getAction();

    public void setAction( MenuAction action );

    public String getClassifier();

    public void setClassifier( String classifier );

    public String getIdentifier();

    public void setIdentifier( String identifier );

    public Image getImage();

    public void setImage( Image image );

    public Alignment getAlignment();

    public void setAlignment( Alignment alignment );

    public boolean isVisible();

    public void setVisible( boolean visible );

    public final void register();

    public final void unregister();

    protected void onRegister();

    protected void onUnregister();
}

MenuGroup

MenuGroup.java

package org.ops4j.pax.wicket.toolkit.menu;

public class MenuGroup extends MenuItem
{
    public MenuGroup( String groupId );

}

MenuAction

package org.ops4j.pax.wicket.toolkit.menu;

import org.ops4j.pax.wicket.service.Page;

public abstract class MenuAction
{
    public abstract void onClick( PageContent page, Menu menu, MenuItem item );
}

Alignment

public enum Alignment 
{ 
    before, after
}

Labels