tooltip.js.coffee in upjs-rails-0.12.3

- old
+ new

@@ -1,27 +1,61 @@
 ###*
 Tooltips
 ========
-  
-Elements that have an `up-tooltip` attribute will show the attribute
-value in a tooltip when a user hovers over the element. 
-  
-\#\#\# Incomplete documentation!
-  
-We need to work on this page:
-  
-- Show the tooltip's HTML structure and how to style the elements
-- Explain how to position tooltips using `up-position`
-- We should have a position about tooltips that contain HTML.
-  
 
+Up.js comes with a basic tooltip implementation.
+
+You can an [`up-tooltip`](/up-tooltip) attribute to any HTML tag to show a tooltip whenever
+  the user hovers over the element:
+
+      <a href="/decks" up-tooltip="Show all decks">Decks</a>
+
+
+\#\#\#\# Styling
+
+The [default styles](https://github.com/makandra/upjs/blob/master/lib/assets/stylesheets/up/tooltip.css.sass)
+show a simple tooltip with white text on a gray background.
+A gray triangle points to the element.
+
+To change the styling, simply override CSS rules for the `.up-tooltip` selector and its `:after`
+selector that is used the triangle.
+
+The HTML of a tooltip element is simply this:
+
+    <div class="up-tooltip">
+      Show all decks
+    </div>
+
+The tooltip element is appended to the end of `<body>`.
+
 @class up.tooltip
 ###
 up.tooltip = (($) ->
   
   u = up.util
 
+  ###*
+  Sets default options for future tooltips.
+
+  @method up.tooltip.config
+  @property
+  @param {String} [config.position]
+    The default position of tooltips relative to the element.
+    Can be either `"top"` or `"bottom"`.
+  @param {String} [config.openAnimation='fade-in']
+    The animation used to open a tooltip.
+  @param {String} [config.closeAnimation='fade-out']
+    The animation used to close a tooltip.
+  ###
+  config = u.config
+    position: 'top'
+    openAnimation: 'fade-in'
+    closeAnimation: 'fade-out'
+
+  reset = ->
+    config.reset()
+
   setPosition = ($link, $tooltip, position) ->
     linkBox = u.measure($link)
     tooltipBox = u.measure($tooltip)
     css = switch position
       when "top"
@@ -45,11 +79,11 @@
     $element
 
   ###*
   Opens a tooltip over the given element.
 
-      up.tooltip.open('.help', {
+      up.tooltip.attach('.help', {
         html: 'Enter multiple words or phrases'
       });
   
   @method up.tooltip.attach
   @param {Element|jQuery|String} elementOrSelector
@@ -61,13 +95,13 @@
     The animation to use when opening the tooltip.
   ###
   attach = (linkOrSelector, options = {}) ->
     $link = $(linkOrSelector)
     html = u.option(options.html, $link.attr('up-tooltip-html'))
-    text = u.option(options.text, $link.attr('up-tooltip'), $link.attr('title'))
-    position = u.option(options.position, $link.attr('up-position'), 'top')
-    animation = u.option(options.animation, u.castedAttr($link, 'up-animation'), 'fade-in')
+    text = u.option(options.text, $link.attr('up-tooltip'))
+    position = u.option(options.position, $link.attr('up-position'), config.position)
+    animation = u.option(options.animation, u.castedAttr($link, 'up-animation'), config.openAnimation)
     animateOptions = up.motion.animateOptions(options, $link)
     close()
     $tooltip = createElement(text: text, html: html)
     setPosition($link, $tooltip, position)
     up.animate($tooltip, animation, animateOptions)
@@ -81,26 +115,35 @@
     See options for [`up.animate`](/up.animate).
   ###
   close = (options) ->
     $tooltip = $('.up-tooltip')
     if $tooltip.length
-      options = u.options(options, animation: 'fade-out')
+      options = u.options(options, animation: config.closeAnimation)
       options = u.merge(options, up.motion.animateOptions(options))
       up.destroy($tooltip, options)
 
   ###*
   Displays a tooltip with text content when hovering the mouse over this element:
 
       <a href="/decks" up-tooltip="Show all decks">Decks</a>
-  
-  You can also make an existing `title` attribute appear as a tooltip:
-  
-      <a href="/decks" title="Show all decks" up-tooltip>Decks</a>
 
+  To make the tooltip appear below the element instead of above the element,
+  add an `up-position` attribute:
+
+      <a href="/decks" up-tooltip="Show all decks" up-position="bottom">Decks</a>
+
   @method [up-tooltip]
+  @param {String} [up-animation]
+    The animation used to open the tooltip.
+    Defaults to [`up.tooltip.config.openAnimation`](/up.tooltip.config).
+  @param {String} [up-position]
+    The default position of tooltips relative to the element.
+    Can be either `"top"` or `"bottom"`.
+    Defaults to [`up.tooltip.config.position`](/up.tooltip.config).
   @ujs
   ###
+
   ###*
   Displays a tooltip with HTML content when hovering the mouse over this element:
 
       <a href="/decks" up-tooltip="Show &lt;b&gt;all&lt;/b&gt; decks">Decks</a>
 
@@ -122,10 +165,13 @@
   # The framework is reset between tests, so also close
   # a currently open tooltip.
   up.on 'up:framework:reset', close
 
   # Close the tooltip when the user presses ESC.
-  up.magic.onEscape(-> close())
+  up.bus.onEscape(-> close())
+
+  # The framework is reset between tests
+  up.on 'up:framework:reset', reset
 
   attach: attach
   close: close
   open: -> u.error('up.tooltip.open no longer exists. Use up.tooltip.attach instead.')
 