Community contributed extensions

Playframework Menu module

What’s New in v1.0c * Support reverse url mapping

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

Motivation

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.

features

TODO List

Dependencies

Usage

Configuration

# Define menu default implementation class
# default is: models._Menu
menu.class=models.MyMenuImpl

Prepare _menu.yml file

you can define menu hierarchies in _menu.yml file (if you use default menu implementation), otherwise, you should define menu hierarchies in corresponding files loaded in your customized menu implementation “.loadMenu()” method. But the content of this file should be the same.

# 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

As you can find in the above sample _menu.yml file, each menu item can have five enties:

Start from v1.0c, you can use reverse URL mapping in menu yml file, e.g. url: ‘@{Application.index}’ will map to ‘/’. Note, you must use quotation mark “'” to use the reverse URL mapping style.

Use menu tag in your template

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:

<div id='navigation'>
   #{menu.menu /}
 </div>

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.

Create your own Menu model implementation

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:

Define Context

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:

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

Use label to group menu

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:

/* 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>

Note: menu items labeled with ‘_global’ will always get displayed unless ‘_menu_no_global’ options set to true

Other RenderArgs

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

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