README.md

ScrobMaster

Master your scroll events based on the elements you are affecting.
ScrobMaster allows you to attach events to scroll points based off registered DOM elements.

Overview:

ScrobMaster works with elements that have been registered to create "Scrobjects". Each Scrobject has two adjustable zones that each have three attachable events. Events are executed when the page's settable trigger point enters, exits or scrolls in one of the scrobjects zones.

	events: bufferEnter, bufferStep, bufferExit, enter, step, exit
Buffer Zone: the space between bufferTop and bufferBottom
live Zone: the space between top and bottom

         Window
------------------------
|  ....................|....... bufferTop
|  .                   |
|  .                   |        Buffer Zone
|  .                   |
|  ------------------..|....... top
|  |     Element    |  |
|  |                |  |        live Zone
|  |                |  |
|  ------------------..|....... bottom
|  .                   |
|  ....................|....... bufferBottom
------------------------

Basic Use:

	<script src="scrobMaster.js"></script>
	<script>
		//Basic Example: 
		// Register Element with ID of bob2 as a scrobject
		scrob.register('bob2');
	//set the bufferEnter event to trigger 100px above the element
	scrob.bob2.set("bufferTop", -100);

	// Set the enter event to change the background color
	// based on the direction of the scroll when event it triggered.
	scrob.bob2.on('enter', function(scrollState){
		this.style.backgroundColor = (scrollState.direction == "up")? "red":"blue";
	});

	// Set exit event to revert the background color to white.
	scrob.bob2.on('exit', function(scrollState){
		this.style.backgroundColor = "white";
	});
</script>

For ease of use ScrobMaster methods can be chained and most accept objects to attach multiple events and set multiple properties at once. So the above could be reduced to:

	<script src="scrobMaster.js"></script>
	<script>
		scrob.register('bob2').set({
			'bufferTop': -100,
			'enter': function(scrollState){this.style.backgroundColor = (scrollState.direction == "up")? "red":"blue";},
			'exit': function(scrollState){this.style.backgroundColor = "white";}
		});
	</script>

Please note: In the examples above to raise the bufferEnter's trigger point a negative value was used. This is because ScrobMaster positioning is based off scrollTop, Larger numbers are further down on the page and the opposite for smaller. The top of the page being located at 0.

ScrobMaster API

Register

scrob.register("elementID");

Registers and returns a new Scrobject on the scrobMaster. Registered elements are accessible off the scrobMaster via the ID passed into the register method. Chain-able.

	//Register example:
	scrob.register('bob2');
	//returns scrob.bob2
//access a scrobject:
scrob.bob2 || scrob['bob2']

setTriggerPos

scrob.setTriggerPos(int);

Sets the windows trigger position. Defaults to 0 or the top of the window. Chain-able Returns ScrobMaster or Scrobject it was called on.

getScrollTop

scrob.getScrollTop()

Not Chain-able. Returns the current scroll position of the window.

ScrobJect API

Methods outlined below are called off a registered scrobject, eg. scrob.bob2.methodCall();

set

scrob.bob2.set(property[, val])

set properties and or events for your scrobject.
accepts object with prop:val pairs
Chain-able, returns scrobject called on.

Settable properties:

• elm : DOM element - element events will affect.
• top: integer - top trigger point relative to elm
• bottom: integer - bottom trigger point relative to elm
• bufferTop: integer - top trigger of buffer point relative to elm
• bufferBottom: integer - bottom trigger of buffer point relative to elm

Note - if top is set to a value less than bufferTop; bufferTop will also be set to the given value. The reverse is true for bottom and bufferBottom

Attachable methods:

• bufferEnter - triggered when buffer zone is entered from top or bottom
• bufferStep - triggered on scroll in buffer zone
• bufferExit - triggered when buffer zone is exited from top or bottom
• enter - triggered when live zone is entered from top or bottom
• step - Triggered on scroll in live zone
• exit - triggered when live zone is exited from top or bottom

Event method functions accept the current ScobMaster scrollState, described below, as their only parameter

on

scrob.bob2.on(method[, val])

Syntactical alias for set - Used to assign scroll events
Chain-able, returns scrobject called on.

addon

scrob.bob2.addon(method[, val])

Similar to the "on" method, used to assign scroll events in addition to previously defined handles rather than replace them.
Chain-able, returns scrobject called on.
example

	scrob.register('bob2');
	scrob.on('enter', function(scrollState){console.log('one')});
	scrob.addon('enter', function(scrollState){console.log('two')});
	//Will log both 'one' and 'two' when enter is triggered

elm

scrob.bob2.elm

The element that the scrobject affects

style

scrob.bob2.style

Shorthand to the affected elements style attribute.

Inside the event handler function

Here is some information about the handlers you pass when setting events:

ScrobMaster scrollState argument

scrollState is updated on scroll and passed in to each event method defined when trigged. Property

• scrollState.direction = direction of scroll.
• scrollState.scrollTop = current scrollTop of window
• scrollState.lastScrollTop = previous scrollTop of window.

this

Inside of a handler function "this" refers to the scrobject you are affecting.

	//an example:
scrob.bob2.set({
	'enter': function(state){
		this.on('exit', function(state){this.style.border = "none"}),
		this.style.border = "solid 2px red";
	}
});