waiter 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.idea
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in menu_builder.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Daniel Vandersluis
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# Waiter
+
+Waiter serves up menus for your application:
+* Provides a quick DSL for building menus, without having to specify any HTML.
+* Makes assumptions based on what's provided in the DSL so that the specification does not need to be unnecessarily verbose.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'waiter'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install waiter
+
+## Usage
+
+### Building a menu
+
+To create a new menu:
+
+    Waiter::Menu.serve do |menu|
+      menu.file
+      menu.edit
+      menu.view
+      # ...
+    end
+
+The above defines a menu with three items. By default, each item name (ie. "file", "edit", etc.) corresponds both to the I18n string to use (so `menu.file` will call `I18n.t(:file)`) as well as to the controller to use (`menu.file` will correspond to `FileController`, and the menu item will link to `FileController#index` by default).
+
+Of course, there will be situations where the path may need to be explicitly specified. In this case, the `:controller`
+and `:action` options can be specified:
+
+    Waiter::Menu.serve do |menu|
+      menu.file :controller => 'documents', :action => 'show'
+    end
+
+In this case the File menu will correspond to `DocumentsController#show`, and will only light up for that action. If
+no specific action is given, the menu item will be lit up for all actions within the given controller.
+
+There may also be times where you need multiple controllers to light up the same menu item. This can be achieved by
+passing an array to the `:controllers` option:
+
+    Waiter::Menu.serve do |menu|
+      menu.file :controller => 'documents', :controllers => ['files', 'print', ... ]
+    end
+
+This will create a menu that links to `DocumentsController#index`, which will be lit up the user hits any action within the `FilesController`, `PrintController`, as well as the `DocumentsController`.
+
+
+### Submenus
+
+Menus can also have submenus (currently only one level of nesting is supported when drawing a menu, but infinite
+levels are supported when building a menu). A submenu is defined with the same syntax as a root menu item, and is
+passed as a block to the root menu item.
+
+Submenus automatically assume the controller to use is the controller specified by its root menu item, so a
+controller does not need to be specified unless it differs. As well, the menu item name is assumed to be used
+for the action within that controller, so action does not need to be specified unless it differs from the name.
+An id can also be specified if necessary (with the `:id` option).
+
+    Waiter::Menu.serve do |menu|
+      menu.file, :controllers => ['print'] do |file|
+        file.new                            # Corresponds to FileController#new
+        file.open :action => :read          # Corresponds to FileController#read
+        file.save :action => :write         # Corresponds to FileController#write
+        file.print, :controller => 'print'  # Corresponds to PrintController#print
+      end
+    end
+
+If an action isn't explicitly given, and the menu item name does not correspond to an actual action, the default
+action for the controller will be used instead.
+
+
+### Menu Options
+
+There are two options that you can use when building your menu. Options can be passed into build when defining
+a menu or specified once the menu is defined by accessing the menu.options hash.
+
+`string_prefix`: Allows for a prefix for I18n strings to be specified.
+
+    Waiter::Menu.serve(:string_prefix => 'menu_') do |menu|
+      menu.file
+    end
+
+    # will use I18n.t(:menu_file) instead of I18n.t(:file)
+
+`selected`: Allows the selected menu item to be overridden, so a specified menu item can be lit up regardless of
+what the current controller/action is. This can be useful if there is an action that falls under different menu
+items depending on application context, or if there is a controller that may correspond to multiple menu items.
+A good way to achieve this would be to add a before_filter to set an instance variable which is then passed into
+the selected option.
+
+    before_filter :set_current_menu
+
+    def set_current_menu
+      case params[:action]
+        when 'foo' then @current_menu = "menu1"
+        when 'bar' then @current_menu = "menu2"
+      end
+    end
+
+    Waiter::Menu.serve(:selected => @current_menu) do |menu|
+    end
+
+Note that the value passed to `:selected` should match the name of the menu item.
+
+
+### Drawing (outputting) a menu
+
+To draw a created menu, use the `Waiter::Menu::Drawer` class. The class requires the current context to be
+passed in so that `ActionController` methods can be used. In general (ie. if the menu is being drawn from a helper)
+the context is self.
+
+    menu = Waiter::Menu.serve do |menu|
+      # ...
+    end
+
+    Waiter::Menu::Drawer.new(menu, context).draw
+
+If a different `Drawer` is desired, `Waiter::Menu::Drawer` can be subclassed and the methods `draw` and `draw_submenu` overridden to provide an alternate format.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/waiter.rb

@@ -0,0 +1,4 @@
+require "waiter/version"
+require "waiter/menu"
+require "waiter/menu/builder"
+require "waiter/menu/drawer"

data/lib/waiter/menu.rb

@@ -0,0 +1,26 @@
+module Waiter
+  class Menu
+    attr_accessor :options, :submenus
+
+    class << self
+      def serve(options = {})
+        yield Builder.new(obj = self.new(options))
+        obj
+      end
+    end
+
+    def initialize(options = {})
+      @menu_items = []
+      @submenus = {}
+      @options = options
+    end
+
+    def add(name, args = {})
+      @menu_items << [name, args]
+    end
+
+    def items
+      @menu_items
+    end
+  end
+end

data/lib/waiter/menu/builder.rb

@@ -0,0 +1,18 @@
+module Waiter
+  class Menu
+    # Builds a menu structure from the DSL
+    class Builder
+      def initialize(menu)
+        @menu = menu
+      end
+
+      def method_missing(name, *args, &block)
+        @menu.add name, *args
+        if block_given?
+          @menu.submenus[name] = Menu.new(@menu.options.merge(:controller => (args.first.andand[:controller] || name)))
+          yield Builder.new(@menu.submenus[name])
+        end
+      end
+    end
+  end
+end

data/lib/waiter/menu/drawer.rb

@@ -0,0 +1,91 @@
+module Waiter
+  class Menu
+    # Outputs a Menu into HTML
+    class Drawer
+      # @context is a Controller binding, which allows the ActionView helpers to work in the correct context
+      delegate :link_to, :content_tag, :params, :to => :@context
+
+      def initialize(menu, context)
+        @context = context
+        @menu = menu
+      end
+
+      def draw
+        content_tag :div, :id => "menu" do
+          out = ActiveSupport::SafeBuffer.new
+
+          @menu.items.each do |(name, menu)|
+            menu[:controller] = name unless menu[:controller]
+
+            # Allow an :if option which will only display the menu if true
+            if !menu[:if] or menu[:if].call
+              # If there is a :selected option, use that instead of trying to determine the selected menu item
+              selected = menu_selected?(name, menu[:controller], menu[:action] || menu[:actions], menu.delete(:controllers))
+
+              out << content_tag(:span, :class => selected ? "selected" : nil) do
+                out2 = ActiveSupport::SafeBuffer.new
+                out2 << link_to(I18n.t(@menu.options[:string_prefix].to_s + name.to_s), { :controller => menu.delete(:controller).to_s.absolutify, :action => (menu.delete(:action) || menu.delete(:actions).andand.first) }.merge(menu))
+                out2 << draw_submenu(@menu.submenus[name]) if @menu.submenus[name]
+                out2
+              end
+            end
+          end
+
+          out << '<br class="clear" />'.html_safe
+          out
+        end
+      end
+
+      def draw_submenu(submenu)
+        content_tag :table, :class => "dropdown", :cellspacing => 0 do
+
+          out = ActiveSupport::SafeBuffer.new
+
+          submenu.items.each do |(name, menu)|
+            out << content_tag(:tr) do
+              content_tag :td do
+                controller = menu.delete(:controller) || submenu.options[:controller]
+                action =
+                    menu.delete(:action) || begin
+                      controller_class = "#{controller}_controller".classify.constantize
+                      controller_class.action_methods.include?(name.to_s) ? name : nil
+                    end rescue nil || :index
+
+                link_to I18n.t(submenu.options[:string_prefix].to_s + name.to_s), { :controller => controller.to_s.absolutify, :action => action }.merge(menu)
+              end
+            end
+          end
+
+          out
+        end
+      end
+
+      protected
+      def menu_selected?(name, controller, action = nil, controllers = [])
+        controllers = [] unless controllers
+
+        if @menu.options[:selected]
+          name.to_s == @menu.options[:selected].to_s
+        else
+          return true if controllers.map(&:to_s).include?(params[:controller])
+
+          selected = params[:controller] == controller.to_s
+
+          if action.is_a? Array
+            selected &&= action.map(&:to_s).include?(params[:action])
+          elsif action
+            selected &&= params[:action] == action.to_s
+          end
+
+          selected
+        end
+      end
+    end
+  end
+end
+
+class String
+  def absolutify
+    self.gsub(%r{^(?!/)}, "/")
+  end
+end

data/lib/waiter/version.rb

@@ -0,0 +1,3 @@
+module Waiter
+  VERSION = "0.0.1"
+end

data/waiter.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'waiter/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "waiter"
+  gem.version       = Waiter::VERSION
+  gem.authors       = ["Daniel Vandersluis"]
+  gem.email         = ["dvandersluis@selfmgmt.com"]
+  gem.description   = "Provides an easy DSL for serving up menus"
+  gem.summary       = "Quick and easy DSL for generating menus for use in Rails applications"
+  gem.homepage      = "https://github.com/dvandersluis/waiter"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "activesupport", "> 3.0.0"
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: waiter
+version: !ruby/object:Gem::Version
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors:
+- Daniel Vandersluis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  prerelease: false
+  type: :runtime
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  name: activesupport
+description: Provides an easy DSL for serving up menus
+email:
+- dvandersluis@selfmgmt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/waiter.rb
+- lib/waiter/menu.rb
+- lib/waiter/menu/builder.rb
+- lib/waiter/menu/drawer.rb
+- lib/waiter/version.rb
+- waiter.gemspec
+homepage: https://github.com/dvandersluis/waiter
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Quick and easy DSL for generating menus for use in Rails applications
+test_files: []
+has_rdoc: