:toc: macro :toclevels: 5 :figure-caption!:

Navigator

‼️ *This gem is deprecated and will be fully destroyed on 2026-01-15. There is no replacement. Please update accordingly.* ‼️

Navigator is a Rails Engine that provides a domain specific language for menu navigation. Great for situations in which you need dynamic, server-side, rendering of site navigation menus complete with active page highlighting. You can also style your navigation menus with plain CSS or any CSS framework of your choice.

toc::[]

Features

non-path usage too).

** div ** section ** header ** h1 - h6 ** nav ** ul ** li ** a ** img ** b ** em ** s ** small ** span ** strong ** sub ** sup ** form ** label ** select ** option ** input ** button

used menu elements.

Requirements

. https://www.ruby-lang.org[Ruby] . https://rubyonrails.org[Ruby on Rails]

Setup

To install, run:

.… gem install navigator .…

Add the following to your Gemfile:

.… gem “navigator” .…

Usage

The following are examples using the navigation view helper:

Unordered List (simple)

Code:

source,ruby

navigation do

item "Dashboard", "/dashboard"
item "News", "/posts"

end


Result:

source,html

<ul>

<li><a href="/dashboard">Dashboard</a></li>
<li><a href="/posts">Posts</a></li>

</ul>


Unordered List (with attributes)

Code:

source,ruby

navigation “ul”, attributes: {class: “nav”} do

item "Dashboard", "/dashboard", item_attributes: {class: "active"}
item "News", "/posts"

end


Result:

source,html

<ul class=“nav”>

<li class="active"><a href="/dashboard">Dashboard</a></li>
<li><a href="/posts">Posts</a></li>

</ul>


Unordered List (with multiple data attributes)

Code:

source,ruby

navigation do

item "Home", "/home", item_attributes: {data: {id: 1, type: "public"}}

end


Result:

source,html

<ul>

<li data-id="1" data-type="public"><a href="/home">Home</a></li>

</ul>


_TIP: Nested data– attributes can be applied to any menu item in the same manner as Rails view helpers._

Code:

source,ruby

navigation “nav” do

a "Dashboard", attributes: {href: "/dashboard"}
a "News", attributes: {href: "/posts"}

end


Result:

source,html

<nav>

<a href="/dashboard">Dashboard</a>
<a href="/posts">Posts</a>

</nav>


Foundation Menu

Code:

source,ruby

navigation “nav”, attributes: {class: “top-bar”, “data-topbar” => nil} do

ul attributes: {class: "title-area"} do
  li attributes: {class: "name"} do
    h1 do
      a "Demo", attributes: {href: "/home"}
    end
  end
end

section attributes: {class: "top-bar-section"} do
  ul attributes: {class: "left"} do
    item "Home", "/"
    item "About", "/about"
  end

  ul attributes: {class: "right"} do
    item "v1.0.0", '#'
  end

  ul attributes: {class: "right"} do
    item "Login", "/login", link_attributes: {class: "button tiny round"}
  end
end

end


Result:

source,html

<nav class=“top-bar” data-topbar=“”>

<ul class="title-area">
  <li class="name">
    <h1><a href="/" class="active">Demo</a></h1>
  </li>
</ul>

<section class="top-bar-section">
  <ul class="left">
    <li class="active"><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>

  <ul class="right">
    <li><a href="#">v1.0.0</a></li>
  </ul>

  <ul class="right">
    <li><a class="button tiny round" href="/login">Login</a></li>
  </ul>
</section>

</nav>


Bootstrap Dropdown

Code:

source,ruby

navigation “nav” do

item "Dashboard", admin_dashboard_path
li attributes: {class: "dropdown"} do
  a "Manage", attributes: {href: "#", class: "dropdown-toggle", "data-toggle" => "dropdown"} do
    b attributes: {class: "caret"}
  end
  ul attributes: {class: "dropdown-menu"} do
    item "Dashboard", admin_dashboard_path
    item "Users", admin_users_path
  end
end

end


Result:

source,html

<ul class=“nav”>

<li><a href="/admin/dashboard">Dashboard</a></li>
<li class="dropdown">
  <a data-toggle="dropdown" class="dropdown-toggle" href="#">
    Manage
    <b class="caret"></b>
  </a>
  <ul class="dropdown-menu">
    <li><a href="/admin/dashboard">Dashboard</a></li>
    <li><a href="/admin/users">Users</a></li>
  </ul>
</li>

</ul>


Menu Helpers

There are several convenience methods, in addition to the standard HTML tags, that can make for shorter lines of code. The following describes each:

When building links, the default is:

source,ruby

navigation “nav”, activator: activator do

a "Home", attributes: {href: home_path}

end


…but can be written as:

source,ruby

navigation “nav”, activator: activator do

link "Home", home_path

end


When building images, the default is:

source,ruby

navigation “nav”, activator: activator do

img attributes: {src: "https://placehold.it/50x50", alt: "Example"}

end


..but can be written as:

source,ruby

navigation “nav”, activator: activator do

image "https://placehold.it/50x50", "Example"

end


When building menu items, the default is:

source,ruby

navigation “nav”, activator: activator do

li do
  a "Home", attributes: {href: home_path}
end

end


…but can be written as:

source,ruby

navigation “nav”, activator: activator do

item "Home", "/dashboard"

end


These are just a few, simple, examples of what can be achieved. See the specs for additional usage and customization.

Customization

The ‘navigation` view helper can accept an optional `Navigator::TagActivator` instance.

Code:

source,ruby

activator = Navigator::TagActivator.new search_value: request.env

navigation “nav”, activator: activator do

link "Home", home_path
link "About", about_path

end


Result:

source,html

<nav>

<a href="/home" class="active">Home</a>
<a href="/about" class="active">About</a>

</nav>


This is the default behavior for all navigation menus and is how menu items automatically get the “‘active`” class when the item URL (in this case “`/home`”) matches the `+request.env+` to indicate current page/active tab.

Navigator::TagActivator` instances can be configured as follows:

  • search_key = Optional. The HTML tag attribute to search for. Default: :href.

  • search_value = Required. The value to match against the search_key value in order to update the

value of the target_key. Default: nil.

  • target_key = Optional. The HTML tag attribute key value to update when the search_value and

search_key value match. Default: :class.

  • target_value = Optional. The value to be applied to the target_key value. If no value exists, then

the value is added. Otherwise, if a value exists then the value is appended to the existing value. Default: “‘active`”.

This customization allows for more sophisticated detection/updating of active HTML tags. For example, the example code (above) could be rewritten to use ‘data` attributes and customized styles.

Code:

source,ruby

activator = Navigator::TagActivator.new search_key: “data-id”,

search_value: "123",
target_key: "data-style"
target_value: "current"

navigation “nav”, activator: activator do

link "Home", home_path, attributes: {data: {id: "123", data-style="info"}}
link "About", about_path attributes: {data: {id: "789"}}

end


Result:

source,html

<nav>

<a href="/home" data-id="123" data-style="info current">Home</a>
<a href="/about" data-id="789">About</a>

</nav>


Lastly, the search value can be a _regular expression_ to make things easier when dealing with complicated routes, sub- menus, etc.

Code:

source,ruby

profile_activator = Navigator::TagActivator.new search_value: /^profile.+/

navigation do

item "Dashboard", dashboard_path
li activator: profile_activator do
  link "Profile", '#'

  ul do
    item "Addresses", profile_addresses_path
    item "Emails", profile_emails_path
  end
end

end


Result:

source,html

<ul>

<li><a href="/dashboard">Dashboard</a></li>
<li class="active">
  <a href="#">Profile</a>
  <ul>
    <li><a href="profile/addresses">Addresses</a></li>
    <li><a href="profile/emails">Emails</a></li>
  </ul>
</li>

</ul>


Assuming either the ‘Addresses` or `Emails` menu item was clicked, the `Profile` menu item would be active due to the regular expression (i.e. `/^profile.+/) matching one of the the `profile/` paths.

Development

To contribute, run:

source,bash

git clone github.com/bkuhlmann/navigator cd navigator bin/setup


You can also use the IRB console for direct access to all objects:

source,bash

bin/console


Tests

To test, run:

source,bash

bin/rake


To test the dummy application, run:

source,bash

cd spec/dummy bin/rails server


Credits