/*** common-dom.js - commonly used DOM-like methods
   *
   */

var JS_DOMCOMMON_LOADED = true;     	
var JS_DOMCOMMON_FILE = 'dom-common.js';		
var JS_DOMCOMMON_VERSION = '0.1';
var JS_DOMCOMMON_BUILD_DATE = '2006/02/06';
  
/** debug stub */
function TRACE() {}
   
/****
	* getElementsByAttribute() 
	*	- returns array of elements where given attribute name & value match a node in the document
	* @attr - attribute name each node needs to be filtered
	* @value - value of the attr to
	* @tag - name of elements to filter. accepts class/value. use "*" for any node, but note early Safari compatability issues
	*/ 
function getElementsByAttribute()
 {
 
 	var options = arguments[0]; // params
	var o = new Array(); // array of elements to return
	
	TRACE('options.attr', options.attr );
	TRACE('options.value', options.value );
	TRACE('options.tag', options.tag );	

	/** return false where baseline DOM method is unsupported */
 	if (! document.getElementsByTagName ) 
		{ TRACE( 'document.getElementsByTagName is unsupported' );  return false; }
		
	/** option.value must be a regular expression */
	if ( typeof ( options.value ) != 'regexp' ) 
		{
		TRACE('options.value.constructor must be a RegExp, found ... ', typeof( options.value ) ); 
			
		/** attempt to cast to regexp if what we've found is a string */
		if ( typeof( options.value ) == 'string' ) 
			{ options.value = new RegExp( options.value ,"i" );
			  TRACE('But options.value.constructor is a String, and i\'ve successfully cast it, so don\'t worry'); }
		else 
			{ return false; }
		}
	
	// where no tagname given, default to * (all) elements
	if ( options.tag == '' || options.tag == null )
		options.tag = "*";

	// assign required elements/tags to t		
	var t;
	if ( options.tag == "*" && document.all ) // additional IE5 support for getElementsByTagName("*")
		t = document.all
	else
	 	t = document.getElementsByTagName( options.tag );

	TRACE( 'found '+t.length+' elements using '+options.tag )
	
	/** no elements found */
	if ( t.length < 0 ) 
		{ return false; }

	/** switch on the type of attribute */
	for ( var i = 0; i < t.length; i++ )
	 {
	 	var a; // attribute value
	 	switch ( options.attr )	
		{
		  case 'class' : 
			a = t[i].className;
			break;
			
		  case 'value' :
		 	a = t[i].value;
			break;
		 
		  default :	
			a = t[i].getAttribute( options.attr ); 
		 }
			
		TRACE( 'matching '+options.attr+' with '+a );
		
		// execute regular expression on attribute string
		if ( options.value.exec( a ) != null )
		  { o[ o.length ] = t[i]; // push element to array where matched
		  	TRACE('found matching attr/value, o now equals ' + o.length ); }
	 }
	
	return o;
 }
 
/****
	* toggleElement()
	* - simple, generic hide/show toggle for any document element. returns true where toggle has been successful.
	* @o - an element object 
	*/
function toggleElement( o )
{

	/** check for style property */
	if (! o.style )
	 { TRACE("node has no style property on which to operate");
		return false; }
		
	/** perform the toggle */
	o.style.display = ( o.style.display != 'none' ) ? 'none' : '';
		 
	return true;
}