Configuration

By default your navigation is configured in the file config/navigation.rb. To generate a template-file with comments in it (to have an easier start), call the following generator:

$ script/generate navigation_config

In the config/navigation.rb file you define your navigation items as illustrated in the following example:

SimpleNavigation::Configuration.run do |navigation|  
  navigation.items do |primary|
    primary.item :books, 'Books', books_path
    primary.item :music, 'Music', musics_path
    primary.item :dvds, 'Dvds', dvds_path
  end
end

This creates a primary navigation with three items (for an online store which sells books, music and dvds). For each item, you define

• a key (used for identifying the active navigation item in the controllers)
• a name (string or a call to your I18n framework)
• the url that the item points to (you can use url_for, restful routes helper, named route helpers or any url as string)
• optionally you can add html-options that are passed on to the rendered navigation items (e.g. class, id etc.)

If you want to define a sub navigation for a primary item you can specify a block for that item, e.g.

primary.item :books, 'Books', books_path do |books|
  books.item :fiction, 'Fiction', fiction_books_path
  books.item :history, 'History', history_books_path
  books.item :sports, 'Sports', sports_books_path
end

which defines three sub navigation items for ‘Books’.

You can nest as many sub navigations as you like, i.e. if you would like to add a sub navigation for ‘History’, simply add another block to that item:

...
books.item :history, 'History', history_books_path do |history|
  history.item :ancient, 'Ancient', ancient_books_path
  history.item :modern, 'Modern', modern_books_path
end
...

Availability of Helpers inside the Config File

The config file is evaluated in the context of the view that renders the navigation. This means you can access all the view-helpers inside the config-file.

Conditional Navigation Items

If you want a navigation item to appear only if certain conditions apply (e.g. only showing an item linking to the admin-zone if the user is admin), you can use :if or :unless options specifying a proc (or lambda) that contains your condition:

primary.item :admin, 'Admin', admin_path, :if => Proc.new { current_user.admin? }

or if you want to show an item only if a user is logged in:

primary.item :account, 'Account', account_path(@user), :unless => Proc.new { logged_in? }

The procs you specify are – as stated above – evaluated in the context of the views, thus you can use all the methods and vars in your proc that are available in the views.

Restful delete links

If you need a navigation item that performs a destroy action (restfully spoken), you can specify :method => :delete as an option for your navigation item:

primary.item :logout, 'logout', session_path, :method => :delete, :if => Proc.new { logged_in? }

For further information on the config/navigation.rb file (more options etc…) check the comments in the generated file itself.