Rails plugin: provides automatic navigation for RESTful architectures, and has simple support for those that aren't.
h1. 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:
h2. Configuration Options:
h2. 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.gith2. Assumptions (er, Conventions)
h3. 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.
h3. 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'
]) %>
h3. 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.
h3. 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.
h2. Example Usage
There are several different ways you can use this plugin. Below are a few examples showing how.
h3. Example 1
The most basic usage…
<%= navigation [:home, :about, :contact] %>…which will render…
The above example assumes that the user is actually on the home page (hence the “current” css class on the Home list item).
h3. Example 1a (custom routes)
<%= navigation [{:home => some_custom_path}, :about, :contact] %>…which will render…
h3. 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…
<%= 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).
h3. 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’).
h3. 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.
h3. 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)…
h3. 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:
The css is up to you, but the markup is definitely flexible enough for some nice handywork.
h3. 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…
The span’s get replaced with link title’s instead.
h3. 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@.
h2. License
Copyright © 2008 Ryan Heath (http://rpheath.com), released under the mit license