michael_hintbuble 1.0.0

data/lib/michael_hintbuble/helpers.rb

@@ -0,0 +1,171 @@
+module Coroutine                #:nodoc:
+  module MichaelHintbuble       #:nodoc:
+    module Helpers              #:nodoc:
+      
+      # This method returns a javascript tag containing the hint bubble initialization logic. The first argument
+      # to this method is <tt>target_id</tt>, the id of the html element to which the hint bubble is anchored.  
+      # The target_id is required and should be unique (duh). Further options may be provided; those that 
+      # are specific to the hint bubble are:
+      #
+      # * <tt>:class</tt> - the css style to assign to the outermost div container (defaults to "michael_hintbuble_bubble")
+      # * <tt>:style</tt> - additional css style assignments for outermost div container (defaults to "")
+      # * <tt>:position</tt> - css-style value that specifies the hint bubble's relative position, e.g., top, bottom, right, or left (defaults to right)
+      # * <tt>:event_names</tt> - an array of strings specifying the events that should trigger the display of the hint bubble
+      # * <tt>:before_show</tt> - a Javascript function that will be invoked before the hint bubble is shown
+      # * <tt>:after_show</tt> - a Javascript function that will be invoked after the hint bubble has been shown
+      # * <tt>:before_hide</tt> - a Javascript function that will be invoked before the hint bubble is hidden
+      # * <tt>:after_hide</tt> - a Javascript function that will be invoked after the hint bubble has been hidden
+      # * <tt>&block</tt> - HTML markup that will be automatically converted to render's inline option
+      # 
+      # All remaining options are the same as the options available to ActionController::Base#render.  Please
+      # see the documentation for ActionController::Base#render for further details.
+      # 
+      # ==== Events
+      #
+      # The library manages repositioning the hint bubble in response to window resizing and scrolling events automatically.
+      # You do not need to specify <tt>resize</tt> or <tt>scroll</tt> in the optional event names array.
+      #
+      # The library defaults to trapping mouse gestures, but it is capable of trapping focus events in addition
+      # to or in place of mouse events.  When specifying events, you need only reference the positive action: the
+      # library can infer the corresponding action to toggle off the tooltip.
+      #
+      # Valid entries for the events array are any combination of the following options:
+      #
+      # * <tt>"focus"</tt>
+      # * <tt>"mouseover"</tt>
+      #
+      #
+      # ==== Example
+      # 
+      # # Generates: 
+      # #
+      # # <script type="text/javascript">
+      # #   //<![CDATA[
+      # #     MichaelHintbuble.Bubble.instances["foo_target_id"] = new MichaelHintbuble.Bubble("What up, foo?", { "event_names": ["mouseover"], "position": "top center" });
+      # #   //]]>
+      # # </script>
+      # <%= render_bubble :foo_target_id, :content => "What up, foo?", :position => "top center" %>
+      #   
+      # In this case, a simple hint bubble is produced with the specified text content.  The bubble responds to mouseover/mouseout
+      # events and centers itself above the target element when shown.
+      # 
+      #
+      # ==== Example
+      # 
+      # # Generates: 
+      # #
+      # # <script type="text/javascript">
+      # #   //<![CDATA[
+      # #     MichaelHintbuble.Bubble.instances["bar_target_id"] = new MichaelHintbuble.Bubble("<ul><li>Item 1</li><li>Item 2</li></ul>", { "event_names": ["focus"], "position": "center left" });
+      # #   //]]>
+      # # </script>
+      # <%= render_bubble :bar_target_id, :event_names => ["focus"], :position => "center left" %>
+      #   <ul>
+      #     <li>Item 1</li>
+      #     <li>Item 2</li>
+      #   </ul>
+      # <% end %>
+      #   
+      # In this case, a slightly more complex hint bubble is produced with the specified markup.  The bubble responds to focus/blur
+      # events and positions itself to the left of the target.
+      #
+      def render_bubble(target_id, options = {}, &block)
+        options[:inline]    = capture(&block) if block_given?
+        render_options      = extract_bubble_render_options(options, &block)
+        javascript_options  = bubble_options_to_js(extract_bubble_javascript_options(options))
+        
+        content = escape_javascript(render(options))
+        
+        raise "You gotta specify a target id to register a hint bubble, baby."  unless target_id
+        raise "You gotta provide content to register a hint bubble, baby."      unless content
+        
+        javascript_tag "Event.observe(window, 'load', function() { MichaelHintbuble.Bubble.instances['#{target_id}'] = new MichaelHintbuble.Bubble('#{target_id}', '#{content}', #{javascript_options}) });"
+      end
+            
+            
+      # This method returns a Javascript string that will show the bubble attached to the supplied
+      # target id.
+      #
+      def show_bubble(target_id)
+        "MichaelHintbuble.Bubble.show('#{target_id}');"
+      end
+      
+      
+      # This method returns a Javascript string that will hide the bubble attached to the supplied
+      # target id.
+      #
+      def hide_bubble(target_id)
+        "MichaelHintbuble.Bubble.hide('#{target_id}');"
+      end
+      
+      
+      
+      private
+      
+      # This method returns an array of javascript option keys supported by the accompanying
+      # javascript library.
+      #
+      def bubble_javascript_option_keys
+        [:class, :style, :position, :event_names, :before_show, :after_show, :before_hide, :after_hide]
+      end
+      
+      
+      # This method converts ruby hashes using underscore notation to js strings using camelcase 
+      # notation, which is more common in javascript.
+      #
+      def bubble_options_to_js(options={})
+        js_kv_pairs = []
+        sorted_keys = options.keys.map { |k| k.to_s }.sort.map { |s| s.to_sym }
+          
+        sorted_keys.each do |key|
+          js_key   = key.to_s.camelcase(:lower)
+          js_value = "null" 
+          
+          unless options[key].empty?
+            case key
+              when :before_show, :after_show, :before_hide, :after_hide
+                js_value = "#{options[key]}" 
+              when :event_names
+                js_value = "['" + options[key].join("','") + "']"
+              else
+                js_value = "'#{options[key]}'" 
+            end
+          end
+          
+          js_kv_pairs << "#{js_key}:#{js_value}"
+        end
+        
+        "{#{js_kv_pairs.join(',')}}"
+      end
+      
+      
+      # This method returns a hash with javascript options. It also inspects the supplied options 
+      # and adds defaults as necessary.
+      #
+      def extract_bubble_javascript_options(options)
+        js_options = options.reject { |k,v| !bubble_javascript_option_keys.include?(k) }
+        
+        js_options[:class]        = "michael_hintbuble_bubble"  if js_options[:class].blank?
+        js_options[:position]     = "right"                     if js_options[:position].blank?
+        js_options[:event_names]  = []                          if js_options[:event_names].blank?
+        
+        js_options[:class]        = js_options[:class].to_s
+        js_options[:event_names]  = js_options[:event_names].uniq.map { |en| en.to_s }
+        js_options[:event_names] << "mouseover"                 if     js_options[:event_names].empty?
+        js_options[:event_names] << "resize"                    unless js_options[:event_names].include?("resize")
+        js_options[:event_names] << "scroll"                    unless js_options[:event_names].include?("scroll")
+        
+        js_options
+      end
+      
+      
+      # This method returns a hash with rendering options. It also inspects the supplied options 
+      # and adds defaults as necessary.
+      #
+      def extract_bubble_render_options(options)
+        options.reject { |k,v| bubble_javascript_option_keys.include?(k) }
+      end
+      
+    end
+  end
+end

data/lib/michael_hintbuble.rb

@@ -0,0 +1,10 @@
+# external gems
+require "action_pack"
+
+
+# helpers
+require File.dirname(__FILE__) + "/michael_hintbuble/helpers"
+
+
+# add action view extensions
+ActionView::Base.module_eval { include Coroutine::MichaelHintbuble::Helpers }

data/michael_hintbuble.gemspec

@@ -0,0 +1,67 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{michael_hintbuble}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Coroutine", "Tim Lowrimore", "John Dugan"]
+  s.date = %q{2010-10-10}
+  s.description = %q{Michael HintBuble allows you to generate hint bubbles and tooltips in Rails applications using the same syntax used for rendering templates.}
+  s.email = %q{gems@coroutine.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     ".specification",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "generators/michael_hintbuble/michael_hintbuble_generator.rb",
+     "generators/michael_hintbuble/templates/michael_hintbuble.css",
+     "generators/michael_hintbuble/templates/michael_hintbuble.js",
+     "generators/michael_hintbuble/templates/michael_hintbuble_pointer.png",
+     "init.rb",
+     "lib/generators/michael_hintbuble/michael_hintbuble_generator.rb",
+     "lib/generators/michael_hintbuble/templates/michael_hintbuble.css",
+     "lib/generators/michael_hintbuble/templates/michael_hintbuble.js",
+     "lib/generators/michael_hintbuble/templates/michael_hintbuble_pointer.png",
+     "lib/michael_hintbuble.rb",
+     "lib/michael_hintbuble/helpers.rb",
+     "michael_hintbuble.gemspec",
+     "rails/init.rb",
+     "test/michael_hintbuble/helpers_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/coroutine/michael_hintbuble}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Dead simple, beautiful hint bubbles for Rails.}
+  s.test_files = [
+    "test/michael_hintbuble/helpers_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<actionpack>, [">= 2.3.4"])
+      s.add_development_dependency(%q<activesupport>, [">= 2.3.4"])
+    else
+      s.add_dependency(%q<actionpack>, [">= 2.3.4"])
+      s.add_dependency(%q<activesupport>, [">= 2.3.4"])
+    end
+  else
+    s.add_dependency(%q<actionpack>, [">= 2.3.4"])
+    s.add_dependency(%q<activesupport>, [">= 2.3.4"])
+  end
+end
+

data/rails/init.rb

@@ -0,0 +1 @@
+require "michael_hintbuble"

data/test/michael_hintbuble/helpers_test.rb

@@ -0,0 +1,156 @@
+#---------------------------------------------------------
+# Requirements
+#---------------------------------------------------------
+
+# all generic stuff required by test helper
+require "test/test_helper"
+
+
+
+#---------------------------------------------------------
+# Class Definitions
+#---------------------------------------------------------
+
+class TestView < ActionView::Base
+end
+
+
+
+#---------------------------------------------------------
+# Tests
+#---------------------------------------------------------
+
+class MichaelHintbubleHelpersTest < ActionView::TestCase
+  
+  def setup
+    @view = TestView.new
+  end
+  
+  
+  def test_composition
+    assert @view.respond_to?(:render_bubble,                      false)
+    assert @view.respond_to?(:show_bubble,                        false)
+    assert @view.respond_to?(:hide_bubble,                        false)
+    assert @view.respond_to?(:bubble_javascript_option_keys,      true)
+    assert @view.respond_to?(:bubble_options_to_js,               true)
+    assert @view.respond_to?(:extract_bubble_javascript_options,  true)
+    assert @view.respond_to?(:extract_bubble_render_options,      true)
+  end
+  
+  
+  #---------------------------------------------------------
+  # Public methods
+  #---------------------------------------------------------
+
+  def test_render_bubble_with_simple_options
+    text            = "Who wants to play volleyball on a court with a four-foot net?"
+    default_options = "{class:'michael_hintbuble_bubble',eventNames:['mouseover','resize','scroll'],position:'right'}" 
+    
+    expected  = "<script type=\"text/javascript\">\n" \
+                "//<![CDATA[\n" \
+                "Event.observe(window, 'load', function() { MichaelHintbuble.Bubble.instances['come_fly_with_me'] = new MichaelHintbuble.Bubble('come_fly_with_me', '#{text}', #{default_options}) });\n" \
+                "//]]>\n" \
+                "</script>"
+    actual    = @view.render_bubble(:come_fly_with_me, :text => text)
+      
+    assert_equal expected, actual
+  end
+  
+  
+  def test_show_bubble
+    expected  = "MichaelHintbuble.Bubble.show('come_fly_with_me');"
+    actual    = @view.show_bubble(:come_fly_with_me)
+    
+    assert_equal expected, actual
+  end
+  
+  
+  def test_hide_dialog
+    expected  = "MichaelHintbuble.Bubble.hide('come_fly_with_me');"
+    actual    = @view.hide_bubble(:come_fly_with_me)
+    
+    assert_equal expected, actual
+  end
+  
+  
+  
+  #---------------------------------------------------------
+  # Public methods
+  #---------------------------------------------------------
+
+  def test_bubble_javascript_option_keys
+    expected  = [:class, :style, :position, :event_names, :before_show, :after_show, :before_hide, :after_hide]
+    actual    = @view.send(:bubble_javascript_option_keys)
+
+    assert_equal expected, actual
+  end
+  
+  
+  def test_bubble_options_to_js
+    options = { 
+                :class        => "error_container",
+                :position     => "top",
+                :event_names  => ["mouseover","resize","scroll"],
+                :before_show  => "function{ alert('hello, world!'); }", 
+                :after_show   => "function{ alert('goodbye, world!'); }"
+              }
+    
+    expected  = "{"                                               + 
+                "afterShow:function{ alert('goodbye, world!'); }" + "," +
+                "beforeShow:function{ alert('hello, world!'); }"  + "," +
+                "class:'error_container'"                         + "," +
+                "eventNames:['mouseover','resize','scroll']"      + "," +
+                "position:'top'"                                  + 
+                "}"
+    actual    = @view.send(:bubble_options_to_js, options)
+
+    assert_equal expected, actual
+  end
+  
+  
+  def test_extract_bubble_javascript_options
+    options     = { :class => "my_class", :event_names => ["focus", "resize", "scroll"], :position => "right", :text => "Text" }
+    js_options  = @view.send(:extract_bubble_javascript_options, options)
+    
+    assert_equal  true,   js_options.has_key?(:class)
+    assert_equal  true,   js_options.has_key?(:event_names)
+    assert_equal  true,   js_options.has_key?(:position)
+    assert_equal  false,  js_options.has_key?(:text)
+    
+    assert_equal  "my_class",                     js_options[:class]
+    assert_equal  ["focus", "resize", "scroll"],  js_options[:event_names]
+    assert_equal  "right",                        js_options[:position]
+  end
+  def test_extract_bubble_javascript_options_for_default_class
+    options     = { :event_names => ["focus", "resize", "scroll"], :position => "top right", :text => "Text" }
+    js_options  = @view.send(:extract_bubble_javascript_options, options)
+    
+    assert_equal  "michael_hintbuble_bubble",  js_options[:class]
+  end
+  def test_extract_bubble_javascript_options_for_default_event_names
+    options     = { :class => "my_class", :position => "top right", :text => "Text" }
+    js_options  = @view.send(:extract_bubble_javascript_options, options)
+    
+    assert_equal  ["mouseover", "resize", "scroll"],  js_options[:event_names]
+  end
+  def test_extract_bubble_javascript_options_for_default_position
+    options     = { :class => "my_class", :event_names => ["focus", "resize", "scroll"], :text => "Text" }
+    js_options  = @view.send(:extract_bubble_javascript_options, options)
+    
+    assert_equal  "right",  js_options[:position]
+  end
+  
+  
+  def test_extract_bubble_render_options
+    options         = { :class => :my_class, :event_names => [:focus, :resize, :scroll], :position => "top right", :text => "Text" }
+    render_options  = @view.send(:extract_bubble_render_options, options)
+    
+    assert_equal  false,  render_options.has_key?(:class)
+    assert_equal  false,  render_options.has_key?(:event_names)
+    assert_equal  false,  render_options.has_key?(:position)
+    assert_equal  true,   render_options.has_key?(:text)
+    
+    assert_equal  "Text", render_options[:text]
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,16 @@
+#----------------------------------------------------------
+# Requirements
+#----------------------------------------------------------
+
+# rails stuff
+require "rubygems"
+require "active_support"
+require "active_support/test_case"
+require "action_controller"
+require "action_controller/test_case"
+require "action_view"
+require "action_view/test_case"
+require "test/unit"
+
+# the plugin itself
+require "#{File.dirname(__FILE__)}/../init"

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification 
+name: michael_hintbuble
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Coroutine
+- Tim Lowrimore
+- John Dugan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-10 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: actionpack
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 3
+        - 4
+        version: 2.3.4
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 3
+        - 4
+        version: 2.3.4
+  type: :development
+  version_requirements: *id002
+description: Michael HintBuble allows you to generate hint bubbles and tooltips in Rails applications using the same syntax used for rendering templates.
+email: gems@coroutine.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- .specification
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- generators/michael_hintbuble/michael_hintbuble_generator.rb
+- generators/michael_hintbuble/templates/michael_hintbuble.css
+- generators/michael_hintbuble/templates/michael_hintbuble.js
+- generators/michael_hintbuble/templates/michael_hintbuble_pointer.png
+- init.rb
+- lib/generators/michael_hintbuble/michael_hintbuble_generator.rb
+- lib/generators/michael_hintbuble/templates/michael_hintbuble.css
+- lib/generators/michael_hintbuble/templates/michael_hintbuble.js
+- lib/generators/michael_hintbuble/templates/michael_hintbuble_pointer.png
+- lib/michael_hintbuble.rb
+- lib/michael_hintbuble/helpers.rb
+- michael_hintbuble.gemspec
+- rails/init.rb
+- test/michael_hintbuble/helpers_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/coroutine/michael_hintbuble
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Dead simple, beautiful hint bubbles for Rails.
+test_files: 
+- test/michael_hintbuble/helpers_test.rb
+- test/test_helper.rb