README.txt

   1
   2                         IMPORTANT INSTALLATION INSTRUCTIONS
   3   ------------------------------------------------------------------------------------
   4   In order for this module to work properly with IE, you will need to download the
   5   ExplorerCanvas library, which can be found here - http://excanvas.sourceforge.net/.
   6   Place the downloaded directory 'excanvas_r3' inside the 'beautytips/other_libs' directory.
   7
   8   Other than that, you just need to turn the module on in the usual Drupal way.
   9
  10   --------------------------------------------------------------------------------------
  11                                    ABOUT THE MODULE
  12
  13   The Beautytips module provides ballon-help style tooltip for any page element.
  14   It integrates BeautyTips jQuery plugin by Jeff Robbins with Drupal.  Currently, this
  15   module allows tooltips to appear with textfields and textareas.  It also supplies hover
  16   tips for Drupal help links and advanced help links.  Most importantly, it allows developers
  17   to add their own beautytips popups to their site without having to delve into jQuery.
  18
  19   For information about the Beauty Tips jQuery plugin:
  20     http://www.lullabot.com/articles/announcing-beautytips-jquery-tooltip-plugin
  21     http://www.lullabot.com/articles/beautytips-09-release
  22
  23   To see a demonstration:
  24     http://www.lullabot.com/files/bt/bt-latest/DEMO/index.html
  25   --------------------------------------------------------------------------------------
  26                                          API
  27   --------------------------------------------------------------------------------------
  28     Beautytips has an API so that you can create your own beautytips and add them into
  29   any place on your site.  To do this, you will need to set up an array of options and
  30   then pass them along to the beautytips_add_beautytips function.  All of the options are
  31   outlined below.  This array will need to have a couple of important pieces of
  32   information, and can accept a plethora of other optional info.
  33
  34     1.  Each beautytip will need a name - distinct from other beautytips added on the
  35         web page.
  36       ex. options['bt_drupal_help_page'] = array( . . .
  37
  38     2.  Each beautytip will need a css(or jQuery) selector.  This is how the bt plugin
  39         knows where to place the tooltip.
  40       ex. 'cssSelect' => '.help-items li a'
  41
  42     3.  Each beautytip will need some text to display.  You can define what to display
  43         in 3 different ways.
  44
  45       a.  Use 'text' to directly add supply the text.  It can accept html.
  46         ex 1.  'text' => t('Here's some beautytips text to display on this page.'),
  47
  48       b.  Use 'contentSelector' to use jQuery to tell beautytips where to find the text
  49           on a page.
  50         ex 2.  'contentSelector' => '$(this).next(".description").html()',
  51         This tells beautytips to find the next item after the css selector with class
  52         'description' and use display it's html
  53
  54       c.  Use 'ajaxPath' to provide a place on another webpage that should be displayed.
  55
  56         ex 3. 'ajaxPath' => 'demo.html',
  57         This will display that particular webpage within the tooltip balloon.
  58
  59         ex 4.  'ajaxPath' => '$(this).attr("href")',
  60         This uses jQuery to find the url associated with the link that was selected with
  61         the css selector and displays it.
  62
  63         ex 5. 'ajaxPath' => array(0 => '$(this).attr("href"), 1 => '#squeeze.clear-block p'),
  64         This does the same thing as ex. 4, except it only displays the css-selected section of
  65         the page.
  66
  67       d.  If none of the above 3 options are given, the beautytips plugin will by default set
  68       'contentSelector' to be '$(this).attr('title')'.
  69
  70     4.  All other options are optional.  See the list below.
  71       ex.  'fill' => "rgb(255, 155, 55)" - sets the background color of the balloon.
  72
  73   ------------------------------------------------------------------------------------
  74     ex. Full options array and function call to add beautytips
  75
  76     $options['bt_drupal_help_page'] = array(
  77       'cssSelect' => '.help-items li a',
  78       'ajaxPath' => array(0 => "$(this).attr('href')", 1 => '.clear-block p'),
  79       'trigger' => array(0 => 'mouseover', 1 => 'click'),
  80       'width' => 350,
  81     );
  82     beautytips_add_beautytips($options);
  83   ------------------------------------------------------------------------------------
  84
  85 ******************************************************************************
  86 Beautytips options and defaults (Copied and pasted from the jQuery.bt.js file)
  87 ******************************************************************************
  88 /**
  89    * Defaults for the beauty tips
  90    *
  91    * Note this is a variable definition and not a function. So defaults can be
  92    * written for an entire page by simply redefining attributes like so:
  93    *
  94    *   jQuery.bt.defaults.width = 400;
  95    *
  96    * This would make all Beauty Tips boxes 400px wide.
  97    *
  98    * Each of these options may also be overridden during
  99    *
 100    * Can be overriden globally or at time of call.
 101    *
 102    */
 103   jQuery.bt.defaults = {
 104     trigger:         'hover',                // trigger to show/hide tip
 105                                              // use [on, off] to define separate on/off triggers
 106                                              // also use space character to allow multiple  to trigger
 107                                              // examples:
 108                                              //   ['focus', 'blur'] // focus displays, blur hides
 109                                              //   'dblclick'        // dblclick toggles on/off
 110                                              //   ['focus mouseover', 'blur mouseout'] // multiple triggers
 111                                              //   'now'             // shows/hides tip without event
 112                                              //   'none'            // use $('#selector').btOn(); and ...btOff();
 113                                              //   'hoverIntent'     // hover using hoverIntent plugin (settings below)
 114                                              // note:
 115                                              //   hoverIntent becomes default if available
 116
 117     clickAnywhereToClose: true,              // clicking anywhere outside of the tip will close it
 118     closeWhenOthersOpen: false,              // tip will be closed before another opens - stop >= 2 tips being on
 119
 120     width:            '200px',               // width of tooltip box
 121                                              //   when combined with cssStyles: {width: 'auto'}, this becomes a max-width for the text
 122     padding:          '10px',                // padding for content (get more fine grained with cssStyles)
 123     spikeGirth:       10,                    // width of spike
 124     spikeLength:      15,                    // length of spike
 125     overlap:          0,                     // spike overlap (px) onto target (can cause problems with 'hover' trigger)
 126     overlay:          false,                 // display overlay on target (use CSS to style) -- BUGGY!
 127     killTitle:        true,                  // kill title tags to avoid double tooltips
 128
 129     textzIndex:       9999,                  // z-index for the text
 130     boxzIndex:        9998,                  // z-index for the "talk" box (should always be less than textzIndex)
 131     wrapperzIndex:    9997,
 132     positions:        ['most'],              // preference of positions for tip (will use first with available space)
 133                                              // possible values 'top', 'bottom', 'left', 'right' as an array in order of
 134                                              // preference. Last value will be used if others don't have enough space.
 135                                              // or use 'most' to use the area with the most space
 136     fill:             "rgb(255, 255, 102)",  // fill color for the tooltip box, you can use any CSS-style color definition method
 137                                              // http://www.w3.org/TR/css3-color/#numerical - not all methods have been tested
 138
 139     windowMargin:     10,                    // space (px) to leave between text box and browser edge
 140
 141     strokeWidth:      1,                     // width of stroke around box, **set to 0 for no stroke**
 142     strokeStyle:      "#000",                // color/alpha of stroke
 143
 144     cornerRadius:     5,                     // radius of corners (px), set to 0 for square corners
 145
 146                       // following values are on a scale of 0 to 1 with .5 being centered
 147
 148     centerPointX:     .5,                    // the spike extends from center of the target edge to this point
 149     centerPointY:     .5,                    // defined by percentage horizontal (x) and vertical (y)
 150
 151     shadow:           false,                 // use drop shadow? (only displays in Safari and FF 3.1) - experimental
 152     shadowOffsetX:    2,                     // shadow offset x (px)
 153     shadowOffsetY:    2,                     // shadow offset y (px)
 154     shadowBlur:       3,                     // shadow blur (px)
 155     shadowColor:      "#000",                // shadow color/alpha
 156     shadowOverlap:   false,                  // when shadows overlap the target element it can cause problem with hovering
 157                                              // set this to true to overlap or set to a numeric value to define the amount of overlap
 158     noShadowOpts:     {strokeStyle: '#999'},  // use this to define 'fall-back' options for browsers which don't support drop shadows
 159
 160     animate:          false,                 // animate show/hide of box - EXPERIMENTAL (buggy in IE)
 161     distance:         15,                    // distance of animation movement (px)
 162     easing:           'swing',               // animation easing
 163     speed:            200,                   // speed (ms) of animation
 164
 165     cssClass:         '',                    // CSS class to add to the box wrapper div (of the TIP)
 166     cssStyles:        {},                    // styles to add the text box
 167                                              //   example: {fontFamily: 'Georgia, Times, serif', fontWeight: 'bold'}
 168
 169     activeClass:      'bt-active',           // class added to TARGET element when its BeautyTip is active
 170
 171     contentSelector:  "$(this).attr('title')", // if there is no content argument, use this selector to retrieve the title
 172
 173     ajaxPath:         null,                  // if using ajax request for content, this contains url and (opt) selector
 174                                              // this will override content and contentSelector
 175                                              // examples (see jQuery load() function):
 176                                              //   '/demo.html'
 177                                              //   '/help/ajax/snip'
 178                                              //   '/help/existing/full div#content'
 179
 180                                              // ajaxPath can also be defined as an array
 181                                              // in which case, the first value will be parsed as a jQuery selector
 182                                              // the result of which will be used as the ajaxPath
 183                                              // the second (optional) value is the content selector as above
 184                                              // examples:
 185                                              //    ["$(this).attr('href')", 'div#content']
 186                                              //    ["$(this).parents('.wrapper').find('.title').attr('href')"]
 187                                              //    ["$('#some-element').val()"]
 188
 189     ajaxError:        '<strong>ERROR:</strong> <em>%error</em>',
 190                                              // error text, use "%error" to insert error from server
 191     ajaxLoading:     '<blink>Loading...</blink>',  // yes folks, it's the blink tag!
 192     ajaxData:         {},                    // key/value pairs
 193     ajaxType:         'GET',                 // 'GET' or 'POST'
 194     ajaxCache:        true,                  // cache ajax results and do not send request to same url multiple times
 195     ajaxOpts:         {},                    // any other ajax options - timeout, passwords, processing functions, etc...
 196                                              // see http://docs.jquery.com/Ajax/jQuery.ajax#options
 197
 198     preShow:          function(){return;},       // function to run before popup is built and displayed
 199     postShow:         function(){return;},       // function to run after popup is built and displayed
 200     preHide:          function(){return;},       // function to run before popup is removed
 201     postHide:         function(){return;},       // function to run after popup is removed
 202
 203     hoverIntentOpts:  {                          // options for hoverIntent (if installed)
 204                         interval: 300,           // http://cherne.net/brian/resources/jquery.hoverIntent.html
 205                         timeout: 500
 206                       }
 207
 208   }; // </ jQuery.bt.defaults >