super_scroller.js

Scroll the contents of any (block-level) element by setting custom controls. This class honours the unobtrusive-guideliness.

Added: 2008-09-13 21:08:22

download

/******
* You may use and/or modify this script as long as you:
* 1. Keep my name & webpage mentioned
* 2. Don't use it for commercial purposes
*
* If you want to use this script without complying to the rules above, please contact me first at: marty@excudo.net
* 
* Author: Martijn Korse
* Website: http://devshed.excudo.net
*
* Date:  2008-09-13 21:08:22
***/

/**
 * Excudo Super Scroller Class
 * Provides the ability of custom scrolling the contents of - for example - a div.
 */
function SuperScroller ()
{
	// class specifics
	this.NAME = 'Excudo Super Scroller';
	this.VERSION = '1.0';
	// default values
	this.speed = 4;
	this.removeScrollbar = true;
	this.controlAction = 'hover';
	this.scrollTimer = null;
}

/**
 * This method is in charge of assigning the right handlers to the choosen elements
 * 
 * @param	int	d	This value should be either -1 or 1. -1 signifying scrolling up and 1 scrollling down
 * @param	obj	el	Reference to the element that should provide the scroll up (d=-1) or down (d=1) functionality
 * @return	void
 */
SuperScroller.prototype.setControl = function (d, el)
{
	// creating a reference to this object to be used in the handler-functions
	var obj = this;

	// we want to perform the scrolling-action through the 'click' of a mouse
	if (this.controlAction == 'click')
	{
		el.onmousedown = function ()
		{
			obj.doScroll(d);
		}
		el.onmouseup = function ()
		{
			obj.cancelScroll();
		}
	}
	// we want to perform the scrolling-action by hover over the controller with the mouse
	else
	{
		el.onmouseover = function ()
		{
			obj.doScroll(d);
		}
		el.onmouseout = function ()
		{
			obj.cancelScroll();
		}
	}
}

/**
 * This function does the actual scrolling
 * 
 * @see		this.setControl()
 * @param	int	d	This value should be either -1 or 1. -1 signifying scrolling up and 1 scrollling down
 * @return	void
 */
SuperScroller.prototype.doScroll = function(d)
{
	// setting the speed in the right direction (up or down)
	var speed = this.speed * d;
	// calculating where our current location is
	var availVerScroll = this.tgt.scrollHeight - this.tgt.clientHeight;
	var availHorScroll = this.tgt.scrollWidth - this.tgt.clientWidth;
	// performing a bit of scroll
	this.tgt.scrollTop += speed;

	// creating a reference to this object so we can use it in the settimeout functions
	var obj = this;
	// now that that's done, we see if further action is needed
	if (d > 0)
	{
		// if we can still scroll, do so with a timeout of 1ms
		// setting this timeout enables us to cancel it later
		if (this.tgt.scrollTop < availVerScroll)
		{
			var setTimer = function() { obj.doScroll(d) };
			this.scrollTimer = setTimeout(setTimer, 1);
		}
		// we've reached the maximum, so we make sure it won't exceed it 
		else if (this.tgt.scrollTop > availVerScroll)
		{
			this.tgt.scrollTop = availVerScroll;
		}
	}
	else
	{
		// same stuff as in if-body above, but in different direction
		if (this.tgt.scrollTop > 0)
		{
			var setTimer = function() { obj.doScroll(d) };
			this.scrollTimer = setTimeout(setTimer, 1);
		}
		else if (this.tgt.scrollTop < 0)
		{
			this.tgt.scrollTop = 0;
		}
	}
}

/**
 * This function is in charge of stopping the scrolling
 *
 * @return void
 */
SuperScroller.prototype.cancelScroll = function()
{
	if (this.scrollTimer != null)
	{
		window.clearTimeout(this.scrollTimer);
	}
}

/**
 * This function retrieves the style/css-value of a given property
 *
 * @param	obj	el		Dom element
 * @param	string	property	The css-property we're interested in
 * @return	mixed			The value of the property
 */
SuperScroller.prototype.getCSSValue = function(el, property)
{
	if (typeof(window.getComputedStyle) == 'function')
	{
		var styleValue = window.getComputedStyle(el, null)[property];
	}
	else
	{
		var styleValue = el.currentStyle[property];
	}
	return typeof(styleValue) != 'undefined' ? styleValue : '';
}

/**
 * function that can set custom properties
 * some of those have default values, some not
 *
 * @param	obj	props	object with custom properties
 * @return	void
 */
SuperScroller.prototype.init = function(props)
{
	// speed. is 4 by default
	if (typeof(props.speed) != 'undefined')
	{
		this.speed = props.speed;
	}
	// target element (where we want to implement the scroller) by id
	if (typeof(props.tgtId) != 'undefined')
	{
		this.tgt = document.getElementById(props.tgtId);
	}
	// target element reference
	else if (typeof(props.tgt) != 'undefined')
	{
		this.tgt = props.tgt;
	}
	// when removeScrollbar is true, the native scrollbar is removed
	if (typeof(props.removeScrollbar) != 'undefined')
	{
		this.removeScrollbar = !props.removeScrollbar ? false : true;
	}
	// this determines what should trigger the scrolling effect. (a mouse-over or a mouse-click)
	if (typeof(props.controlAction) != 'undefined')
	{
		this.controlAction = props.controlAction;
	}
	// the element that causes the scroll-up - indicated by its id
	if (typeof(props.controlUpId) != 'undefined')
	{
		this.setControl(-1, document.getElementById(props.controlUpId));
	}
	// the element that causes the scroll-up - by reference
	else if (typeof(props.controlUp) != 'undefined')
	{
		this.setControl(-1, props.controlUp);
	}
	// the element that causes the scroll-down - indicated by its id
	if (typeof(props.controlDownId) != 'undefined')
	{
		this.setControl(1, document.getElementById(props.controlDownId));
	}
	// the element that causes the scroll-down - by reference
	else if (typeof(props.controlDown) != 'undefined')
	{
		this.setControl(1, props.controlDown);
	}

	// if it's not set, we warn the user
	if (typeof(this.tgt) == 'undefined')
	{
		alert('you forgot to set a tgt element!\nScroller could not be initiated');
	}
	else
	{
		if (this.removeScrollbar)
		{
			this.tgt.style.overflow = 'hidden';
		}
	}
}

download