javascript / K345 classNames

Description

Manipulate className(s) of an DOM element. (className is very similar to HTML class attribute).

Uses classList API or fallback for older browsers.

Requirements

Method overwiew:

For all methods, elRef has to be a DOM element reference or an array of such. Each className has to be a string (not empty, no whitespace allowed). If elRef is an array of references, the return value is an array containing the values as they were specified for each method

hasClass()
Checks existance of className in class list of element elRef
Boolean has = K345.DOM.hasClass(Node elRef, String className);
Returns true if the class name of elRef contains className
addClass()
Adds one or multiple class names to element class list
String old = K345.DOM.addClass(Node elRef, String className [,String className…]);
Returns former class name string
removeClass()
Removes one or multiple class names from element class list
String old = K345.DOM.removeClass(Node elRef, String className [,String className…]);
Returns former class name string
setClass()
Sets one or multiple class names as element class list. All former class names will be removed.
String old = K345.DOM.setClass(Node elRef, String className [,String className…]);
Returns former class name string
getClass()
Gets all class list values of element as array
Array names = K345.DOM.getClass(Node elRef);
Returns array containing value(s) of elRef class list
For string value use elRef.className
toggleClass()
Adds class name(s) if not in class list of element or removes class name(s) if already in list.
String old = K345.DOM.toggleClass(Node elRef, String className [,String className…]);
Returns former class name string
replaceClass()
Removes classNameA and adds classNameB to the class list of elRef.(just like seperate calls of addClass() and removeClass()).
If strict is true class names will be changed only if classNameA is already set.
String old = K345.DOM.replaceClass(
	Node elRef, String classNameA, String classNameB [,Boolean strict]
);
Returns former class name string
addClassIf()
Adds one or multiple class names to element class list if condition is truthy.
String old = K345.DOM.addClassIf(
	Node elRef, String className [,String className…], Boolean condition
);
Returns former class name string
removeClassIf()
Removes one or multiple class names from element class list if condition is truthy.
String old = K345.DOM.removeClassIf(
	Node elRef, String className [,String className…], Boolean condition
);
Returns former class name string
addOrRemoveClassIf()
Adds className to element class list if condition is truthy and removes className from class list if condition is falsy.
String old = K345.DOM.addOrRemoveClassIf(
	Node elRef, String className [,String className…], Boolean condition
);
Returns former class name string

Examples:

given element
<span id="foo-elem" class="foo">foo</span>
javascript
var el = document.getElementById('foo-elem'),
	another_el = document.getElementById('bar-elem'),
	n = 2,
	cnames, rv;

rv = K345.DOM.hasClass(el, 'hi');
	// false,

rv = K345.DOM.hasClass(el, 'foo');
	// true,

K345.DOM.addClass(el, 'hi');
	// el.className now is 'foo hi',

K345.DOM.addClassIf(el, 'yo', n === 3);
	// condition is falsy, el.className still is 'foo hi',

K345.DOM.addClass(el, 'ho', 'bar', 'baz');
	// el.className now is 'foo hi ho bar baz',

K345.DOM.removeClass(el, 'hi');
	// el.className now is 'foo ho bar baz',

cnames = K345.DOM.getClass(el);
	// cnames is ['foo', 'ho', 'bar', 'baz'],

K345.DOM.removeClassIf(el, 'quz', true);
	// class quz does not exist, no changes,

K345.DOM.setClass(el, 'aa', 'bb', 'cc');
	// el.className now is 'aa bb cc',

K345.DOM.toggleClass(el, 'bb');
	// el.className now is 'aa cc',

K345.DOM.toggleClass(el, 'bb');
	// and now it's ' aa bb cc' again,

K345.DOM.replaceClass(el, 'bb', 'xx');
	// el.className now is 'aa xx cc',

K345.DOM.replaceClass(el, 'tt', 'mm');
	// el.className now is 'aa xx cc mm'.
	// replaceClass() acts like addClass() here, because class tt does not exist.

K345.DOM.replaceClass(el, 'rz', 'kk', true);
	// el.className still is 'aa xx cc mm'
	// no changes if third parameter is set to true and class rz does not exist.

K345.DOM.addOrRemoveClassIf(el, 'gg', n < 4);
	// condition truthy, el.className now is 'aa xx cc mm gg',

K345.DOM.addOrRemoveClassIf(el, 'aa', n > 4);
	// condition falsy, el.className now is 'xx cc mm gg

K345.DOM.addClass(el, 'foo bar');
	// will throw error because string contains whitespace
	// use K345.DOM.addClass(el, 'foo', 'bar') instead

K345.DOM.addClass([el, another_el], 'foo', 'bar');
	// foo and bar were added to both elements

Namespace

The default namespace of all methods is K345.DOM.

It is possible to add all methods to a custom namespace object or use them prefixed in global namespace (usually window in a browser).

K345.DOM.classAPI_NS(Object namespace | String prefix);
Namespace object
var myNS = { /* some stuff here */ };
K345.DOM.classAPI_NS(myNS);
myNS.addClass(el, 'foo');
Prefixed
K345.DOM.classAPI_NS('_');
_addClass(el, 'foo');

K345.DOM.classAPI_NS('$$');
$$addClass(el, 'foo');

All chars of prefix must be valid within variable names.

Code & Downloads