Navigation Helper

Web applications always use navigation. And the majority of the apps built enjoy keeping track of the current tab (or link or section or whatever). This plugin attempts to aid that process a bit.

You get two methods with this plugin:

• navigation(sections, options={}) – this is the helper method that is used in your views
  • sections – a :symbol array of sections (i.e. [:home, :about, :contact])
    • note: each section must map to a named route (see below in “Assumptions” for more details)
  • options – used to override default behavior
• current_tab(name) – used in any controller to override the current tab for that controller
  • name – must be a symbol matching the symbol passed in the navigation helper

Configuration Options:

• authorize => [:links] – specifies which of the sections require authorization before showing up
  • note: use :authorize => [:all] to do all links at once (i.e. for an “admin” menu)
• with => :authorization_method – specifies the method to use to authorize against (defaults to logged_in? method)
  • note: requires the authorize option to actually work
• hover_text => (true|false) – specifies to use the subtitles as hovertext instead of showing up as span’s under the links
• authorized_css => 'custom_css_class' – specifies the css class that goes on all authorized tabs (defaults to ‘authorized_nav_link’)

Installation: Get it at GitHub

You can install this as a plugin. Navigation to your project root and type:

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

Assumptions (er, Conventions)

Use Symbols for Sections

You cannot pass strings to the navigation helper and expect it to work properly. Meaning:

# incorrect
<%= navigation ['home','about','contact_me'] %>

# correct
<%= navigation [:home, :about, :contact_me] %>

This is because of the subtitles. The plugin understands strings and symbols differently, so just make
sure you’re using symbols for the sections and strings for the subtitles.

Subtitles Must Follow Respective Section

If you choose to use subtitles, just make sure you keep them “grouped” together in their respective pairs.

<%= navigation([
  :home,    'Start Here',
  :about,   'Learn More',
  :contact, 'Get In Touch'
]) %>

Named Routes matching Sections

One thing to make note of is each symbolized link you pass to the navigation helper, it is expected that a matched named route exist
(unless you’re using custom routes – see below). For instance:

# calling this
<%= navigation [:home, :about, :contact_me] %>

# would expect these named routes to exist
home_path
about_path
contact_me_path

And by default, an “underscored” link will result in capitalized words. So :contact_me would
result in ‘Contact Me’ link text. If you wish to have all lowercase or all uppercase, just use css to do that.

Custom Routes

If you need to deviate from the RESTful routes and break from consistency, you can. To set a custom route for one of your tabs, just pass a
key/value pair in place of the section, like so:

<%= navigation [{:home => some_custom_path}, :about, :contact] %>

Now your ‘Home’ tab will go to some_custom_path instead of home_path.

The examples below provide some help on how to use this plugin.

Example Usage

There are several different ways you can use this plugin. Below are a few examples showing how.

Example 1

The most basic usage…

<%= navigation [:home, :about, :contact] %>

…which will render…

<ul class="navigation">
  <li class="current"><a href="/home">Home</a></li>
  <li><a href="/about">About</a></li>
  <li><a href="/contact">Contact</a></li>
</ul>

The above example assumes that the user is actually on the home page (hence the “current” css class on the Home list item).

Example 1a (custom routes)

<%= navigation [{:home => some_custom_path}, :about, :contact] %>

…which will render…

<ul class="navigation">
  <li class="current"><a href="/some/custom/path">Home</a></li>
  <li><a href="/about">About</a></li>
  <li><a href="/contact">Contact</a></li>
</ul>

Example 2

Sometimes you need tabs to show up only based on some condition (such as a user being logged in). Picture a blog application. A Blog may have public tabs (such as Home, About, etc), but a logged in admin may want another tab to easily get to the admin interface. You can specify this behavior in the navigation helper by passing an array of links to the :authorize option…

</code><%= navigation [:home, :about, :contact, :admin], :authorize => [:admin] %>

Now, based on that setup, the “Admin” tab will require authorization before showing up.

By default, a logged_in? method will be checked, but this can be overridden (as we’ll see next).

Example 3

By default, this plugin will check against a logged_in? method to ensure an authorized user. However, if you already have a custom method you’re using to limit access and don’t want to call it
logged_in? (or maybe you need to check against a certain role), you can specify that by passing the method to use using the :with option:

<%= navigation [:home, :about, :contact, :admin], :authorize => [:admin], :with => :authorize_first %>

Now the plugin will check against an authorize_first method instead of logged_in?.

Just for completeness, you can specify multiple links to be “authorized”.

<%= navigation [:home, :about, :users, :reports], :authorize => [:users, :reports] %>

Also worth noting, each “authorized link” will have a default css class. A lot of the time, I want my “authorized” tabs to be positioned to the right of the screen, while my regular tabs are to the left, which is why I’ve added the css class. Also, this css class can be overriden using the :authorized_css option (defaults to ‘authorized_nav_link’).

Example 4

Now, let’s say you want to use the navigation helper for an entire section of admin links, maybe to show up in an admin sidebar or something. Well, we don’t want to have to repeat all of those links in the :authorize option, so you can pass a single value of :all to show/hide the entire menu based on an authorized method:

<%= navigation [:dashboard, :users, :reports], :authorize => [:all] %>

Again, by default that will look for a logged_in? method, but you can override
that by passing your own (as shown above) using the :with option. The navigation
helper will return nothing if the authorization doesn’t pass.

Example 5

Just a quick example of how to add custom css for authorized links:

<%= navigation [:about, :admin], :authorize => [:admin], :authorized_css => 'admin' %>

This would render (assuming admin tab is the current)…

<ul class="navigation">
  <li><a href="/about">About</a></li>
  <li class="current admin"><a href="/admin">Admin</a></li>
</ul>

Example 6

Now, sometimes I want to place a subtitle under my links. Maybe a brief description or something. This plugin also supports that by passing the link followed by its subtitle, like so:

<%= navigation [:home, 'Start Here', :about, 'Learn More'] %>

This would render:

<ul class="navigation">
  <li class="current">
    <a href="/home">Home</a>
    <span>Start Here</span>
  </li>
  <li>
    <a href="/about">About</a>
    <span>Learn More</span>
  </li>
</ul>

The css is up to you, but the markup is definitely flexible enough for some nice handywork.

Example 7

Maybe you want your subtitles to be a little less obtrusive and not actually show up as markup. By setting the :hover_text option to true, the subtitles will then become hover text on the links instead. Redoing the above example with hover text, we get:

<%= navigation [:home, 'Start Here', :about, 'Learn More'], :hover_text => true %>

Notice the :hover_text => true option. This would render…

<ul class="navigation">
  <li class="current">
    <a href="/home" title="Start Here">Home</a>
  </li>
  <li>
    <a href="/about" title="Learn More">About</a>
  </li>
</ul>

The span’s get replaced with link title’s instead.

Example 8

By default this plugin will use the name of the current controller to determine the current tab. But what if you don’t want to name your controllers in the context of your navigation, and vice versa (which is a very practical need)? No problem.

Let’s say you have the following controllers:

def PublicController < ApplicationController
end

def AboutController < ApplicationController
end

def ContactController < ApplicationController
end

And you wanted your navigation links to be setup like so:

<%= navigation [:home, :about, :contact] %>

According to how the navigation helper works, you would have to replace :home with :public. But that would be confusing. This is where the current_tab method comes into play. Just do this to associate a controller with a tab:

def PublicController < ApplicationController
  current_tab :home
end

And you’re set. Now whenever you’re on any action within the PublicController, the navigation helper
will match the current tab up against :home instead of :public.

License

Copyright © 2008 Ryan Heath (http://rpheath.com), released under the mit license