README.md in navigator-0.6.0 vs README.md in navigator-0.7.0
- old
+ new
@@ -1,21 +1,23 @@
# Overview
[](http://badge.fury.io/rb/navigator)
[](https://codeclimate.com/github/bkuhlmann/navigator)
+[](https://codeclimate.com/github/bkuhlmann/navigator)
[](https://gemnasium.com/bkuhlmann/navigator)
[](http://travis-ci.org/bkuhlmann/navigator)
-[](https://coveralls.io/r/bkuhlmann/navigator)
+[](https://www.gittip.com/bkuhlmann)
Enhances Rails with a DSL for menu navigation.
# Features
-* A simple DSL for creating navigation menus.
+* Provides a simple 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: ul, li, a, b, em, s, small, span, strong, sub, and sup.
-* Provides the "item" convenience method which combines the "li" and "a" HTML tags into a single method for less typing.
+* Supports the following HTML tags: nav, ul, li, a, b, em, s, small, span, strong, sub, and sup.
+* Provides an "item" convenience method which combines the "li" and "a" HTML tags into a single method for less typing.
# Requirements
0. Any of the following Ruby VMs:
* [MRI 2.x.x](http://www.ruby-lang.org)
@@ -25,11 +27,11 @@
# Setup
For a secure install, type the following from the command line (recommended):
- gem cert --add <(curl -Ls http://www.redalchemist.com/gem-public.pem)
+ gem cert --add <(curl -Ls http://www.alchemists.io/gem-public.pem)
gem install navigator --trust-policy MediumSecurity
NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while
allowing the installation of unsigned dependencies since they are beyond the scope of this gem.
@@ -41,86 +43,165 @@
gem "navigator"
# Usage
-The following are examples using the render_navigation view helper:
+The following are examples using the navigation view helper:
## Unordered List (simple)
- render_navigation do
+Code:
+
+ navigation do
item "Dashboard", "/dashboard"
item "News", "/posts"
end
-Yields:
+Result:
<ul>
<li><a href="/dashboard">Dashboard</a></li>
<li><a href="/posts">Posts</a></li>
</ul>
## Unordered List (with attributes)
- render_navigation "ul", class: "nav" do
+Code:
+
+ navigation "ul", class: "nav" do
item "Dashboard", "/dashboard", class: "active"
item "News", "/posts"
end
-Yields:
+Result:
<ul class="nav">
<li class="active"><a href="/dashboard">Dashboard</a></li>
<li><a href="/posts">Posts</a></li>
</ul>
## Nav (with links)
- render_navigation "nav" do
+Code:
+
+ navigation "nav" do
a "Dashboard", href: "/dashboard"
a "News", href: "/posts"
end
-Yields:
+Result:
<nav>
<a href="/dashboard">Dashboard</a>
<a href="/posts">Posts</a>
</nav>
-## Twitter Bootstrap Dropdown
+## Foundation Menu
- li nil, class: "dropdown" do
- a "Manage", href: "#", class: "dropdown-toggle", "data-toggle" => "dropdown" do
- b nil, class: "caret"
+Code:
+
+ navigation "ul", class: "left" do
+ item "Home", root_path
+ item "About", about_path
+ end
+
+Result:
+
+ <ul class="ul" class: "left">
+ <li class="active"><a href="/home">Home</a></li>
+ <li><a href="/about">About</a></li>
+ </ul>
+
+## Bootstrap Dropdown
+
+Code:
+
+ navigation "nav" do
+ item "Dashboard", admin_dashboard_path
+ li nil, class: "dropdown" do
+ a "Manage", href: "#", class: "dropdown-toggle", "data-toggle" => "dropdown" do
+ b nil, class: "caret"
+ end
+ ul nil, class: "dropdown-menu" do
+ item "Dashboard", admin_dashboard_path
+ item "Users", admin_users_path
+ end
end
- ul nil, class: "dropdown-menu" do
- item "Dashboard", admin_dashboard_path
- item "Users", admin_users_path
- end
end
-Yields:
+Result:
<ul class="nav">
- <li><a href="/en-US/admin/dashboard">Dashboard</a></li>
+ <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>
+ <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>
+# Customization
+
+The `navigation` view helper can accept an optional `Navigator::TagActivator` instance. Example:
+
+ # Code
+ activator = Navigator::TagActivator.new search_value: request.env["PATH_INFO"]
+ navigation "nav", {}, activator do
+ a "Home", href: home_path
+ a "About", href: about_path
+ end
+
+ <!-- Result -->
+ <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 automaticaly get the "active" class when the
+item URL (in this case "/home") matches the `request.env[“PATH_INFO"]` 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 as follows:
+
+ # Code
+ activator = Navigator::TagActivator.new search_key: "data-id",
+ search_value: "123",
+ target_key: "data-style"
+ target_value: "current"
+
+ navigation "nav", {}, activator do
+ a "Home", href: home_path, "data-id" => "123", data-style="info"
+ a "About", href: about_path, "data-id" => "789"
+ end
+
+ <!-- Result -->
+ <nav>
+ <a href="/home" data-id="123" data-style="info current">Home</a>
+ <a href="/about" data-id="789">About</a>
+ </nav>
+
# Tests
-To test, do the following:
+To test, run:
-0. cd to the gem root.
-0. bundle install
-0. bundle exec rspec spec
+ bundle exec rspec spec
# Versioning
Read [Semantic Versioning](http://semver.org) for details. Briefly, it means:
@@ -128,20 +209,20 @@
* Minor (x.Y.z) - Incremented for new, backwards compatible public API enhancements and/or bug fixes.
* Major (X.y.z) - Incremented for any backwards incompatible public API changes.
# Contributions
-Read CONTRIBUTING for details.
+Read [CONTRIBUTING](CONTRIBUTING.md) for details.
# Credits
-Developed by [Brooke Kuhlmann](http://www.redalchemist.com) at [Red Alchemist](http://www.redalchemist.com)
+Developed by [Brooke Kuhlmann](http://www.alchemists.io) at [Alchemists](http://www.alchemists.io)
# License
-Copyright (c) 2011 [Red Alchemist](http://www.redalchemist.com).
-Read the LICENSE for details.
+Copyright (c) 2012 [Alchemists](http://www.alchemists.io).
+Read the [LICENSE](LICENSE.md) for details.
# History
-Read the CHANGELOG for details.
+Read the [CHANGELOG](CHANGELOG.md) for details.
Built with [Gemsmith](https://github.com/bkuhlmann/gemsmith).