jQuery.popLockit

A jQuery plugin for 'locking' short content in place as the user scrolls by longer content. For example, it will lock metadata and share buttons in place as the user scrolls by a long essay or series of images.

This is used for the posts feed on Artsy, in this example and on this page.

Usage

Include required Javascripts

<script src="jquery.js"></script>
              <script src="dist/poplockit.min.js"></script>
          

Create html like this

  <div id="feed">
              <article>
              <div class="column">Left</div>
              <div class="column">Center</div>
              <div class="column">Right</div>
              </article>
              ...
              </div>
          

Apply the popLockIt plugin

$('#feed').popLockIt({
              feedItems      : $('#feed > article'),
              columnSelector : '> .column'
              });
          

feedItems { jQuery Object }

jQuery object for you feed items.

columnSelector { selector String }

Selector string to get the columns for your feed items relative to a feed item element. It is used in jQuery.popLockIt like so: $feedItem.find(columnSelector);

preventFixed { boolean }

Pass in preventFixed: true to have popLockIt use position absolute instead of fixed. This is useful for supporting browsers (Safari on iOS) that do not support position fixed.

onScroll { function(scrollTop) }

This function will be called every time the popLockIt scroll event fires. Useful for infinite scroll functionality. We recommend that you pass in a throttled function so that it does not affect scroll performance.

additionalFeedItemInit { function($el, index) }

Function that runs after each feed item is initialized. Passes a jquery wrapped element and the index of that element in the feed.

destroy()

returns feedItems and their columns to their default positions and unbinds all events.

recompute()

Recomputes height / top / bottom etc of each feed item and its columns. Run if the size of any of your feed items has changed.

recomputeItem(index)

Recomputes height / top / bottom etc of one feed item and its columns. Run if the size of only one feed item has changed.

recomputeItemColumn(index, column)

Recomputes height / top / bottom etc of one feed item's column. Run if one column of one of your feed items has changed.

onScroll()

Manually run the onScroll event. Recommend running this if you have hidden the feed and are now re-showing it.

addFeedItems( { jQuery Object } )

Add items to the feed. Takes a jQuery object containing the new feed items.

stop()

Stop popLockit from running. Useful if you want to temporarily disable popLockit functionality.

start()

Restarts popLockit after calling Stop

Contributions and pull requests are very welcome. Please follow these guidelines when submitting new code.

Modifying the code

1. Fork and clone the repo.
2. If needed: npm install -g grunt for Grunt
3. If needed: brew install phantomjs for PhantomJS
4. Run npm install to install dependencies
5. Run grunt (compiles coffeescripts and runs tests)
6. Run grunt watch while editing files to auto-compile coffeescripts and run tests
7. Make all changes in Coffeescript files, not JavaScript files.

Submitting pull requests

1. Add tests for the change you want to make. Run grunt jasmine to see if tests fail.
2. Run grunt to compile new dist and make sure nothing is broken
3. Submit a Pull Request using GitHub.