Playframework Menu module

What’s New in v1.1a

• Add Mongo menu implementation
• Automatically choose mongo implementation if Morphia or MongoDB plugin found
• IMenu.getContext() dropped, use IMenu.hasLabel() instead
• Support user define the yaml file name with “menu.yamlFile” configuration
• Always load menu from yaml file on application startup if “menu.loadFrom” is “yml”
• Support load all menus into memory if “menu.cache” is set to ‘true’
• Simplified menu yaml file

# previously
_Menu(home):
    name: home
    url: '@{Application.index()}'
# now
home:
    name: home
    url: '@{Application.index()}'

What’s New in v1.0c

• Support reverse url mapping. I.e. in your _menu.yml file you can define url as ‘@{Demo.index()}’

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

• 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

TODO List

• Add themes (js/css)

Dependencies

• 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 play-morphia plugin.

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
 
play:
    name: play
    url: /
    labels:
        - play
    
doc:
    name: learn
    url: /doc
    title: play documentation
    parent: play
    labels:
        - play
        - doc
    
com:
    name: community
    url: /community
    title: play community
    parent: play
    labels:
        - play
        - community
    
code:
    name: code
    url: /code
    parent: play
    labels:
        - play
        - code
    
module:
    name: modules
    url: /modules
    parent: play
    labels:
        - play
        - module
    
akka:
    name: akka support
    url: /modules/akka
    parent: module
    labels:
        - play
        - module
    
bespin:
    name: Bespin online editor
    url: /modules/bespin
    parent: module
    labels:
        - play
        - module
    
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:

• name
• url
• title (optional)
• labels (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)

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 (unless you have Morphia or MongoDB plugin enabled, in which case MongoMenu will be used). 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.

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

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

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:

• 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_defimpl=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.

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