h1. Playframework Menu module

The Menu module is developed to enable Playframework application developer to quickly implement web navigation menu

h2. <a>Motivation</a>

It is a usual task for web developer to implement navigation menu. The idea of Menu module is to enable developer to quickly define menu structure and inject the menu using tag in the play groovy templates.

h2. <a>features</a>

* Define menu structure with yaml data file
* Provide easy to use menu tag to insert navigation menu to your web page
* Support current menu
* Support hierarchical structure
* Using label to group your menus

h2. TODO List

* Add javascript to support menu fold
* Add more CSS style
* Menu Configuration
* Add configuration to disable default menu model implementation

h2. <a>Dependencies</a>

* Although Play Menu module is developed on Play-1.1beta, I don't think there are any reason to prevent it be running on Play-1.0, except the sample application. The sample application demonstrate how you can implement your own Menu model besides using Menu module's built-in _Menu model. The user defined Menu model of the sample application use MongoDB to store the menu structure via <a href="http://www.playframework.org/modules/morphia">play-morphia</a> plugin.

h2. <a>Usage</a>

h3. <a>Configuration</a>

p. There is virtually no configuration needs except load the module into your application.conf file except you want to disable the default JPA Menu model implementation, in which case you want to add the following lines in your application.conf

bc.. menu.no_def_impl=true

h3. <a>Prepare _menu.yml file</a>

bc.. # Sample _menu.yml
 
_Menu(play):
    name: play
    url: /
    labels:
        - play
    
_Menu(doc):
    name: learn
    url: /doc
    title: play documentation
    parent: play
    labels:
        - play
        - doc
    
_Menu(com):
    name: community
    url: /community
    title: play community
    parent: play
    labels:
        - play
        - community
    
_Menu(code):
    name: code
    url: /code
    parent: play
    labels:
        - play
        - code
    
_Menu(module):
    name: modules
    url: /modules
    parent: play
    labels:
        - play
        - module
    
_Menu(akka):
    name: akka support
    url: /modules/akka
    parent: module
    labels:
        - play
        - module
    
_Menu(bespin):
    name: Bespin online editor
    url: /modules/bespin
    parent: module
    labels:
        - play
        - module
    
_Menu(user):
    name: Manage user
    url: /admin/users
    context: admin # context is deprecated, use labels instead
    labels:
        - play
        - admin

p. As you can find in the above sample _menu.yml file, each menu item can have five enties:
* name
* url
* title (optional)
* context (optional, could be used to partition your navigation menu depends on the context, e.g. admin)
* parent (optional, if no parent specified, then this entry is the top level menu)

h3. <a>Use menu tag in your template</a>

p. Basically you don't need to do anything else once you have created your _menu.yml file. Just make sure you have configured db in your application.conf file because the default menu implementation use JPA. Now you can easily insert menu in your groovy template file. For example:

bc.. <div id='navigation'>
   #{menu.menu /}
 </div>
 
p. That's it, easy, isn't? One important note, if you decide to use default _Menu model built-in the module (I guess 90% case you will use the built-in one), make sure *you delete the _Menus.java in menu/app/controllers directory*. That one is prepared in case you have your own IMenu model implementation, just as demonstrated in the sample app.

h3. <a>Create your own Menu model implementation</a>

p. It's possible that you will not be able to use the default Menu impl. One obvious reason is GAE does not support JPA. In the case, you need to implement your own IMenu in your models package. The demo application provides a Menu model implementation with mongodb, you can refer to it on how to implement your own Menu model. There are several notes need to be mentioned:

* Always implement your menu model using models.Menu as the package/class name. Otherwise you can't benefit from controllers._Menus which prepare renderArgs for menu.menu tag.
* Plugin will always load _menu.yml unless you disable it, i.e. menu.no_def_impl=true. You can choose to put your menu structure in that file, or (most probably) implement your own bootstrap load mechanism. In the demo app, there is a Bootstrap job created OnApplicationStart to load menu.yml file. The load process use Fixtures.load because Morphia Model support that. If you are using Model doesnot support Fixture.load, you are on your own to create and load your own intial data file or input the menu struture data in your db storage directly.

h3. <a>Define Context</a>

p. Context is deprecated, use label instead
p. Normally you won't touch renderArgs because the module is smart enough to determine your top menus and the current menu being selected. One common case you need to touch with the renderArgs is to define your context, for example, in the base controller of your administration controllers, you will probably have the following codes:

bc.. @Before
static void setMenuContext() {
    renderArgs.put("_menu_context", "admin");
}

h3. <a>Use label to group menu</a>

p. First you need to assign label(s) to menu items in your menu definition file "_menu.yml" if you use default implementation. Then you can define require menu.menu tag to display menus which are associated with specific label. You can do it in two ways:

bc.. /* apply label method 1: use controller to set the label */
@Before
static void setMenuLabel() {
    renderArgs.put("_menu_label", "play");
}

/* apply label method 2: assign label in your template file */
<div id="admin-menu">#{menu.menu menu_label: 'admin' /}</div>
<div id="user-menu">#{menu.menu menu_label: 'user' /></div>

p. Note: menu items labeled with '_global' will always get displayed unless '_menu_no_global' options set to true

h3. <a>Other RenderArgs</a>

* _menu_top_list: a list of IMenu object to be rendered in the web page
* _menu_current: url indicate the current menu


h2. <a>FAQ</a>

h3. Why do I get "models.Menu cannot be resolved" error when I start my play app?

p. You have not defined your own Menu model, please remove the {play.path}/modules/menu-xx/app/controllers/_Menus.java file.

h3. How to customize look&feel of the navigation menu rendered in my web page?

p. Refer to {play.path}/modules/menu-xx/public/stylesheets/_menu.css