- commit
- 59b27dd6f544a113abc1c82e3f31953fe2bb0f6f
- parent
- 5fae7d87852129faa90dc286076b5ed869e95f93
- Author
- Tobias Bengfort <tobias.bengfort@gmx.net>
- Date
- 2015-02-28 11:36
update readme
Diffstat
| M | README.md | 110 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- |
1 files changed, 103 insertions, 7 deletions
diff --git a/README.md b/README.md
@@ -2,13 +2,109 @@ 2 2 3 3 *relatively sticky* is a drop-in replacement for the excellent 4 4 [sticky-kit](https://github.com/leafo/sticky-kit). The idea was to be able to5 -1 have sticky elements within any scrollable element, not only window. But from-1 5 have sticky elements within any scrollable element, not only `window`. But from 6 6 the simple idea this grew into a rewrite of more or less the whole project. 7 78 -1 The approach taken here is different from the one in sticky-kit: Instead of9 -1 using a mixture of static, absolute and fixed positioning for different cases10 -1 (normal, bottomed, fixed) this always uses relative positioning. This way the11 -1 element stays in its original context and we do not need to sync it manually.12 -1 There is also no need for a spacer.13 -114 8 License: WTFPL -1 9 -1 10 ## Usage -1 11 -1 12 $("#sticky_item").stick_in_parent() -1 13 -1 14 You can optionally pass a hash of options to configure how Relativly Sitcky -1 15 works. The following options are accepted, each one is optional: -1 16 -1 17 `parent` -1 18 : The element will be the parent of the sticky item. The dimensions of the -1 19 parent control when the sticky element bottoms out. Defaults to the closest -1 20 parent of the sticky element. Can be a selector. -1 21 -1 22 `scrollable` -1 23 : The element in which the sticky item should stick. Defaults to `window`. -1 24 Can be a selector. -1 25 -1 26 `sticky_class` -1 27 : The name of the CSS class to apply to elements when they have become stuck. -1 28 Defaults to `"is_stuck"`. -1 29 -1 30 `offset_top` -1 31 : offsets the initial sticking position by of number of pixels, can be either -1 32 negative or positive -1 33 -1 34 `bottoming` -1 35 : Boolean to control whether elements bottom out. Defaults to `true` -1 36 -1 37 ## quick reminder of the "traditional" positioning algorithms -1 38 -1 39 static -1 40 : This is the "normal" positioning algorithm. `top`, `right`, `bottom` and -1 41 `left` will have no effect. -1 42 -1 43 relative -1 44 : Works mostly like `static`, but the element will be displayed with the -1 45 specified offset relative to its original position. All other elements will -1 46 still behave as if there was no offset. -1 47 -1 48 absolute -1 49 : The element will be displayed with the specified offset relative to the -1 50 next parent with a non-static positioning. All other elements will behave -1 51 as if this element did not exist. -1 52 -1 53 fixed -1 54 : The element will be displayed with the specified offset relative to the -1 55 window. All other elements will behave as if this element did not exist. -1 56 -1 57 -1 58 ## some notes on sticky positioning -1 59 -1 60 Sticky positioning today is a commonly used feature in web development. For -1 61 example, there is the `affix` class in -1 62 [twitter bootstrap](http://getbootstrap.com/javascript/#affix), a jquery plugin -1 63 called [sticky-kit](https://github.com/leafo/sticky-kit) and there is even an -1 64 effort to include it in the -1 65 [CSS standard](http://dev.w3.org/csswg/css-position-3/#position-property). -1 66 -1 67 The idea is that an element is displayed in normal flow as long as it is on the -1 68 screen. But when you scroll, instead of leaving the screen, it "sticks" to it. -1 69 This is especially usefull for navigation elements which need to be available -1 70 all the time. -1 71 -1 72 So `sticky` works like `static` by default and like `fixed` when it sticks to -1 73 the screen. But that is `fixed` with a bit of `relative` because all other -1 74 elements must still behave as if the sticky element would still be at its -1 75 original position. -1 76 -1 77 Now there are two approaches how sticky can be implemented if it is not -1 78 available natively. The first approach is to use `fixed`. In that case you need -1 79 to create a "spacer" element that will sit at the original position of the -1 80 sticky element in order to make all other elements behave correctly. -1 81 -1 82 The second approach is to use relative positioning. In that scenario, the -1 83 position of the sticky element needs to be recalculated on every scroll event. -1 84 -1 85 Most libraries (all I could find) use the first approach, probably because it -1 86 has better performance. But there might be cases where the second approach is -1 87 more suitable, for example scrollable child elements or fluid design. So this -1 88 library implements exactly that. -1 89 -1 90 ## Conclusion -1 91 -1 92 - Use native sticky positioning where possible (AFAIK Firefox and Safari). -1 93 - Evaluate which approach works best for you in your specific usecase. Most -1 94 likely, *sticky-kit* is the better choice. But maybe *relatively-sticky* -1 95 actually works better for you. -1 96 -1 97 Example: -1 98 -1 99 var stick = function(element, modernizr, top) { -1 100 if (modernizr.csspositionsticky) { -1 101 element.css({ -1 102 position: 'sticky', -1 103 top: top + 'px' -1 104 }); -1 105 } else { -1 106 element.stick_in_parent({ -1 107 offset_top: top -1 108 }); -1 109 } -1 110 };