afb-client/bower_components/tether/docs/intro.md

   1 <script src="tether.js"></script>
   2 <script src="js/markAttachment.js"></script>
   3 <script src="docs/js/intro.js"></script>
   4 <link rel="stylesheet" href="docs/css/intro.css"></link>
   5
   6 Tether
   7 ======
   8
   9 Tether is a JavaScript library for efficiently making an absolutely positioned
  10 element stay next to another element on the page. For example, you might
  11 want a tooltip or dialog to open, and remain, next to the relevant item
  12 on the page.
  13
  14 Tether includes the ability to constrain the element within the viewport, its
  15 scroll parent, any other element on the page, or a fixed bounding box.  When it
  16 exceeds those constraints it can be pinned to the edge, flip to the other
  17 side of its target, or hide itself.
  18
  19 Tether optimizes its location placement to result in the minimum amount of
  20 'jankyness' as the page is scrolled and resized.  The page can maintain 60fps
  21 scrolling even with dozens or hundreds of tethers on screen (pop open the
  22 devtools timeline as you scroll this page).
  23
  24 Tether is 5kb minified and gzipped, and supports IE9+, and all modern
  25 browsers.
  26
  27 <h2 class="projects-header">Projects Built With Tether</h2>
  28 <p class="projects-paragraph">
  29 <a href="http://github.hubspot.com/select/docs/welcome"><span>Select</span><img src="http://github.hubspot.com/os-icons/select-icon.png" /></a>
  30 <a href="http://github.hubspot.com/drop/docs/welcome"><span>Drop</span><img src="http://github.hubspot.com/os-icons/drop-icon.png" /></a>
  31 <a href="http://github.hubspot.com/tooltip/docs/welcome"><span>Tooltip</span><img src="http://github.hubspot.com/os-icons/tooltip-icon.png" /></a>
  32 <a href="http://github.hubspot.com/shepherd/docs/welcome"><span>Shepherd</span><img src="http://github.hubspot.com/os-icons/shepherd-icon.png" /></a>
  33 </p>
  34
  35 Usage
  36 -----
  37
  38 The element to be moved is called the 'element'.
  39 The element in the page it's to be attached to is called the 'target'.
  40
  41 To use Tether, you define a point on the target and a point on the element.
  42 Tether moves the element to keep those two points on top of each other.
  43
  44 That point is called the attachment (we've marked it in the examples with
  45 a red <span class="attachment-mark"></span>).  For example, if you'd like
  46 the element to sit on the left of the target:
  47
  48 <pre class="pre-with-output"><code class="lang-javascript" data-example='usage'>new Tether({
  49   element: yellowBox,
  50   target: greenBox,
  51   attachment: 'top right',
  52   targetAttachment: 'top left'
  53 });
  54 </code></pre><output data-example='usage'></output>
  55
  56 Attachment
  57 ----------
  58
  59 You can move the attachment points of both the element and the target.
  60
  61 For example, lets move the element's attachment:
  62
  63 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
  64   element: yellowBox,
  65   target: greenBox,
  66   attachment: <mark>'bottom left'</mark>,
  67   targetAttachment: 'top left'
  68 });
  69 </code></pre><output></output>
  70
  71 We can also change the target's attachment point:
  72
  73 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
  74   element: yellowBox,
  75   target: greenBox,
  76   attachment: 'bottom left',
  77   targetAttachment: <mark>'bottom right'</mark>
  78 });
  79 </code></pre><output></output>
  80
  81 There are two more attachment points we haven't seen yet, center and middle:
  82
  83 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
  84   element: yellowBox,
  85   target: greenBox,
  86   attachment: <mark>'middle center'</mark>,
  87   targetAttachment: <mark>'middle center'</mark>
  88 });
  89 </code></pre><output></output>
  90
  91 All told, Tether provides six built in attachment positions:
  92
  93 - left
  94 - center
  95 - right
  96 - top
  97 - middle
  98 - bottom
  99
 100 The syntax of the attachment properties is: `"vertical-attachment horizontal-attachment"`
 101
 102 You must always supply an `attachment`.  If you don't supply a `target-attachment`, it is
 103 assumed to be the mirror image of `attachment`.
 104
 105 ### Offset
 106
 107 The six attachment points we provide are not always enough to place the element
 108 exactly where you want it.  To correct this, we provide two more properties,
 109 `offset` and `targetOffset`.
 110
 111 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 112   element: yellowBox,
 113   target: greenBox,
 114   attachment: 'top right',
 115   targetAttachment: 'top left',
 116   <mark>offset: '0 10px'</mark>
 117 });
 118 </code></pre><output></output>
 119
 120 As you can see, we've moved the attachment point of the element 10px to the right.
 121 We can also move the attachment point of the target:
 122
 123 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 124   element: yellowBox,
 125   target: greenBox,
 126   attachment: 'top right',
 127   targetAttachment: 'top left',
 128   offset: '0 10px',
 129   <mark>targetOffset: '20px 0'</mark>
 130 });
 131 </code></pre><output></output>
 132
 133 The offset properties also accept percentages. Percentages in `offset` refer to
 134 the height and width of the element, `targetOffset` the height and width of
 135 the target.
 136
 137 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 138   element: yellowBox,
 139   target: greenBox,
 140   attachment: 'top right',
 141   targetAttachment: 'top left',
 142   targetOffset: <mark>'0 75%'</mark>
 143 });
 144 </code></pre><output></output>
 145
 146 The syntax of the offset properties is `"vertical-offset horizontal-offset"`
 147
 148 Tether offers a couple of special attachments, using the `targetModifier`
 149 option:
 150
 151 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 152   element: yellowBox,
 153   target: scrollBox,
 154   attachment: 'middle right',
 155   targetAttachment: 'middle left',
 156   targetModifier: 'scroll-handle'
 157 });
 158 </code></pre><output></output>
 159
 160 Set the target to `document.body` to have the element follow the page's scroll bar.
 161
 162 The `targetModifier` `visible` can be used to attach an element to the visible part
 163 of an element:
 164
 165 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 166   element: yellowBox,
 167   target: document.body,
 168   attachment: 'middle center',
 169   targetAttachment: 'middle center',
 170   <mark>targetModifier: 'visible'</mark>
 171 });
 172 </code></pre><output deactivated></output>
 173
 174 <pre class="pre-with-output"><code class="lang-javascript" data-example="scroll-visible">new Tether({
 175   element: yellowBox,
 176   <mark>target: scrollBox</mark>,
 177   attachment: 'middle center',
 178   targetAttachment: 'middle center',
 179   targetModifier: 'visible'
 180 });
 181 </code></pre><output class="no-green scroll-page" data-example="scroll-visible"></output>
 182
 183 Constraints
 184 -----------
 185
 186 If you have tried any of the previous examples, you'll notice that it's pretty
 187 easy to scroll the regions in such a way that the element is hanging out on
 188 its own, with no target in sight.
 189
 190 Constraints allow you to control what happens when the tethered element would
 191 have to fall outside of a defined region to maintain the attachment.
 192
 193 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 194   element: yellowBox,
 195   target: greenBox,
 196   attachment: 'middle left',
 197   targetAttachment: 'middle left',
 198   <mark>constraints</mark>: [
 199     {
 200       to: 'scrollParent',
 201       pin: true
 202     }
 203   ]
 204 });
 205 </code></pre><output></output>
 206
 207 We've created a constraint which will keep the element within its scroll
 208 parent by 'pinning' it to the edges if it tries to escape.  For the sake
 209 of the example, we're also highlighting the pinned edge in red.
 210
 211 Specify an array of sides if you'd only like to pin those edges:
 212
 213 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 214   element: yellowBox,
 215   target: greenBox,
 216   attachment: 'middle left',
 217   targetAttachment: 'middle left',
 218   constraints: [
 219     {
 220       to: 'scrollParent',
 221       pin: <mark>['top']</mark>
 222     }
 223   ]
 224 });
 225 </code></pre><output></output>
 226
 227 You might want to allow the element to change its attachment, if doing so
 228 would keep more of it within its assigned region:
 229
 230 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 231   element: yellowBox,
 232   target: greenBox,
 233   attachment: 'top left',
 234   targetAttachment: 'bottom left',
 235   constraints: [
 236     {
 237       to: 'scrollParent',
 238       <mark>attachment: 'together'</mark>
 239     }
 240   ]
 241 });
 242 </code></pre><output></output>
 243
 244 If you scroll the example a bit, you'll see it flip the attachment when necessary.
 245 You can combine `pin` and `attachment` as well:
 246
 247 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 248   element: yellowBox,
 249   target: greenBox,
 250   attachment: 'top left',
 251   targetAttachment: 'bottom left',
 252   constraints: [
 253     {
 254       to: 'scrollParent',
 255       attachment: 'together',
 256       <mark>pin: true</mark>
 257     }
 258   ]
 259 });
 260 </code></pre><output></output>
 261
 262 Attachment will accept any of these values:
 263
 264 - `element`: Only change the element's attachment
 265 - `target`: Only change the target's attachment
 266 - `both`: Change either's attachment (or both), as needed
 267 - `together`: Change both the element's and target's attachment at the same time (to
 268 'flip' the element to the other side of the attachment)
 269 - `none`: Don't allow changes to attachment (the default)
 270
 271 Together is the option you will use most commonly:
 272
 273 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 274   element: yellowBox,
 275   target: greenBox,
 276   attachment: 'top right',
 277   targetAttachment: 'bottom left',
 278   constraints: [
 279     {
 280       to: 'scrollParent',
 281       attachment: <mark>'together'</mark>
 282     }
 283   ]
 284 });
 285 </code></pre><output></output>
 286
 287 You can also provide different settings for the horizontal
 288 and vertical attachments:
 289
 290 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 291   element: yellowBox,
 292   target: greenBox,
 293   attachment: 'top left',
 294   targetAttachment: 'bottom left',
 295   constraints: [
 296     {
 297       to: 'scrollParent',
 298       attachment: <mark>'together none'</mark>
 299     }
 300   ]
 301 });
 302 </code></pre><output></output>
 303
 304 Whenever the element is out of the constrained area, we add the `tether-out-of-bounds`
 305 class to it.  If you add some CSS to make items with that class `display: none`, the
 306 tether will hide.
 307
 308 <pre class="pre-with-output"><code class="lang-javascript" data-example="hide">new Tether({
 309   element: yellowBox,
 310   target: greenBox,
 311   attachment: 'middle center',
 312   targetAttachment: 'middle center',
 313   constraints: [
 314     {
 315       to: 'scrollParent'
 316     }
 317   ]
 318 });
 319 </code></pre><output data-example="hide"></output>
 320
 321 You can also constrain the element to the viewport, you'll have to scroll the
 322 page to see this one.
 323
 324 <pre class="pre-with-output"><code class="lang-javascript" data-example="window">new Tether({
 325   element: yellowBox,
 326   target: greenBox,
 327   attachment: 'top left',
 328   targetAttachment: 'bottom left',
 329   constraints: [
 330     {
 331       to: <mark>'window'</mark>,
 332       attachment: 'together'
 333     }
 334   ]
 335 });
 336 </code></pre><output data-example="window" class="scroll-page"></output>
 337
 338 You can, of course, use pin with the window as well to
 339 make it always visible no matter where the user scrolls:
 340
 341 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 342   element: yellowBox,
 343   target: greenBox,
 344   attachment: 'top left',
 345   targetAttachment: 'bottom left',
 346   constraints: [
 347     {
 348       to: 'window',
 349       attachment: 'together',
 350       <mark>pin: true</mark>
 351     }
 352   ]
 353 });
 354 </code></pre><output deactivated class="scroll-page visible-enabled"></output>
 355
 356 `to` can be any of:
 357
 358 - `'scrollParent'`
 359 - `'window'`
 360 - any DOM element
 361 - an array of bound points relative to the body `[X1, Y1, X2, Y2]`
 362
 363 You can also provide multiple constraints, keeping in mind that they are
 364 processed in the order supplied (the last one always has the final word).
 365
 366 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 367   element: yellowBox,
 368   target: greenBox,
 369   attachment: 'top left',
 370   targetAttachment: 'bottom left',
 371   constraints: [
 372     {
 373       to: <mark>'scrollParent'</mark>,
 374       pin: true
 375     },
 376     {
 377       to: <mark>'window'</mark>,
 378       attachment: 'together'
 379     }
 380   ]
 381 });
 382 </code></pre><output></output>
 383
 384 Optimization
 385 ------------
 386
 387 ### Element Moving
 388
 389 The goal of Tether's optimizer is to not have to change the positioning
 390 CSS as the page is scrolled or resized.  To accomplish this it looks at the
 391 last few positions, finds commonalities, and uses them to decide whether to
 392 position the element absolutely or with fixed positioning.
 393
 394 If the element is fully contained within its scroll parent, its DOM node
 395 can also be moved inside the scroll parent, to avoid repaints as the
 396 container is scrolled.
 397
 398 <pre class="pre-with-output"><code class="lang-javascript" data-example="optimizer">new Tether({
 399   element: yellowBox,
 400   target: greenBox,
 401   attachment: 'top left',
 402   targetAttachment: 'bottom left'
 403 });
 404 </code></pre><output data-example="optimizer"></output>
 405
 406 We are moving where the DOM node is, so if you have CSS which styles elements
 407 within the offset parent, you may see some rendering changes.  Also note
 408 that this optimization works best if the scroll parent is the offset parent.
 409 In other words, **the scroll parent should be made position relative, fixed or
 410 absolute to enable this optimization.**
 411
 412 If you do see stylistic changes occur when the element is moved,
 413 you might want to disable this optimization.  You can do that by
 414 setting `optimizations.moveElement` to false.
 415
 416 <pre class="pre-with-output"><code class="lang-javascript" data-example="optimizer2">new Tether({
 417   element: yellowBox,
 418   target: greenBox,
 419   attachment: 'top left',
 420   targetAttachment: 'bottom left',
 421   optimizations: {
 422     <mark>moveElement: false</mark>
 423   }
 424 });
 425 </code></pre><output data-example="optimizer2"></output>
 426
 427 ### GPU
 428
 429 By default tether positions elements using CSS transforms.  These transforms allow the
 430 tethered element to be moved as its own layer to not force a repaint of the underlying
 431 page.
 432
 433 This method of positioning can cause some issues however, including color shifts and artifacts.
 434
 435 If you experience these issues, you can disable this optimization by setting `optimizations.gpu`
 436 to false:
 437
 438 <pre class="pre-with-output"><code class="lang-javascript" data-example>new Tether({
 439   element: yellowBox,
 440   target: greenBox,
 441   attachment: 'top left',
 442   optimizations: {
 443     <mark>gpu: false</mark>
 444   }
 445 });
 446 </code></pre><output></output>
 447
 448 Methods
 449 -------
 450
 451 The `Tether` constructor we've been using in these examples returns us a
 452 `Tether` object.
 453
 454 The `Tether` object has these methods:
 455
 456 - `setOptions({ options })` - Update any of the options (such as attachment)
 457 - `disable()` - Disable the tethering
 458 - `enable()` - Enable the tethering
 459 - `destroy()` - Disable and remove all references
 460 - `position()` - Manually trigger a repositioning
 461
 462 Options
 463 -------
 464
 465 The full list of options which can be passed to the `Tether` constructor and
 466 `setOptions`:
 467
 468 - `element`: The DOM element, jQuery element, or a selector string of an element which will be moved
 469 - `target`: The DOM element, jQuery element, or a selector string of an element which the `element` will be attached to
 470 - `attachment`: A string of the form `'vert-attachment horiz-attachment'`
 471   - `vert-attachment` can be any of `'top'`, `'middle'`, `'bottom'`
 472   - `horiz-attachment` can be any of `'left'`, `'center'`, `'right'`
 473 - `targetAttachment`: A string similar to `attachment`.
 474   The one difference is that, if it's not provided, targetAttachment will assume the mirror
 475   image of `attachment`.
 476 - `offset`: A string of the form `'vert-offset horiz-offset'`
 477   - `vert-offset` and `horiz-offset` can be of the form `"20px"` or `"55%"`
 478 - `targetOffset`: A string similar to `offset`, but refering to the offset of the target
 479 - `targetModifier`: Can be set to `'visible'` or `'scroll-handle'`
 480 - `enabled`: Should the tether be enabled initially? Defaults to `true`.
 481 - `classes`: A hash of classes which should be changed or disabled
 482 - `classPrefix`: The prefix placed at the beginning of the default classes, defaults to `'tether'`
 483 - `optimizations`: A hash of optimizations, used to disable them
 484 - `constraints`: An array of constraint definition objects.  Each definition is of the form:
 485   - `to`: A DOM element, bounding box, the string `'window'`, or the string `'scrollParent'`
 486   - `pin`: `true` or an array of strings representing the sides of the constraint
 487   - `attachment`: A string of the form `"vert-modifier horiz-modifier"`, or a single value
 488   representing both
 489     - Each modifier should be one of `"none"`, `"together"`, `"element"`, `"target"`, or `"both"`.
 490   - `outOfBoundsClass`: An alternative to `"tether-out-of-bounds"`, useful if the class
 491   needs to be differentiated from that of another constraint.
 492   - `pinnedClass`: An alternative to `"tether-pinned"`, similar to `outOfBoundsClass`.
 493
 494 Classes
 495 -------
 496
 497 Tether adds a variety of classes to the element and target to allow you to style
 498 them based on their tethering.
 499
 500 You can change the prefix of the classes with the `classPrefix` option.  It is `'tether'` by
 501 default, but you could, for example, change it to be `'bill'` if you were building the bill
 502 library and all the classes would be `'bill-*'`.
 503
 504 ```javascript
 505 new Tether({
 506   classPrefix: 'bill'
 507 });
 508 ```
 509
 510 The sass/css is similarily configurable, see
 511 [tooltip](https://github.com/HubSpot/tooltip/blob/master/sass/tooltip-theme-arrows.sass#L14) for
 512 an example of how to make your own prefixed css file.
 513
 514 All classes can be changed or disabled with the `classes` option.  For example, to change the
 515 `tether-element` class to be `my-box`:
 516
 517 ```javascript
 518 new Tether({
 519   classes: {
 520     element: 'my-box'
 521   }
 522 });
 523 ```
 524
 525 You can also disable classes you're not going to use:
 526
 527 ```javascript
 528 new Tether({
 529   classes: {
 530     out-of-bounds: false
 531   }
 532 });
 533 ```
 534
 535 - `tether-element` is added to the element
 536 - `tether-target` is added to the target
 537 - `tether-enabled` is added to both elements when tether is not disabled
 538 - `tether-element-attached-[left,right,top,bottom,middle,center]` is added to both
 539 elements based on the elements attachment, if the element becomes detached (for
 540 example, if it's pinned), that class is removed.  The class reflects how the
 541 element is actually attached, so if a constraint changes the attachment, that
 542 change will be reflected in the class.
 543 - `tether-target-attached-[left,right,top,bottom,middle,center]` is added to both
 544 elements based on the target's attachment.  All of the characteristics are the
 545 same as for element-attached.
 546
 547 ### Constraint-related Classes
 548
 549 - `tether-out-of-bounds`, `tether-out-of-bounds-[side]` are added to both the element and the target
 550 when the element is placed outside of its constraint.
 551 - `tether-pinned`, `tether-pinned-[side]` are added to both the element and target when a constraint
 552 has pinned the element to the [side] of the container.
 553
 554 Browser Support
 555 ---------------
 556
 557 Tether supports IE9+, and all modern browsers.
 558
 559 Google doesn't support IE8, Microsoft is dropping support in a few months, and not supporting it saves
 560 us a whole lot of trouble.  If you are interested in adding support, get in touch, we're happy to accept
 561 a PR.
 562
 563 Contributing
 564 ------------
 565
 566 Please contribute! Tether is developed in Coffeescript, but if that's problematic for you, feel free
 567 to submit pull requests which just change the JavaScript files, we can adapt them as needed.
 568
 569 To build Tether, you need:
 570
 571 - Node.js
 572 - Ruby (for compass)
 573
 574 #### Instructions
 575
 576 - Install compass (if you don't have it already)
 577
 578 ```bash
 579 gem update --system
 580 gem install compass
 581 ```
 582
 583 - Install the build tool
 584
 585 ```bash
 586 npm install -g gulp
 587 ```
 588
 589 - Install the project
 590
 591 ```bash
 592 # In the project directory
 593 npm install
 594 ```
 595
 596 - Build / Watch
 597
 598 ```bash
 599 gulp
 600 ```