Sometimes when updating an HTML value using JavaScript it is appropriate to animate the HTML in some that draws the users eye to the change. Often designers choose to animate the opacity or a background color. Todays widget illustrates a different approach to use with numbers, where the value quickly counts up or down from the current value to the correct value.

Example 1: Jackpot Numbers

(function() {
var Y = YAHOO,
	YD = Y.util.Dom,
	YL = Y.lang,

	_addNumbers = function(n) {
		var result = 1, i = 2;
		for (; i &lgt; = n; i += 1) {
			result += i;
		}
		return result;
	},

	_handleAnimation = function() {
		var _this = this; // improves compression
		_this.value += Math.round(_this.stepSize * _this.stepCount);
		_this.node.innerHTML = _this.formatFx(_this.value);
		_this.stepCount += 1;

		if (_this.stepCount >= _this.animSteps) {
			_this.timeout.cancel();
			_this.node.innerHTML = _this.formatFx(_this.finalValue);
		}
	};

	Core.Widget.JackpotNumbers = {
		incrementTo: function(elem, endPoint, conf) {
			var node = YD.get(elem),
				cfg = YL.isObject(conf) ? conf : {},
				currValue, isIncrement, diffValue;

			if (! node) {
				Y.log(Invalid node passed to Core.Widget.JackpotNumbers.incrementTo);
				return;
			}

			currValue = parseInt(node.innerHTML.replace(/[^0-9\.]/, ), 10);

			if (isNaN(currValue)) {
				Y.log(Node did not resolve to number in Core.Widget.JackpotNumbers.incrementTo);
				return;
			}

			isIncrement = currValue < endPoint;
			diffValue = isIncrement ? endPoint - currValue : currValue - endPoint;

			if (! YL.isNumber(cfg.animLength)) {cfg.animLength = 1000;}
			if (! YL.isNumber(cfg.animSteps)) {cfg.animSteps = 20;}
			if (! YL.isFunction(cfg.formatFx)) {cfg.formatFx = function(n) {return n;};}

			cfg.multiplier = _addNumbers(cfg.animSteps);
			cfg.animFreq = cfg.animLength / cfg.animSteps;
			cfg.stepCount = 1;
			cfg.stepSize = (isIncrement ? 1 : -1) * diffValue / (cfg.multiplier);
			cfg.node = node;
			cfg.value = currValue;
			cfg.finalValue = endPoint;
			cfg.timeout = YL.later(cfg.animFreq, cfg, _handleAnimation, null, true);
		}
	};
}());

The animation is setup in the static incrementTo function, while the actual DOM animation occurs in the private _handleAnimation function. Call the incrementTo function to begin animating a number in the DOM. It requires two parameters (elem - a string ID or DOM pointer, and endPoint the number to animate to) and one optional parameter (conf - a configuration object). The function then calculates if the endPoint is greater than or less than the current value in the provided DOM element to determine whether it should add or subtract. It then calculate an arithmetic multiplier using an additive method (if animSteps is 5, then the multiplier is 1 + 2 + 3 + 4 + 5 = 15), based on the number of animation steps, so that the rate of addition will increase as the number nears the endPoint. This multiplier is used to calculate the step size. All values are stored on a configuration object which is passed into an interval timer, with the period determined by the length of animation divided ("cfg.animLength") by the number of animation steps ("cfg.animSteps").

The configuration parameter has properties that can be controlled by the developers: animLength, animSteps, and formatFx. The animation length is the number of milliseconds it should take for the animation to reach the endPoint. The animation steps is the number of additive steps to take to reach the endPoint. And the formatFx is a function that should take a number as its first parameter and return a string, presumably the number in a desired format. These 3 configuration properties give the developer control over most of the animation attributes.

The _handleAnimation function simply adds the the value of the stepCount multiplied by the stepSize (so each addition is slightly larger than the previous) and updates the DOM node. Once the stepCount equals the total number of animation steps (animSteps), then the interval timer is stopped and the DOM node is updated with the endPoint value to correct any rounding issues.

Although, I probably wont use this widget very often, it is a lot of fun to play with. Here is a Demo Page to give it a try.

Limitations

The function will remove all number numeric characters from the node, so only use this on DOM nodes containing numbers. It also currently parses to integer, so any decimal places will be lost.