Xebec is a Gem and Rails plugin that helps you build navigation for your website. Tired of building custom navigation code for each site?
Have you seen Ryan Heath's Navigation Helper? It's very usable, but it only does one navigation bar. I often have sites where there are many, e.g.
+-----------------------------------------------------------+ | MyApp | Home | Sign Out | FAQ | | # "site" nav bar |===========================================================| | | *Projects* | Friends | | # "area" nav bar |===========================================================| | | Project Overview | *Budget* | History | | # "tabs" nav bar | | | | | Project "Foo" Budget | | ==================== | | ... | +-----------------------------------------------------------+
Each navigation bar has dynamic content. The site one will often have a "Sign In" and "Sign Up" link when no user is signed-in, but will have a "Sign Out" link otherwise. The area bar will often change based on the permissions/roles of the person signed in. The tabs bar will certainly depend on the area and the permissions/roles, and possibly also the features of the item being viewed. (Do all projects have budgets? If the "Budget" link goes to "./budget" then it doesn't have to be generated for each project, but it might not be so easy in other cases.)
(Of course, these site, area, and tabs aren't the only possibilities, merely a common pattern.)
Another common pattern is to differentiate the currently-selected navigation item in each applicable bar. (The asterisks in the above display.) In the case above, it probably makes sense to leave the "Projects" area item as a link when browsing a specific project so the user may easily return to the projects listing page. On the other hand, the currently active tabs item probably doesn't need to be a link. Clicking that would be the equivalent of a refresh.
Installing Xebec in a Rails Application
Add the Gem Dependency
If you're using Bundler, add this to your
If not, add this to
Add the Helpers
Add this to your
class ApplicationController < ActionController::Base helper :: end
Building and Rendering Navigation Bars
Rendering a Navigation Bar
To render a navigation bar, render
nav_bar in your view, passing the name of the bar:
<%= nav_bar :site %>
If you want to render the navigation bar only if it contains any items, use
<%= nav_bar_unless_empty :area >
If you only have one navigation bar on your site, you can leave off the name, like so:
<%= nav_bar %>
<%= nav_bar :site, :id => 'sitenav' %>
Xebec will assign this navigation bar the name
:default in case you need to refer to it elsewhere, but you probably won't.
Populating a Navigation Bar
To add items to your navigation bar in a view, call
nav_bar with a block containing any number of
<% nav_bar :site do |nb| nb.nav_item :home, root_path nb.nav_item :sign_in unless signed_in? # assumes sign_in_path end %>
Setting the "Current" Element of a Navigation Bar
A navigation bar will automatically set an item as selected if its URL matches the current page URL. That will work for pages like "FAQ" above, but what if you want "Projects" to be highlighted not only for the projects list page but also for any page in the "Projects" area, such as an individual project's "Budget" tab? You can manually set the current item in a navigation bar like so:
<% nav_bar(:area).current = :projects %>
Styling Navigation Bars
Xebec provides a stylesheet generator to build you some reasonably sane default styles. Call it from the command line with a list of the names of your navigation bars:
script/generate xebec_stylesheet site area tabs footer
Then you'll have to add the
xebec stylesheet to your layout:
<head> <%= stylesheet_link_tag :xebec, :media => :screen %> </head>
Xebec::StylesheetGenerator for more information about how to customize the generated stylesheet.
To see the full range of features that Xebec supports, including internationalization and
before_filters for your controllers, check out the example application in
Xebec::WebAppThemeRenderer if you're using Andrea Franz's web-app-theme. Check out
Xebec::TitleEnhancedNavBarRenderer if you want to give your navigation items both content and a tooltip title.
What's a xebec?
Apple's dictionary provides the following entry:
xe‧bec |ˈzēˌbek| (also ze‧bec) noun historical a small three-masted Mediterranean sailing ship with lateen and sometimes square sails. ORIGIN mid 18th cent.: alteration (influenced by Spanish xabeque) of French chebec, via Italian from Arabic šabbāk.