RocketNavigation

Master repository has moved to gitlab, all new code will be there:

https://gitlab.com/rocket-science/rocket_navigation

Status

Currently beta quality, but we already use it in production for some projects.

Lots of tests (which were copied and adapted from SimpleNavigation) are failing, but the gem itself works and is somewhat tested in real world projects as a replacement for SimpleNavigation.

But anyway use at your own risk.

About

This gem is heavily inspired by (and uses some code from) simple-navigation but it is NOT a drop-in replacement.

Changes include:

Simple with no dark magic involved
Thread safe with no mutexes. (simple_navigation's render_navigation can render incomplete navs and not render any items at all under multithread load due to app-global config, which is used internally even if proc or items passed)
Supports only Rails, support for sinatra/paradino is removed.
Defining navigation via magic eval-loaded config file is not available, use real code.
Much simpler and more configurable at the same time.
Add many additional highlight options from active_link_to gem
Add ability to set CSS classes and container DOM attributes on render
ID autogeneration is removed
Rewritten to use and allow helpers in renderers and to use ActiveSupport::SafeBuffer everywhere in renderers
All css classes are managed in renderers and can be easily overriden from them
Added breadcrumbs_on_rails integration
expand_all defaults to true, as pretty much all menus are js-based now.
Includes bootstrap 4 renderer, with optional superfish support for multilevel menu

Installation

Add this line to your application's Gemfile:

gem 'rocket_navigation'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rocket_navigation

Usage

Basic usage is the same and complatible with simple_navigation - but only if you pass menu data as a proc or as items hash (config file not supported).

helper:

def navigation(kind = :main)
  proc do |primary|
    primary.item :home, 'Home', root_path do |sub_nav|
      sub_nav.item(:people, 'People', people_path, highlights_on: [:people, :show]) do |person|
        person.item :person, @person.try(:name), url_for(@person), highlights_on: /people\/[0-9]+/
        person.item :new_person, 'New Person', new_person_path, highlights_on: /people\/new$/
      end
    end
  end
end

view:

= render_navigation level: 1..2, &navigation(:main)

More docs

Basic menu usage is the same as simple-navigation

See https://github.com/codeplant/simple-navigation/wiki/Dynamic-Navigation-Items

This gem aims to be a drop-in replacement for this mode, including custom renderer code and api. Any incomatibility can be reported as a bug.

Most renderers should be compatible out of the box, or require minimal changes due to ActiveSupport::SafeBuffer usage instead of .html_safe.

Setting HTML attributes

on render:

# helper
def menu_options
  {
    container_html: {class: "nav"},
    item_html: {
      class: 'nav nav-item'
    },
    link_html: {
      class: %w(link nav-link),
      rel: "nofollow",
    },
    selected_class: {
      leaf: "selected-leaf",
      item: "selected-li",
      link: "selected-a"
    }
  }
end

view:

= render_navigation menu_options, &navigation(:main)
= render_navigation no_default_classes: true, &navigation(:main)
= render_navigation renderer: :breadcrumbs, no_default_classes: true, prefix: "You are here: ", static_leaf: true, join_with: " &rarr; ".html_safe, &extra_nav

bootstrap example:

= render_navigation container_html: {class: "nav navbar-nav"}, renderer: :bootstrap, &navigation(:main)

Same options could be defined on a container when defining menu:

def navigation(kind = :main)
  proc do |primary|
    primary.container_html = {class: "nav"}
    primary.item_html = {class: 'nav-item'}
    primary.link_html = {class: 'nav-link'}
    primary.selected_class = {branch: "active-branch", item: "active", link: "active"}
    primary.item :home, 'Home', root_path, item_html: {class: "other"}, link_html: {class: "other"}
    primary.item :two, 'Two', root_path, item_html: {class: "more two"}, link_html: {class: "two", method: :post}
  end
end
helper_method :navigation

HTML options priority - item, renderer, default

BreadcrumbsOnRails integration

Just render with a breadcrumbs_on_rails renderer. Returns nothing, calls add_breadcrumb instead. Should be called before = render_breadcrumbs, i.e. in controller

render_navigation renderer: :breadcrumbs_on_rails, &navigation(:main)

Bootstrap example with superfish

required js:

$(function() {
  $('ul.navbar-nav').superfish();
})

required sass:

.dropdown-menu
  margin-top: 0

rendering:

= render_navigation container_html: {class: "nav navbar-nav"}, renderer: :bootstrap, superfish: true, &navigation(:main)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rs-pro/rocket_navigation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the RocketNavigation project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.