Navigation plugin
Dependency:
compile "org.grails.plugins:navigation:1.3.2"
Summary
Provides convention-based navigation data for your UI and tags for rendering the navigation menus.
Description
This plugin is DEPRECATED. This documentation is left here for users who have used it to date. If you are not already using this and looking for navigation menu handling, please consider using the Platform Core plugin's Navigation API. Same author, but 3-4 years' more experience later, and much better docs.This plugin implements simple menu navigation in your application using convention - your controllers and actions are mapped into the navigation structure - with default rendering like this:

- Render menus or tabs, with control over the rendering and CSS styling
- Indicate which controllers and actions should appear in menus
- Declare and render sub-items of a top-level item
- Explicitly add non-convention based menu items for the "20% case"
- Have as many navigation groups (each is a 2-level menu) as you like
Installation
Just run:grails install-plugin navigation
Getting started
Once installed into your application, simply edit any controllers that you would like to appear in the navigation and add a "navigation" static property, like this:class DashboardController { static navigation = true def index = { } }
<html>
<head><nav:resources/></head>
<body>
<div id="menu">
<nav:render/>
</div>
<g:layoutBody/>
</body>
</html>
class DashboardController { static navigation = [
group:'tabs',
order:10,
title:'Your Inbox',
action:'inbox'
] def index = { } def inbox = { [items:Inbox.findAllByUser(user)]}
}
class SettingsController { static navigation = [
group:'tabs',
order:100,
title:'Account',
action:'billing'
] def index = { } def billing = { }
}
<html> <head><nav:resources/></head> <body> <div id="menu"> <nav:render group="tabs"/> </div> <g:layoutBody/> </body> </html>
class AuthController { static navigation = [ [group:'userOptions', action:'login', order: 0, isVisible: { session.user == null }], [action:'logout', order: 99, isVisible: { session.user != null }], [action:'profile', order: 1, isVisible: { session.user != null }] ] def login = { } def logout = { } def profile = { } }
<html> <head><nav:resources/></head> <body> <div id="user"> // You might use CSS to, say, right-align this <nav:render group="userOptions"/> </div> <div id="menu"> <nav:render group="tabs"/> </div> <g:layoutBody/> </body> </html>
class DashboardController { static navigation = [ group:'tabs', order:10, title:'Your Inbox', action:'newInbox', subItems: ['newInbox', 'archive'] ] def index = { newInbox() } def newInbox = { [items:Inbox.findAllByUserAndArchive(user, false)]} def archive = { [items:Inbox.findAllByUserAndArchive(user, true)]} }
<html> <head><nav:resources/></head> <body> <div id="user"> // You might use CSS to, say, right-align this <nav:render group="userOptions"/> </div> <div id="menu"> <nav:render group="tabs"/><br/> <nav:renderSubItems group="tabs"/> </div> <g:layoutBody/> </body> </html>
class DashboardController { static navigation = [ group:'tabs', order:10, title:'Your Inbox', action:'newInbox', subItems: [ [action:'newInbox', order:1, title:"Inbox"], [action:'archive', order:10, title:'Old items'] ] ] def index = { newInbox() } def newInbox = { [items:Inbox.findAllByUserAndArchive(user, false)]} def archive = { [items:Inbox.findAllByUserAndArchive(user, true)]} }
navigation.tabs.inbox=Your Inbox
navigation.tabs.inbox=Your Inbox navigation.tabs.inbox.inbox=Your Inbox navigation.tabs.inbox.archive=Your Inbox
<nav:resources override="true"/>
// first get the navigationService instance… how depends on where you are navigationService.registerItem('tabs', [controller:'reports', action:'users', title:'Reports']) navigationService.registerItem('tabs', [controller:'content', action:'view', id:'welcome', title:'Welcome']) navigationService.update()
navigation.user = [controller:'content',title:'Log in',action:'view',id:'login'] navigation.dashboard = [ [controller:'content',title:'Help',action:'view',id:'help'], [controller:'content',title:'Beta info',action:'view',id:'beta'] ]
How it works out what items are "active"
Normally you want to show the user which section of the navigation they are currently in. The rendering passes in an "active" flag for each item that is considered active.As of 1.2 this is calculated in a new way, using the current controller and action and request parameters to create a path e.g. "book/list". This is reverse-mapped to the controller and action that is declared with this path. Any nav item or sub item that matches the start or all of this path is marked active. Exact matches for query parameters are also supported, but it will fall back to a definition that does not have any parameters specified if a match is not found for e.g. "book/list/[max:5]"You can use this mechanism to provide different path mappings, other than controller/action, and to specify navigation items that do not exist as controllers - perhaps standalone GSPs. Just add the "path" attribute to the navigation declaration.You can then tell the tags what is your current "activePath" if the plugin will not be able to work it out from the controller/action (which may be null if rendering a standalone GSP):class DashboardController { static navigation = [ group:'tabs', order:10, title:'Your Inbox', action:'newInbox', path:'inbox', subItems: [[action:'newInbox', path:'inbox/new'], [action:'archive', path:'archive']] ] def index = { newInbox() } def newInbox = { [items:Inbox.findAllByUserAndArchive(user, false)]} def archive = { [items:Inbox.findAllByUserAndArchive(user, true)]} }
Commercial Support
Commercial support is available for this and other Grailsrocks plugins.Tag reference
nav:resourcesPulls in the CSS needed for default rendering. Failure to include this in a page that uses nav:render tags will result in an exceptionAttributes
- override - true to suppress inclusion of CSS, eg you are providing it in your own CSS
Attributes
- group - the name of the group. Defaults to the all '*' group if not supplied
- activePath - Optional. The current "location" inside your navigation structure. Use this to force the navigation to assume you are in a certain place in the hierarchy, or for when the current controller/action do not map directly to the menu items that should be shown as "active". Example: 'main/admin'
- var - the name of the variable to contain the item when the body is invoked. Optional
Attributes
- group - the name of the group. Defaults to the all '*' group if not supplied
- var - the name of the variable to contain the item when the body is invoked. Optional
- title - the title of the parent element to locate. Optional - defaults to current controller's subitems
- controller - the name of the controller identifying the parent of the subitems. Optional - defaults to current controller's subitems
- activePath - Optional. The current "location" inside your navigation structure. Use this to force the navigation to assume you are in a certain place in the hierarchy, or for when the current controller/action do not map directly to the menu items that should be shown as "active". Example: 'main/admin'
Attributes:
- group - the name of the group. Defaults to the all '*' group if not supplied
Attributes
- group - the name of the group. Defaults to the all '*' group if not supplied
Attributes
- id - id of the <ul> tag holding the menu items. Optional - defaults to "navigation_<nameofgroup>"
- group - the name of the navigation group. Defaults to the all '*' group if not supplied
- subitems - set to true to automatically render all subitems in nested <ul> elements
- activePath - Optional. The current "location" inside your navigation structure. Use this to force the navigation to assume you are in a certain place in the hierarchy, or for when the current controller/action do not map directly to the menu items that should be shown as "active". Example: 'main/admin'
Attributes
- id - id of the <ul> tag holding the menu items. Optional - defaults to "navigation_<nameofgroup>"
- group - the name of the navigation group. Defaults to the all '*' group if not supplied
- var - the name of the variable to contain the item when the body is invoked. Optional
- title - the title of the parent element to locate. Defaults to the name of the current controller if none supplied. Optional
- activePath - Optional. The current "location" inside your navigation structure. Use this to force the navigation to assume you are in a certain place in the hierarchy, or for when the current controller/action do not map directly to the menu items that should be shown as "active". Example: 'main/admin'