relatively-sticky

commit

11d0ac65a4102ce06069124b0206be0c1af08783

parent

cba15aa463f677cea70dbe751b11d555626b4202

Author

leaf corcoran <leafot@gmail.com>

Date

2014-11-13 18:24

update docs with more info about tick/recalc and new options

Diffstat

1 files changed, 37 insertions, 7 deletions

diff --git a/site/index.html b/site/index.html

@@ -149,8 +149,8 @@ $("#sticky_item").stick_in_parent()
  149   149 $("#sticky_item").stick_in_parent(options)
  150   150 ```
  151   151 
  152    -1 `options` is an optional hash of options to configure how Sticky Kit works. The
  153    -1 following options are accepted:
   -1   152 You can pass a hash of options to configure how Sticky Kit works. The following
   -1   153 options are accepted, each one is optional:
  154   154 
  155   155 * `parent` -- The element will be the parent of the sticky item. The
  156   156   dimensions of the parent control when the sticky element bottoms out. Defaults
@@ -162,6 +162,14 @@ following options are accepted:
  162   162   have become stuck. Defaults to `"is_stuck"`.
  163   163 * `offset_top` -- offsets the initial sticking position by of number of pixels,
  164   164   can be either negative or positive
   -1   165 * `spacer` -- either a selector to use for the spacer element, or `false` to
   -1   166   disable the spacer. The selector is passed to
   -1   167   [`closest`](http://api.jquery.com/closest/), so you should nest the sticky
   -1   168   element within the spacer. Defaults to Stiky Kit creating its own spacer.
   -1   169 * `bottoming` -- Boolean to control whether elements bottom out. Defaults to `true`
   -1   170 * `recalc_every` -- Integeger specifying that a recalc should automatically
   -1   171   take place between that many ticks. A tick takes place on every scroll event.
   -1   172   Defaults to never calling recalc on a tick.
  165   173 
  166   174 ### Events
  167   175 
@@ -193,14 +201,14 @@ Sticky Kit listens to one event on `document.body`.
  193   201   recalculated. More information below.
  194   202 
  195   203 
  196    -1 If you want to remove sticky kit from an element after applying it you can send
  197    -1 that element a `sticky_kit:detach` event.
  198    -1 
  199   204 Sticky Kit also listens to an event on the sticky elements:
  200   205 
  201   206 * `sticky_kit:detach` -- remove sticky kit and restore element to original
  202   207   position
  203   208 
   -1   209 If you want to remove sticky kit from an element after applying it you can send
   -1   210 that element a `sticky_kit:detach` event.
   -1   211 
  204   212 For example:
  205   213 
  206   214 ```js
@@ -213,7 +221,8 @@ If you're changing the markup of your page on the fly by removing, adding or
  213   221 resizing elements then you most likely need to tell Sticky Kit to recalculate
  214   222 the sticky elements to guarantee they're positioned correctly.
  215   223 
  216    -1 You can cause a recalculation to happen by triggering an event on `document.body`:
   -1   224 You can manually cause a recalculation to happen by triggering an event on
   -1   225 `document.body`:
  217   226 
  218   227 ```js
  219   228 $(document.body).trigger("sticky_kit:recalc")
@@ -223,11 +232,32 @@ Typically you only need to trigger a recalculation if you are changing the
  223   232 positions/sizes of elements above the sticky element, adjacent to it, or the
  224   233 sticky element itself.
  225   234 
   -1   235 Sticky kit has two types of internal actions, a `recalc` and a `tick`. A
   -1   236 recalculation happens very rarely, by default only on start up and on page
   -1   237 resize. It caches the sizes and positioning CSS of all the elements that it
   -1   238 needs to interact with.
   -1   239 
   -1   240 A `tick` happens on every scroll event. It's a light weight function checks the
   -1   241 cached values and updates state accordingly. This is done to keep the least
   -1   242 amount of code running on each scroll event to help prevent jank and give more
   -1   243 time to any other scroll event listeners you might have.
   -1   244 
   -1   245 Instead of manually calling `sticky_kit:recalc` you can use the `recalc_every`
   -1   246 option described above to periodically do a recalculation between ticks.
   -1   247 Setting it to 1 will cause a recalculation to happen on every scroll event,
   -1   248 preventing the state from ever being out of date.
   -1   249 
   -1   250 ```js
   -1   251 $("#sticky_item").stick_in_parent({recalc_every: 1})
   -1   252 ```
   -1   253 
  226   254 ### About Columns
  227   255 
  228   256 If you're familiar with HTML and CSS then you probably know there are a handful
  229   257 of different ways to make columns. Sticky kit works automatically with floated
  230    -1 columns or `inline-block` columns.
   -1   258 columns, `inline-block` columns, or absolutely positioned elements. (Non column
   -1   259 elements like toolbars work great as well, for example the toolbar on this
   -1   260 site.)
  231   261 
  232   262 ### Browser Support
  233   263