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:

		//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";
	});

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:

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

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");
	scrob.register("#elementID");
	scrob.register(".className");

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])
	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])
	scrob.bob2.on({"method":val})

Syntactical alias for set - Used to assign scroll events
accepts object with prop:val pairs
Chain-able, returns scrobject called on.

addon

	scrob.bob2.addon(method[, val])
	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.
accepts objects with prop:val pairs
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 handles 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";
	}
});

---

Working with Classes and ScrobMaster

ScrobMaster supports registering a group of elements at the same time through the use of a CSS class selector.
Registering with a class selector will return a scrobarray object; The same way a scrobject would be returned.
The scrobarray object has the same methods and properties as the basic scrobject. The difference is, rather than applying them to a single element, a scrobarray houses an array of nodes. (scrob.scrobarray.nodes) These nodes are essentially scrobject that prototype thier parental scrobarray.

Each node has the ability to support it's own set of handles that will overide the scrobarray handles.
Scrobarray nodes are only available to edit after the DOM has loaded.

example:

	
	scrob.register('.classBob');
	
	scrob.classBob.set({
		"enter": function(state){this.style.backgroundColor = "blue"}, 
		"exit": function(state){this.style.backgroundColor = "white"}, 
		"top": -100 
	});
	
	window.onload = function(){
		scrob.classBob.nodes[1].set("enter", funciton(state){this.style.backgroundColor = "green"});
	}
	

What we did:

• register the className, which will construct and return a new scrobarray.
• set the enter, exit events and trigger top for every node on the scrobarray, which will, again, return the scrobarray
  • turn blue when element is entered
  • turn white when element is exited
  • set trigger point to be 100px above each element
  • change the enter event for the second node after it is available for editing (after the DOM loads)
  • This will overwrite the previously set enter event for THIS NODE ONLY.
  • All others will function as previously defined
  • returns the ScrobArrayNode that was called upon.