antw-kin 0.3.2 → 0.3.3

data/CHANGELOG

@@ -1,3 +1,14 @@
+== 0.3.3 2009-08-28
+
+* Added Subnav and HasRight menu formatters.
+* A custom formatter can now be supplied when setting up a menu.
+
+== 0.3.2 2009-08-27
+
+* The _modal.sass partial, containing shared styles for modal dialogs, has
+  been added to assets/css.
+* Added a block syntax for defining nav items.
+
 == 0.3.1 2009-08-26
 
 * When setting on which controller and actions a nav item can be active, you

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:patch: 2
+:patch: 3
 :major: 0
 :minor: 3

data/lib/kin.rb

@@ -14,10 +14,13 @@ if defined?(Merb::Plugins)
   require File.join(kin, 'nav')
 
   Merb::Plugins.add_rakefiles(File.join(kin, 'tasks', 'sync_assets'))
+  Merb::Plugins.add_rakefiles(File.join(kin, 'tasks', 'sprites'))
 
   # Default nav formatter. Can be overridden in an after_app_loads block, or
   # on a case-by-case basis in +display_navigation+.
-  Merb::Plugins.config[:kin] = { :nav_formatter => Kin::Nav::BasicFormatter }
+  Merb::Plugins.config[:kin] = {
+    :nav_formatter => Kin::Nav::Formatters::Basic
+  }
 
   Merb::BootLoader.after_app_loads do
     # Add default time formats.

data/lib/kin/masthead.rb

@@ -22,20 +22,38 @@ module Kin
     class Builder
       include Merb::Helpers::Tag
 
-      DEFAULT_CLASSES = {
+      CSS_CLASSES = {
         :title          => ''.freeze,
         :subtitle       => 'subtitle'.freeze,
         :right_title    => 'main'.freeze,
         :right_subtitle => 'subtitle'.freeze
       }.freeze
 
-      attr_accessor :no_border
-      attr_reader   :options
-
+      ##
+      # Creates a new masthead builder.
+      #
+      # @api semipublic
+      #
       def initialize
-        @title, @right_title = nil, nil
-        @subtitle, @right_subtitle = nil, nil
-        @options = {}
+        @title = @right_title = @subtitle = @right_subtitle = nil
+        @options = Hash.new { |hash, key| hash[key] = {} }
+      end
+
+      ##
+      # Builds a masthead.
+      #
+      # Yields the builder instance providing a DSL for setting up the
+      # masthead as desired.
+      #
+      # @return [Kin::Nav::Builder]
+      #
+      # @yield [Kin::Nav::Builder]
+      #
+      # @api semipublic
+      #
+      def build
+        yield self
+        self
       end
 
       ##
@@ -46,6 +64,8 @@ module Kin
       # @param  [Hash]   options A hash containing extraoptions.
       # @return [String]         The masthead title.
       #
+      # @api public
+      #
       def title(value = nil, options = nil)
       end
 
@@ -57,6 +77,8 @@ module Kin
       # @param  [Hash]   options A hash containing extraoptions.
       # @return [String]         The masthead right title.
       #
+      # @api public
+      #
       def right_title(value = nil, options = nil)
       end
 
@@ -68,6 +90,8 @@ module Kin
       # @param  [Hash]   options A hash containing extraoptions.
       # @return [String]         The masthead subtitle.
       #
+      # @api public
+      #
       def subtitle(value = nil, options = nil)
       end
 
@@ -79,6 +103,8 @@ module Kin
       # @param  [Hash]   options A hash containing extraoptions.
       # @return [String]         The masthead right subtitle.
       #
+      # @api public
+      #
       def right_subtitle(value = nil, options = nil)
       end
 
@@ -101,89 +127,114 @@ module Kin
       end
 
       ##
-      # Returns the masthead as HTML.
-      # @return [String] The masthead with all the various titles.
+      # Returns the HTML representation of the masthead.
+      #
+      # @return [String]
+      #   The masthead with all the various titles.
+      #
+      # @api public
       #
       def to_html
-        formatted_title = formatted(:title, :h1)
-        formatted_subtitle = formatted(:subtitle) if @subtitle
-
-        extras = if has_extras?
-          '<div class="extra">%s %s</div>' % [
-            formatted(:right_title) || '<span class="main">&nbsp;</span>',
-            @right_subtitle ? formatted(:right_subtitle) : ''
-          ]
-        end
-
         <<-HTML
-          <div id="masthead"#{no_border ? ' class="no_border"' : ''}>
+          <div id="masthead">
             <div class="details">
-              #{formatted_title}
-              #{formatted_subtitle}
+              #{ formatted(:title, :h1) }
+              #{ formatted(:subtitle) }
             </div>
 
-            #{extras}
+            #{ extras_as_html }
           </div>
         HTML
       end
 
-      ##
-      # Builds a masthead.
-      #
-      def build
-        yield self
-        self
-      end
-
-      #######
-      private
-      #######
+      private # ==============================================================
 
       ##
-      # Returns whether this masthead builder has an "extras".
+      # Returns <div.extra> containing the right-hand stuff.
       #
-      # Extras are defined as being a right-hand title or right-hand subtitle.
-      # Generally, if the builder has no extras, the .extras div will not be
-      # rendered by #to_html
+      # @return [String, nil]
+      #   Returns nil if no <div.extra> is needed.
       #
-      # @return [TrueClass|FalseClass]
+      # @api private
       #
-      def has_extras?
-        not @right_title.nil? or not @right_subtitle.nil?
+      def extras_as_html
+        unless @right_title.nil? && @right_subtitle.nil?
+          <<-HTML
+            <div class="extra">
+              #{ formatted(:right_title) }
+              #{ formatted(:right_subtitle) }
+            </div>
+          HTML
+        end
       end
 
       ##
-      # Returns formatted text for a given field. Wraps the text in a link if
-      # one is required, otherwise the text is returned on it's own.
+      # Returns the HTML element containing the value for the field specified
+      # by +field+.
+      #
+      # @param [Symbol] field
+      #   The name of the field whose value you wish to retrieve.
+      # @param [Symbol] wrap_in
+      #   The HTML element which should wrap the field value.
+      #
+      # @return [String, nil]
+      #   nil will be returned if no the field should not be displayed.
+      #
+      # @api semipublic
       #
       def formatted(field, wrap_in = :span)
-        if instance_variable_get(:"@#{field}").blank?
-          return nil
-        else
-          value = instance_variable_get(:"@#{field}").to_s
-        end
+        value = value_for(field)
+        options = @options[field]
 
-        options = @options[field] || {}
-        link    = options.delete(:link)
+        if value.blank?
+          # If the field is blank, we want to return _unless_ the field is the
+          # right subtitle, and a right title is set (in which case a title
+          # element is needed to push the subtitle down).
+          if field != :right_title || value_for(:right_subtitle).blank?
+            return nil
+          else
+            value = '&nbsp;'
+            options[:no_escape] = true
+          end
+        end
 
         # Escape required?
         unless options.delete(:no_escape)
-          value = Merb::Parse.escape_xml(value.to_s)
+          value = Merb::Parse.escape_xml(value)
         end
 
         # Link required?
-        if link
-          value = '<a href="%s" title="%s">%s</a>' % [link, value, value]
+        if options.has_key?(:link)
+          value = %[<a href="#{options.delete(:link)}"] +
+                    %[ title="#{value}">#{value}</a>]
         end
 
+        # Set the CSS class.
         if options[:class]
-          options[:class] += ' %s' % DEFAULT_CLASSES[field]
-        elsif field != :title
-          options[:class] = DEFAULT_CLASSES[field]
+          options[:class] = [options[:class], CSS_CLASSES[field]].join(' ')
+        elsif CSS_CLASSES[field] != ''
+          options[:class] = CSS_CLASSES[field]
         end
 
         tag(wrap_in, value, options)
       end
+
+      ##
+      # Retrieves a value for the specified +field+.
+      #
+      # @param [Symbol] field
+      #   The name of the field whose value you wish to retrieve.
+      #
+      # @return [String, nil]
+      #   Returns nil if nothing is set, or a string version of whatever the
+      #   field is set to.
+      #
+      # @api private
+      #
+      def value_for(field)
+        value = instance_variable_get(:"@#{field}")
+        value.nil? ? nil : value.to_s
+      end
     end
 
     ##
@@ -199,22 +250,24 @@ module Kin
       # Note that the block is evaluated within the MastheadBuilder instance
       # itself.
       #
-      # @example [In a template]
-      #   - masthead(:no_border => true) do
+      # @example In a template
+      #   - masthead do
       #     - title @set
       #     - subtitle "This set contains #{@set.contents}"
       #
+      # @api public
+      #
       def masthead(options = {}, &blk)
-        masthead_builder.no_border = options.fetch(:no_border, false)
         masthead_builder.build(&blk)
       end
 
       ##
       # Returns the MastheadBuilder instance for the current request.
       #
-      # @api private
       # @return [Kin::MastheadBuilder]
       #
+      # @api public
+      #
       def masthead_builder
         @_masthead_builder ||= Kin::Masthead::Builder.new
       end

data/lib/kin/nav.rb

@@ -19,6 +19,8 @@ module Kin
     #
     # @param [Symbol] name
     #   A name for this menu.
+    # @param [Kin::Nav::Formatters::Basic] formatter
+    #   A custom formatter to use when rendering the menu as HTML.
     # @param [Block] blk
     #   A block for setting up the menu.
     #
@@ -27,8 +29,8 @@ module Kin
     #
     # @api public
     #
-    def self.setup(name = :default, &blk)
-      menu = Builder.new(name).build(&blk)
+    def self.setup(name = :default, formatter = nil, &blk)
+      menu = Builder.new(name, formatter).build(&blk)
       menu.freeze
       menu.items.freeze
       menu.items.each { |i| i.freeze }
@@ -88,17 +90,31 @@ module Kin
       #
       # @param [Symbol] name
       #   A name for this nav.
+      # @param [Kin::Nav::Formatters::Basic]
+      #   A formatter to be used when rendering the menu.
       #
       # @api private
       #
-      def initialize(name)
+      def initialize(name, formatter = nil)
         @name  = name.to_sym
+        @formatter = formatter
         @items = []
 
         # Used to find the active item on a given page.
         @matchers = Struct.new(:best, :controller, :generic).new([], [], [])
       end
 
+      ##
+      # Returns the default formatter to be used when rendering this menu.
+      #
+      # @return [Kin::Nav::Formatters::Basic]
+      #
+      # @api public
+      #
+      def formatter
+        @formatter || Merb::Plugins.config[:kin][:nav_formatter]
+      end
+
       ##
       # Adds a controller name / action name pair for matching active items.
       #
@@ -109,7 +125,7 @@ module Kin
       #
       # @return Kin::Nav::ItemMatcher
       #
-      # @api semipubic
+      # @api semipublic
       #
       def add_active_match(name, item)
         name = name.split('/')
@@ -228,6 +244,8 @@ module Kin
       # Returns true if this item expects a resource in order to generate a
       # URL.
       #
+      # @api private
+      #
       def expects_resource?
         not @resource.nil?
       end
@@ -235,6 +253,8 @@ module Kin
       ##
       # Takes a resource and generates a URL.
       #
+      # @api private
+      #
       def resource_url(given)
         raise MissingResource, "Nav item #{id.inspect} expected a " \
           "resource to generate a URL, and none was given" unless given
@@ -255,6 +275,11 @@ module Kin
     # given controller and action.
     #
     class ItemMatcher
+      ##
+      # Returns the item which this matcher is associated.
+      #
+      # @api semipublic
+      #
       attr_reader :item
 
       ##

data/lib/kin/nav/builder.rb

@@ -10,11 +10,13 @@ module Kin
       #
       # @param [Symbol] name
       #   A unique name for the Menu instance.
+      # @param [Kin::Nav::Formatters::Basic] formatter
+      #   A custom formatter to use when rendering the menu as HTML.
       #
       # @api private
       #
-      def initialize(name)
-        @nav = Menu.new(name)
+      def initialize(name, formatter = nil)
+        @nav = Menu.new(name, formatter)
         @item_builders = []
       end
 

data/lib/kin/nav/formatters.rb

@@ -1,116 +1,211 @@
 module Kin
   module Nav
-
-    ##
-    # Receives a nav instance and transforms it into HTML.
-    #
-    # @see Kin::Nav::Helper#display_navigation
-    #
-    class BasicFormatter
-      include Merb::Helpers::Tag
-
+    module Formatters
       ##
-      # Creates a new BasicFormatter instance.
-      #
-      # @param [Kin::Nav::Menu] nav
-      #   An instance of a Menu to be rendered as HTML.
-      # @param [#controller_name, #action_name] controller
-      #   An object which behaves like a controller.
-      # @param [Hash] options
-      #   A hash of options for customising the menu. See
-      #   Kin::Nav::Helper#display_navigation.
+      # Receives a nav instance and transforms it into HTML.
       #
-      # @api public
+      # @see Kin::Nav::Helper#display_navigation
       #
-      def initialize(nav, controller, options)
-        @nav = nav
-        @current  = nav.active_item(controller)
-
-        @resource = options[:resource]
-        @inject   = options.fetch(:inject, {})
-        @guards   = options.fetch(:guard, {})
-
-        # Escape injected content.
-        @inject.each do |item_id, contents|
-          contents = Array(contents)
-          contents.map! { |v| Merb::Parse.escape_xml(v) }
-          @inject[item_id] = contents
+      class Basic
+        include Merb::Helpers::Tag
+
+        ##
+        # Creates a new BasicFormatter instance.
+        #
+        # @param [Kin::Nav::Menu] nav
+        #   An instance of a Menu to be rendered as HTML.
+        # @param [#controller_name, #action_name] controller
+        #   An object which behaves like a controller.
+        # @param [Hash] options
+        #   A hash of options for customising the menu. See
+        #   Kin::Nav::Helper#display_navigation.
+        #
+        # @api public
+        #
+        def initialize(nav, controller, options)
+          @nav = nav
+          @current  = nav.active_item(controller)
+
+          @resource = options[:resource]
+          @inject   = options.fetch(:inject, {})
+          @guards   = options.fetch(:guard, {})
+
+          # Escape injected content.
+          @inject.each do |item_id, contents|
+            contents = Array(contents)
+            contents.map! { |v| Merb::Parse.escape_xml(v) }
+            @inject[item_id] = contents
+          end
         end
-      end
 
-      ##
-      # Transforms the menu given to +initialize+ into a string containing
-      # HTML.
-      #
-      # @return [String]
-      #   HTML containing the rendered menu. A collection of <li> elements
-      #   contained in a <ul>.
-      #
-      # @api public
-      #
-      def to_html
-        '<ul>%s</ul>' % @nav.items.map do |item|
-          trasform_item_to_html(item) if item.display?(@guards)
-        end.join("\n")
-      end
+        ##
+        # Transforms the menu given to +initialize+ into a string containing
+        # HTML.
+        #
+        # @return [String]
+        #   HTML containing the rendered menu. A collection of <li> elements
+        #   contained in a <ul>.
+        #
+        # @api public
+        #
+        def to_html
+          '<ul>%s</ul>' % @nav.items.map do |item|
+            trasform_item_to_html(item) if item.display?(@guards)
+          end.join("\n")
+        end
 
-      private # ==============================================================
+        private # ==============================================================
 
-      ##
-      # Receives an individual nav item and transforms it into HTML.
-      #
-      # @param [Kin::Nav::Item] item
-      #   The nav item to be transformed.
-      #
-      # @return [String]
-      #   A string containing an HTML <li> element.
-      #
-      # @api private
-      #
-      def trasform_item_to_html(item)
-        html_list_item(item) do
-          html_link(item) { item.label(@inject[item.id]) }
+        ##
+        # Receives an individual nav item and transforms it into HTML.
+        #
+        # @param [Kin::Nav::Item] item
+        #   The nav item to be transformed.
+        #
+        # @return [String]
+        #   A string containing an HTML <li> element.
+        #
+        # @api private
+        #
+        def trasform_item_to_html(item)
+          html_list_item(item) do
+            html_link(item) { item.label(@inject[item.id]) }
+          end
         end
-      end
+
+        ##
+        # Returns a list element, yielding to allow injection of the <a>
+        # element.
+        #
+        # @param [Kin::Nav::Item] item
+        #   The item to be transformed to HTML.
+        #
+        # @return [String]
+        #
+        # @api private
+        #
+        def html_list_item(item)
+          opts =
+            case item.id == @current
+              when true  then { :id => "nav_#{item.id}", :class => 'active' }
+              when false then { :id => "nav_#{item.id}" }
+            end
+
+          tag(:li, yield, opts)
+        end
+
+        ##
+        # Returns an anchor element containing a link for the menu item.
+        #
+        # @param [Kin::Nav::Item] item
+        #   The item to be transformed to HTML.
+        #
+        # @return [String]
+        #
+        # @api private
+        #
+        def html_link(item)
+          tag(:a, yield,
+            :href  => item.url(@resource),
+            :title => item.title(@inject[item.id])
+          )
+        end
+      end # Basic
 
       ##
-      # Returns a list element, yielding to allow injection of the <a>
-      # element.
+      # A formatter used when a navigation menu may has items which should
+      # appear on the right of the UI. Right-floated items are styled slightly
+      # differently.
       #
-      # @param [Kin::Nav::Item] item
-      #   The item to be transformed to HTML.
-      #
-      # @return [String]
-      #
-      # @api private
-      #
-      def html_list_item(item)
-        opts =
-          case item.id == @current
-            when true  then { :id => "nav_#{item.id}", :class => 'active' }
-            when false then { :id => "nav_#{item.id}" }
-          end
+      class HasRight < Basic
+        class_inheritable_accessor :right_items
 
-        tag(:li, yield, opts)
-      end
+        private
+
+        ##
+        # Receives an individual nav item and transforms it into HTML.
+        #
+        # Items specified as being a right_item will be styled differently
+        # to the others.
+        #
+        # @param [Kin::Nav::Item] item
+        #   The nav item to be transformed.
+        #
+        # @return [String]
+        #   A string containing an HTML <li> element.
+        #
+        # @api private
+        #
+        def trasform_item_to_html(item)
+          return super unless self.class.right_items.include?(item.id)
+
+          html_list_item(item) do
+            link = html_link(item) { item.label(@inject[item.id]) }
+
+            <<-HTML
+              <span class="right_border">&nbsp;</span>
+              <span class="bg">#{ link }</span>
+            HTML
+          end
+        end # transform_item_to_html
+      end # HasRight
 
       ##
-      # Returns an anchor element containing a link for the menu item.
+      # Creates a HasRight subclass.
+      #
+      # @param [Symbol] *items
+      #   Symbols matching the given items which should have the custom style
+      #   applied.
       #
-      # @param [Kin::Nav::Item] item
-      #   The item to be transformed to HTML.
+      # @return [Class]
+      #   A subclass of the HasRight formatter.
       #
-      # @return [String]
+      # @example
+      #   :formatter => Kin::Nav::Formatters::HasRight(:user, :guest)
       #
-      # @api private
+      # @api public
       #
-      def html_link(item)
-        tag(:a, yield,
-          :href  => item.url(@resource),
-          :title => item.title(@inject[item.id])
-        )
+      def self.HasRight(*items)
+        klass = Class.new(Kin::Nav::Formatters::HasRight)
+        klass.right_items = Set.new(items)
+        klass
       end
-    end # Formatter
 
+      ##
+      # A formatter used for creating subnavs.
+      #
+      class Subnav < Basic
+        private
+
+        ##
+        # Receives an individual nav item and transforms it into HTML.
+        #
+        # Wraps the contents of the link in a span.pill and span.icon to
+        # enable futher styling.
+        #
+        # @param [Kin::Nav::Item] item
+        #   The nav item to be transformed.
+        #
+        # @return [String]
+        #   A string containing an HTML <li> element.
+        #
+        # @api private
+        #
+        def trasform_item_to_html(item)
+          html_list_item(item) do
+            html_link(item) do
+              <<-HTML
+                <span class="pill">
+                  <span class="icon">
+                    #{item.label(@inject[item.id])}
+                  </span>
+                </span>
+              HTML
+            end
+          end
+        end # transform_item_to_html
+      end # Subnav
+
+    end # Formatters
   end # Nav
 end # Kin