:toc: macro :toclevels: 5 :figure-caption!:
Navigator
¶ ↑
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¶ ↑
-
Provides a DSL for building navigation menus.
-
Supports auto-detection/highlighting of active menu items based on current path (customizable for
non-path usage too).
-
Supports sub-menus, nested tags, HTML attributes, etc.
-
Supports the following HTML tags:
** div ** section ** header ** h1 - h6 ** nav ** ul ** li ** a ** img ** b ** em ** s ** small ** span ** strong ** sub ** sup ** form ** label ** select ** option ** input ** button
-
Provides ‘
link
`, `image
`, and `item
` convenience methods for succinct ways to build commonly
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._
Nav (with links)¶ ↑
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.envnavigation “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
https://alchemists.io/policies/license[License]¶ ↑
https://alchemists.io/policies/security[Security]¶ ↑
https://alchemists.io/policies/code_of_conduct[Code of Conduct]¶ ↑
https://alchemists.io/policies/contributions[Contributions]¶ ↑
https://alchemists.io/projects/navigator/versions[Versions]¶ ↑
https://alchemists.io/community[Community]¶ ↑
Credits¶ ↑
-
Built with https://alchemists.io/projects/gemsmith[Gemsmith].
-
Engineered by https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
-
-