= Michael Hintbuble

Hiya.

I'm Michael Hintbuble.  A lot of people confuse me with the singer who rose to fame singing jazz
standards, but I'm a different guy altogether.  

Don't get me wrong, that Michael and I are into a lot of the same things, like dating Emily Blunt and 
opening fictitious restaurants with Jon Hamm. But while that Michael spent his career focused on smooth 
vocal stylings and making ladies of all nationalities swoon, I only care about one thing.

<b>Freakin' Hint Bubbles</b>.  

If you're a Rails developer who wants to use hint bubbles but doesn't want to mess with Javascript, I
suggest you get yourself a firmer grip on your knickers.

Check it.  If you want my hint bubble anchored to an element in one of your views, here's what you do:

    # Define the target
    <div id="restaurant_header">Hamm and Buble</div>
    
    # Create and attach the bubble
    <%= render_bubble :restaurant_header, 
                      :position => :right, :event_names => [:mouseover], 
                      :partial  => "map",  :locals      => { :address => @restaurant.address } %>

That's pretty much it.  Did you notice how <tt>render_bubble</tt> takes the same options as 
<tt>render</tt>?  The content for your bubble can just be a regular old partial.

Boom.

What's that, you want a few more details?  You got it, bro.

<tt>render_bubble</tt> always needs the unique id for the target element as its first argument.  After 
that, it will take the same options as <tt>ActionController::Base#render</tt>.  It'll also take a few 
more, namely:

* <tt>:class</tt> - an additional css style to assign to the outermost div container (facilitates multiple stylings)
* <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 (accepts focus and/or mouseover)
* <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

Here's an example using the <tt>before_show</tt> option with block notation:

    # Define the target
    <div id="cry_for_help">I have a feeling that he's standing right behind me.</div>
    
    # Create and attach the bubble
    <%= render_bubble :cry_for_help, :position => :bottom, :before_show => "function() { JonHamm.eyes.goBlack(); }" %>
      <div>You are on the thinnest of ice.</div>
    <% end %>

If you need more help than that, maybe you should just look at the source code.  There are a ton of comments 
in there.

    
Cheers,

Michael Hintbuble



== Multiple Hint Bubble Styles

If you need to style more than one kind of hint bubble (e.g., one style for tooltips, one style for errors), just
use the <tt>:class</tt> option to append a css class name on the outermost div.  That'll give you a logical anchor 
around which you can restyle all the interior classes.

Please note that the blocking iframe is automatically given an additional class name equal to the outermost div's class name plus 
the string "_frame".  

By default, the top-level class assignments are "michael_hintbuble_bubble" and "michael_hintbuble_bubble_frame". 

If you set the <tt>:class</tt> option to <tt>:error_bubble</tt>, the top-level class assignments will be 
"michael_hintbuble_bubble error_bubble" and "michael_hintbuble_bubble_frame error_bubble_frame".



== Positioning Notes

Windows get resized, documents and divs scroll, stuff happens.  Sometimes the area in which you intended for a 
hint bubble to appear ends up off the viewport.  Which kind of screws the whole hint bubble UI pattern.

Good thing I'm so friendly.  Here's what I can do to help.  

If you tell me to position the bubble to one side of the target and the bubble can't fit in the viewport over 
there, I'll just place it on the opposite side.  If it doesn't fit over there either, I'll just give up and
put it where you told me in the first place.  I'm not a mindreader, you know.



== IE6 Support

I'm not what you'd call a huge fan of IE6, so I don't provide a blocking 
iframe for my hint bubbles by default.  But I can.  You just need to ask nicely.

At the top of the generated javascript file, just change the obviously-named property 
hanging	right off of the main namespace.  Like this.

	MichaelHintbuble.SUPPORT_IE6_BULLSHIT = true;

That's it. I do the rest.



== Helpful Links

* <b>Repository:</b> http://github.com/coroutine/michael_hintbuble
* <b>Gem:</b> http://rubygems.org/gems/michael_hintbuble
* <b>Authors:</b> http://coroutine.com



== Prerequisites

If you want to come fly with me, you'll need to invite the other members of my trio, Prototype and Scriptaculous.  

But since I was designed as a Rails extension, chances are you already have my bandmates
in the mix.

* <b>Prototype:</b> http://prototypejs.org
* <b>Scriptaculous:</b> http://script.aculo.us



== Installation & Generators (Rails 3)

Install me from RubyGems.org by adding a gem dependency to your Gemfile.  Bundler does 
the rest.

	gem "michael_hintbuble"
	
	$ bundle install

Then generate the required javascript file and the starter stylesheet and image.

	$ rails g michael_hintbuble
	


== Installation & Generators (Rails 2)

Install me from RubyGems.org and add a gem dependency in the appropriate file.

	$ gem install michael_hintbuble

Or install me as a plugin.

	$ script/plugin install git://github.com/coroutine/michael_hintbuble.git

Either way, then generate the required javascript file and the starter 
stylesheet and image.

	$ script/generate michael_hintbuble



== Gemroll

If you think I'm awesome, you should check out my soulmate 
{Kenny Dialoggins}[http://github.com/coroutine/kenny_dialoggins].

Other gems by Coroutine include:

* {acts_as_current}[http://github.com/coroutine/acts_as_current]
* {acts_as_label}[http://github.com/coroutine/acts_as_label]
* {acts_as_list_with_sti_support}[http://github.com/coroutine/acts_as_list_with_sti_support]
* {delayed_form_observer}[http://github.com/coroutine/delayed_form_observer]
* {tiny_navigation}[http://github.com/coroutine/tiny_navigation]



== License

Copyright (c) 2010 {Coroutine LLC}[http://coroutine.com].

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.