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 viewssections– 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 controllername– must be a symbol matching the symbol passed in thenavigationhelper
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)
- note: use
with => :authorization_method– specifies the method to use to authorize against (defaults tologged_in?method)- note: requires the
authorizeoption to actually work
- note: requires the
hover_text => (true|false)– specifies to use the subtitles as hovertext instead of showing up as span’s under the linksauthorized_css => 'custom_css_class'– specifies the css class that goes on all authorized tabs (defaults to ‘authorized_nav_link’)
You can install this as a plugin. Navigation to your project root and type:
git clone git://github.com/rpheath/navigation_helper.git vendor/plugins/navigation_helperYou 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.
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'
])
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. 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.
The examples below provide some help on how to use this plugin.
There are several different ways you can use this plugin. Below are a few examples showing how.
The most basic usage…
navigation [:home, :about, :contact]…which will render…
<ul class="nav_bar">
<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).
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).
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_firstNow 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’).
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.
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="nav_bar">
<li><a href="/about">About</a></li>
<li class="current admin"><a href="/admin">Admin</a></li>
</ul>
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="nav_bar">
<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.
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 => trueNotice the :hover_text => true option. This would render…
<ul class="nav_bar">
<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.
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.
Copyright © 2008 Ryan Heath (http://rpheath.com), released under the mit license