hlStickyElement
Makes an element sticky programmatically. The service is a function and you need to make an instance to use it.
This service is heavily used by the hlSticky
directive. So if you simple want to use a directive, that might be easier for you.
One reason is because you'll need to manually draw the sticky object as can be seen from this demo. In most cases you'll not need that.
var stickyElementInstance = hlStickyElement(element:DOMElement, options:object); stickyElementInstance.draw(drawOptions:object); stickyElementInstance.destroy();
hlStickyElement(element:DOMElement, options:object)
element
A DOM element object. This should either be a jQuery/jqLite object or an Angular element.
options
An object with a bunch of options that determine the behavior of the sticky element:
id
(Default: none) - Determines the identifier of the sticky element.
Most of the time you won't need this, but sometimes it's handy to set it. For example if you want to retrieve a sticky element from a stack. If this is not set, the identifier will default to the index it has in the stack.
stack
(Default: none) - Supplies a hlStickyStack
instance the element will be added to.
This will allow you to make use of the lower-level methods in the hlStickyStack
. Or you can give a stack if you simply don't want to use the default hlStickyStack
.
mediaQuery
(Default: none) - Enables/disables the sticky element based on a media query.
Check out the media query demo.
Or learn more about media queries in general.
stickyClass
(Default: 'is-sticky') - Adds custom classes to the sticky element when it becomes sticky.
usePlaceholder
(Default: true) - Prevent the dom from collapsing on itself.
When a sticky element becomes sticky its position becomes fixed
.
It is no longer part of the DOM in terms of other DOM element respecting it's dimensions and the elements underneath the sticky will suddenly jump a little.
To compensate for this an invisible placeholder is created with the height of the sticky element.
anchor
(Default: 'top') - Determines to what edge the sticky element should stick.
top
and bottom
are valid values.offsetTop
(Default: 0) - Adds offset to the top of the sticky element to act as margin.anchor
must be set to top
to make it work.offsetBottom
(Default: 0) - Adds offset to the bottom of the sticky element to act as margin.anchor
must be set to bottom
to make it work.container
(Default: None) - Id of a DOM element that you want the sticky element to be constrained to.Check out the container demo.
event
(Default: None) - Calls method whenever something noteworthy happens.Example:
options.event = function(event:object)
event: { event:string //event name }
The possible events are as follows:
stick
: The sticky element becomes sticky
unstick
: The sticky element lost it stickiness
enable
(Default: None) - Boolean value to toggle sticky behavior on and off.Only affects rendering if negative value is passed in.
Once you have an instance a few methods are made available to you.
draw(drawOptions:object)
A DOM element object. This should either be a jQuery/jqLite object or an Angular element.
drawOptions
{ offset: { top:int, bottom:int, zIndex:int }, force:boolean }
offset.top
(Default: 0) - Gives the sticky element additional offset from the top.
Perhaps not extremely useful when using single sticky elements, but the hlStickyElementCollection
service is using this for parent collections to accommodate for the stack height.
anchor
must be set to top
to make it work.offset.bottom
(Default: 0) - Gives the sticky element additional offset from the bottom.
Perhaps not extremely useful when using single sticky elements, but the hlStickyElementCollection
service is using this for parent collections to accommodate for the stack height.
anchor
must be set to bottom
to make it work.offset.zIndex
(Default: none) - Allows for altered z-indexes.
Read more about the z-indexes at the hlStickyStack
service
force
(Default: false) - Forces a complete re-draw.
Sometimes calling draw is not enough, for example during a resize of the viewport in the width dimension only, the element will not get re-drawn as expected. Setting this options to true will simply un-stick the element and re-stick it. You should try to limit using this option because it uses a bit more resources.
anchor()
Will return the anchor currently active.
isSticky()
Will return a boolean telling you if the sticky element is sticky or not
computedHeight(scrolledDistance:int)
Will return a integer with the height of the sticky element. If the element is not sticky at the scrolled distance the result will be 0.
sticksAtPosition(scrolledDistance:int)
Will return a boolean telling you if the sticky element will stick at a certain position. The conditions also includes the media query if that was set.
destroy()
Destroys the sticky element from the stack it was attached to and it makes sure it un-sticks itself. It is vital you call this method after you for example switch pages in your Angular application, otherwise it might cause weird artifacts on follow up pages.