afm-client/bower_components/tether/docs/3-Advanced/2-extending_tether.md

   1 Extending Tether
   2 -----
   3
   4 Tether has a module system which can be used to modify Tether's positioning, or just do something each time the Tether is moved.
   5
   6 Tether has an array called `Tether.modules`, push onto it to add a module:
   7
   8 ```coffeescript
   9 Tether.modules.push
  10   position: ({top, left}) ->
  11     top += 10
  12
  13     {top, left}
  14 ```
  15
  16 #### Position
  17
  18 Your position function can either return a new object with `top` and `left`, `null`/`undefined` to leave the coordinates unchanged, or
  19 `false` to cancel the positioning.
  20
  21 The position function is passed an object with the following elements:
  22
  23 ```javascript
  24 {
  25   left, // The element's new position, from the top left corner of the page
  26   top,
  27   targetAttachment, // The targetAttachment, with 'auto' resolved to an actual attachment
  28   targetPos, // The coordinates of the target
  29   attachment, // The attachment, as passed in the option
  30   elementPos, // The coordinates of the element
  31   offset, // The offset, after it's converted into pixels and the manual offset is added
  32   targetOffset, // The attachment is converted into an offset and is included in these values
  33   manualOffset, // The manual offset, in pixels
  34   manualTargetOffset
  35 }
  36 ```
  37
  38 It is called with the Tether instance as its context (`this`).
  39
  40 #### Initialize
  41
  42 Modules can also have an `initialize` function which will be called when a new tether is created.  The initialize function
  43 is also called with the Tether instance as its context.
  44
  45 ```coffeescript
  46 Tether.modules.push
  47   initialize: ->
  48     console.log "New Tether Created!", @
  49 ```
  50
  51 #### Examples
  52
  53 [Constraints](https://github.com/HubSpot/tether/blob/master/coffee/constraint.coffee) and [shift](https://github.com/HubSpot/tether/blob/master/coffee/shift.coffee) are both implemented as modules.
  54 [Mark Attachment](https://github.com/HubSpot/tether/blob/master/coffee/markAttachment.coffee) is used by the docs.