New Rails Navigation plugin

I mentioned before how I was getting the urge to rewrite my navigation_helper plugin, and now I finally have. But really, it takes a totally different approach, so it’s almost Just Another Navigation Plugin (JANP) and not a rewrite. Either way, you can find it on GitHub.

I don’t want to duplicate the README, but I’ll briefly touch on a few things.

Installation

Just to be explicit: navigation plugin on GitHub. Install it like so:

1

script/plugin install git://github.com/rpheath/navigation.git

Now onto the usage.

Menu Definition

This plugin requires pre-defined menus before they can be rendered in your views. This is mainly because I like writing straight-up Ruby code more than I like writing ERB code. So, here’s an example menu definition:

1
2
3
4
5
6

RPH::Navigation::Builder.config do |navigation|
  navigation.define :authenticated do |menu|
    menu.item HomeController, :text => 'Welcome'
    menu.item ContactController, :path => :contact_us_path
  end
end

The defaults are as you might expect. If no :text or :path options are present, the text would be the controller’s name, titleized, and the path would be the route that matches the controller (for HomeController expect home_path).

Also, you can define as many menus as your application needs using the yielded navigation object. And once you have your menus defined, you can render them via the key used in the definition:

1

<%= navigation :authenticated %>

Rule-based Menus and Items

You can pass an :if option to the menu itself and each menu item independently if you have some custom rules that need to be applied before rendering either the menu or a particular item. Here’s how it works:

1
2
3
4
5
6
7

RPH::Navigation::Builder.config do |navigation|
  navigation.define :authenticated, :if => Proc.new { |view| view.logged_in? } do |menu|
    menu.item HomeController, :text => 'Welcome'
    menu.item ContactController, :path => :contact_us_path
    menu.item AdminController, :if => Proc.new { |view| view.logged_in_as_admin? }
  end
end

Notice the :if option after the :authenticated key. Based on the true/false nature of that Proc, that will either render or not render the entire menu. Now, if you look down to the last menu.item, you can see another :if condition used there. That will simply render or not render that specific menu item.

The Proc will be automatically handed the view instance, so any method that ActionView::Base is aware of can be called here. And if you need the controller, just use view.controller.

There are several other things worth checking out, like support for nested menus (just pass a block to the menu.item call), separate action-level menus, and so on. Again, the README has all of the details.

This is the one area in Rails that I don’t like to think much about once it’s done, so I’m trying to come up with a solution that works for every application, despite the number of edge cases. So far, this is probably the closest I’ve come to that realization. I’m currently using it on 2 production applications and things are going just fine so far.

Questions/comments welcome, and as always, feel free to fork and improve!