Menus Plugin

Summary

Description

Menus Plugin

Description

The menus plugin allows for the creation, maintenance and display of a menu and its sub-menus (to an arbitrary depth) by defining option records in a database table. A breadcrumb trail is displayed on menu pages for moving back through the menu hierarchy and can also be placed on 'target' pages in your application. A 'return to the menu' button can also be placed on pages in your application to allow the end user to return to the menu system.

Installation

Execute the following from your application directory:

grails install-plugin menus

The system is internationalized using two message bundles: menus.properties and menuOptions.properties which are copied to the i18n directory of your application on installation/update of the plugin overwriting any files of the same name. The menu.properties file is used by the menus plugin itself. The menuOptions.properties file is for you to internationalize the texts of menus you create and contains instructions to that end. Also, a menu subdirectory is created in the views directory of your application and a display.gsp menu display page created there. You may tailor the display.gsp page to suit your own needs. A new image called menu.png is added to the web-app/images/skin directory of your application so that pages of your application can have a 'return to the menu' button displayed on them. A crumb.png image file is copied to the images directory of your application. Finally, the plugin creates a single database domain called Menu which is used to hold the options you create.

After installation of the plugin, the Menu table in your database should have a unique index on the 'menu_path' column and a non-unique index on the 'parent' column but, since Hibernate may or may not create these indices, you are advised to check that they exist otherwise performance may suffer.

Usage

The components of the plugin are in a package called org.grails.plugins.menus and any class that wishes to access the components directly must include the following:

import org.grails.plugins.menus.*

The menus plugin comes with a complete set of CRUD screens that assume you are using a layout called main. You define your menu structure using these screens and you may optionally internationalize your menu texts either using the menuOptions properties bundle or the database system if you have the localizations plugin installed.

Once you have your menu structure defined, you can display the menu using a URL such as http://myServer/myApp/menu/display.

To add a 'return to the menu' button to a page of your application, add the following line (split over multiple lines below only for formatting purposes here) to your GSP. The line would typically be added right after the equivalent definition of the 'home' button:

If you wish an application page to have a breadcrumb trail of the menu options selected rather (or possibly in addition to) a 'return to the menu' button described previously, then add the following line to your application GSP pages:

<div class="crumbs"><g:optionCrumbs/></div>

The display of the breadcrumbs will include the page of your application that was executed and, by default, this will be an active (clickable) link. If you would like it to be inactive (so that it does not re-display the page selected from the menu) then add an active="false" attribute to the <g:optionCrumbs/> tag. If you wish to change the image used to separate crumbs, use an attribute in the optionCrumbs tag such as image="/images/myImage.png".

The page that actually displays menus also uses a breadcrumb trail so that the user can move backwards through the menu hierarchy. Consequently, even if you do not intend to use breadcrumb trails on your own application pages, you would probably want to add lines similar to the following to your main.css style sheet in order to format the menu display page itself:

Since, using the standard Grails scaffolding structure, a user can jump from any page in an application to the home page (index.gsp in the web-app directory), it is a good idea to reset the menu system so that the next time the user goes to the menu display page, it is the main menu that will be displayed as opposed to any last sub-menu page they may have used. To do this, include the following tag in your index.gsp home page: <g:menuReset/>.

Compatibility

This plugin was written using Java version 1.6u18 and Grails version 1.3.0.

If you have the settings plugin and have defined pagination.max and/or pagination.default values, the menu maintenance 'list' screen will obey these settings. If you have the criteria plugin, the maintenance 'list' screen will allow the limitation of records to be displayed. If you have the help-balloons plugin, on-screen help will be available when creating/editing menu option records. Without the help-balloons plugin, you will need to read the help texts in the menus.properties file to understand what each field does. If you have the drilldowns and/or criteria plugins, the menu plugin will automatically perform a reset of those plugins whenever a user returns to a menu. If you have the localizations plugin installed, all translation of texts (both of the menus plugin itself and of the menu texts you create) will be done via the database rather than property bundles.