makandra-navy 0.1 → 0.1.1

data/README.markdown

@@ -0,0 +1,116 @@
+Navy
+====
+
+Navy support rendering for horizontal, multi-level navigation bars. Sections are dynamic and can depend on user permissions etc.
+
+Some of the features are:
+
+- A simple but powerful DSL to describe the navigation structure
+- Subnavigations can be previewed by clicking an expand arrow
+- Sections that don't fit into the navigation bar are automatically moved into a dropdown
+
+
+How it works
+-----------
+
+The gem provides the DSL to specify the navigation structure as well as a renderer that outputs appropriate HTML.
+
+To style it, we provide a sample .sass stylesheet you have to copy and include into your stylesheet, as well as adapt to your design.
+
+The javascript functionality is provided in navy.js that you have to copy and include in your application.
+
+
+Caveats
+-------
+
+The gem should be considered in an alpha state.
+
+Styles are not very flexible yet, it might be hard to adapt them to your needs.
+
+The standard styles do not work well with old browsers (e.g. IE 8).
+
+The JavaScript features are somewhat dependent on the CSS (to determine when sections will be collapsed). In particular, you have to make sure that the dropdown arrow floats correctly right of the navigation sections.
+
+Some assets have to be copied manually, there is no generator yet.
+
+
+Installation
+------------
+
+Put this into your Gemfile:
+
+    gem 'makandra-navy', :require => 'navy'
+
+
+Copy stylesheets, javascripts and (perhaps) cucumber steps from /assets into your project.
+
+
+
+Usage
+-----
+
+Navigation structure is defined with a class like this (somewhere in your load path):
+
+    class Navigation
+      include Navy::Description
+
+      navigation :main do
+
+        section :dashboard, "Dashboard", root_path
+
+        if current_user.admin?
+          section :admin, 'Admin' do
+            section :admin_users, "Users", admin_users_path
+
+            if current_user.may_admin_projects?
+              section :admin_projects, "Projects", admin_projects_path
+            end
+          end
+        end
+      end
+
+      navigation :footer do
+        section :terms, "Terms and Conditions", terms_and_conditions_path
+        section :imprint, "Imprint", imprint_path
+      end
+
+      navigation :user do |user|
+        section :settings, "Settings", user_settings_path(user)
+      end
+
+    end
+
+
+This is all evaluated in your view context, so helpers will work.
+  
+To actually render a navigation, do this in your view:
+
+    <%= render_navigation Navigation.main, :collapse => true %>
+
+    <%= render_navigation Navigation.footer %>
+
+    <%= render_navigation Navigation.user(current_user) %>
+
+The `:collapse => true` option enables the automatic moving of navigation sections into a dropdown if they do not fit.
+
+
+Cucumber
+-------
+
+There are some cucumber steps in /assets.
+
+The most important one is:
+  
+
+    When I open the "Admin" section
+
+
+To open submenu entries, use
+ 
+   When I open the "Admin > Projects" section
+
+
+Credits
+-------
+
+Tobias Kraze, Henning Koch

data/assets/cucumber/navy_steps.rb

@@ -0,0 +1,36 @@
+When /^I open the "([^"]*)" (?:section|tab)$/ do |all_labels|
+  labels = all_labels.split('>').collect(&:squish)
+  if Capybara.current_session.driver.is_a? Capybara::Driver::Selenium
+    if labels.size == 2
+      When "I expand the \"#{labels.first}\" section"
+    end
+    When "I follow \"#{labels.last}\" within \".navy-level-#{labels.size}\""
+  else
+    opens = nil
+    section = nil
+    labels.each_with_index do |label, index|
+      scope = "div[data-navy-navigation-level='#{index + 1}']"
+      if opens
+        scope << "[data-navy-opened-by='#{opens}']"
+      end
+      scope << ' a'
+      page.should have_css(scope, :text => label)
+      section = find(scope, :text => label)
+      opens = section["data-navy-opens"]
+    end
+    section.click
+  end
+end
+
+When /^I expand the "([^"]*)" (?:section|tab)$/ do |label|
+  page.execute_script("$('.navy-level-1 .navy-section:contains(\"#{label}\") .navy-section-expander').click()")
+end
+
+Then /^there should( not)? be a "([^"]*)" (?:section|tab)$/ do |negate, label|
+  expectation = negate ? "should_not" : "should"
+  page.send(expectation, have_css(".navy-navigation", :text => label))
+end
+
+Then /^I should be in the "([^"]*)" (?:section|tab)$/ do |label|
+  page.should have_css(".navy-navigation .navy-active", :text => label)
+end

data/assets/javascripts/navy.js

@@ -0,0 +1,81 @@
+(function() {
+
+  function unexpand($navigation, level) {
+    $navigation.find('.navy-navigation-bar[data-navy-navigation-level="' + (level + 1) + '"].navy-hidden').hide();
+    $navigation.find('.navy-navigation-bar[data-navy-navigation-level="' + (level + 1) + '"].navy-current').show();
+    var $thisBar = $navigation.find('.navy-navigation-bar[data-navy-navigation-level="' + level + '"]');
+    $thisBar.find('.navy-section-expanded').removeClass('navy-section-expanded navy-active');
+    $thisBar.find('.navy-section.navy-current').addClass('navy-active');
+  }
+
+  function expand($navigation, level, idToOpen) {
+    unexpand($navigation, level);
+    $navigation.find('.navy-navigation-bar[data-navy-navigation-level="' + (level + 1) + '"]').hide();
+    $navigation.find('.navy-navigation-bar[data-navy-opened-by="' + idToOpen + '"][data-navy-navigation-level="' + (level + 1) + '"]').show();
+    var $thisBar = $navigation.find('.navy-navigation-bar[data-navy-navigation-level="' + level + '"]');
+    $thisBar.find('.navy-current').removeClass('navy-active');
+  }
+
+  function layout() {
+    $('.navy-navigation .navy-navigation-dropdown').each(function() {
+      var $dropdown = $(this);
+      var $bar = $dropdown.closest('.navy-navigation-bar');
+      var $layouted_sections = $bar.find('.navy-layouted-sections');
+      var $dropdown_sections = $bar.find('.navy-dropdown-sections');
+      $dropdown_sections.find('.navy-section').appendTo($layouted_sections);
+      if ( $layouted_sections.find('.navy-section:last').offset().top > $layouted_sections.find('.navy-section:first').offset().top ) {
+        var barTop = $bar.offset().top;
+        while ( $dropdown.offset().top > barTop ) {
+          var $last_section = $layouted_sections.find('.navy-section:not(.navy-current):last')
+          $last_section.detach().prependTo($dropdown_sections);
+          if ( $last_section.length == 0 ) break;
+        }
+      }
+      if ( $dropdown_sections.find('.navy-section').length > 0 ) {
+        $dropdown.css('visibility', 'visible');
+      } else {
+        $dropdown.css('visibility', 'hidden');
+      }
+    });
+  }
+
+  function sectionExpanderClicked() {
+    var $section = $(this).closest('.navy-section');
+    var level = Number($section.closest('.navy-navigation-bar').data('navy-navigation-level'));
+    var openId = $section.data('navy-opens');
+    if ( $section.hasClass('navy-section-expanded') ) {
+      unexpand($section.closest('.navy-navigation'), level, openId);
+    } else {
+      expand($section.closest('.navy-navigation'), level, openId);
+      $section.addClass('navy-section-expanded navy-active');
+    }
+    return false;
+  }
+
+  function navigationDropdownClicked() {
+    var $dropdownExpander = $(this);
+    var $dropdown = $dropdownExpander.closest('.navy-navigation-dropdown');
+    if ( $dropdownExpander.hasClass('navy-section-expanded') ) {
+      $dropdownExpander.removeClass('navy-section-expanded navy-active');
+      $dropdown.find('.navy-dropdown-sections').hide();
+    } else {
+      $dropdownExpander.addClass('navy-section-expanded navy-active');
+      $dropdown.find('.navy-dropdown-sections').show();
+    }
+  }
+
+  function init() {
+    $(function() {
+      $('.navy-navigation .navy-section-expander').live('click', sectionExpanderClicked);
+
+      // difficult to handle in selenium, since it now depends on browser width
+      $('.navy-navigation .navy-dropdown-expander').live('click', navigationDropdownClicked);
+
+      $(window).resize(layout);
+      
+      layout();
+    });
+  }
+
+  return { init: init, unexpand: unexpand };
+})().init();

data/lib/navy/version.rb

@@ -1,3 +1,3 @@
 module Navy
-  VERSION = "0.1"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: makandra-navy
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 1
-  version: "0.1"
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Tobias Kraze
@@ -15,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-04-13 00:00:00 Z
+date: 2012-04-20 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: actionpack
@@ -43,7 +44,10 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- README.markdown
 - Rakefile
+- assets/cucumber/navy_steps.rb
+- assets/javascripts/navy.js
 - assets/sass/_navy.sass
 - lib/navy.rb
 - lib/navy/description.rb