addEventHandler(element, eventType, handler[, useCapture [, userArg1 [, userArg2 … … …]]])

element *only when called as a functional

The DOM Element(s) to attach the event-handler to.  You may pass in a single Element, or a UniDOM ElementWrapper instance, or an array of Elements and/or ElementWrappers.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 2 arguments (plus any optional- & user-arguments), as the element is then figured by this method’s Object.

eventType

Event-types may be passed in with or without the prefixed “on” and are case-insensitive.  You may pass in a single event-type (as a String), or an array of event-types.  All event-types passed in will be “bound” to all elements passed in, and all event-handlers you pass in will be called upon by every one of these event-types.  Custom user-defined event types may be used.  With legacy versions of Micorsoft’s® Internet Exploder, since custom events can not be used as “listeners,” UniDOM keeps track of these and “manually fires” them using generateEvent.

handler

You may add a single event handler, or an array of event handlers (using one single call to addEventHandler()) to be called in order by the wrapper function.  That is, all handlers will be called by each eventType you add.  When you add [an] event handler[s], it/they is/are “wrapped” with an internal closure-function, and this wrapper is then the actual attached event handler.  Each handler added using addEventHandler() may be:

• a function (same as usual for standard DOM or MSIE)
• an Object with a generic “handleEvent” method (Mozilla® Firefox® style)
• an Object with a method to match the event type, i.e. myObject.onclick, myObject.onmouseover, myObject.onfocus, etc.  The method name must be the event-type in all lowercase, prefixed with “on”, regardless of how you registered it.

Preference given in reverse order from the above presentation;  therefore note in these example possibilities below that “mousemove” is logged in the console as “unhandled”: ===== myHandler=function(event) {console.log("myHandler unhandled "+event.type+" → "+event.target.name)}; myHandler.onclick=function(event) {… … …}; myHandler.onmouseover=function(event) {… … …}; myHandler.onmouseout=function(event) {… … …}; UniDOM.addEventHandler(element, ['click', 'mouseOver', 'mouseMove', 'mouseOut'], myHandler); ===== myObject={/*… … properties and methods, foos and bazes … …*/} myObject.handleEvent(event) {console.log("myObject unhandled "+event.type+" → "+event.target.name)}; myObject.onclick=function(event) {… … …}; myObject.onmouseover=function(event) {… … …}; myObject.onmouseout=function(event) {… … …}; UniDOM.addEventHandler(element, ['click', 'mouseOver', 'mouseMove', 'mouseOut'], myObject); ===== You may also pass in an Array of handlers and all will be called in order, so given the examples above, we can do: ===== anotherHandler=function(event) {/*… …handle all events… …*/}; UniDOM.addEventHandler(element, ['click', 'mouseOver', 'mouseMove', 'mouseOut'], [myHandler, myObject, anotherHandler]); ===== When using multiple event-handlers (in an Array), any one of them may change the property “doContinue” of the “event” object to “false” ( event.doContinue=false; ) to cancel calling the rest in the Array.  This will not cancel bubbling or capturing, and this will not cancel other event-handlers added using a separate call to “addEventHandler”.
¡¡¡Don’t forget an Array of event-handlers is {{live}}, so you can change it after you add it; therefore, additions to an Array of event-handlers are affected by and can effect “event.doContinue”!!!
In the example below (given the examples above), no “unhandled” events will be logged: ===== anotherHandler=function(event) { if (event.type=='mousemove') event.doContinue=false; //block the rest of the handlers in the handler-array /*… …handle all mouseMove events… …*/ }; UniDOM.addEventHandler(element, ['click', 'mouseOver', 'mouseMove', 'mouseOut'], [anotherHandler, myHandler, myObject]); ===== The value of the JavaScript™ keyword “this” within the added handler function or Object method will be as follows:

function	→ this= →	the Element to which the event handler was “added”
myObject.handleEvent	→ this= →	myObject
myObject['on'+event.type]	→ this= →	myObject

The wrapper sends to your handlers a hybrid EventObject which guarantees at least the following cross-browser properties:

event ={

id:	unique id generated for each event
target:	MSIE’s event.srcElement  →  the Element, Document, or Window that generated the event, i.e. a possible childNode of the “currentTarget” element during capture or bubble phases.
currentTarget:	element  →  the current element which is handling the event, to which an event handler is attached (value of “this” when an event-handler is attached to or is a property of an Element).
relatedTarget:	MSIE’s (event.fromElement || event.toElement) the Element from which the mouse is going/coming.
eventPhase:	1   ← when using MSIE, only when you employ the simulated capture phase.
eventPhase:	MSIE’s (event.srcElement===element) ? 2 : 3 where element is the one you attach the event to.  (2 is the “on target” phase; 3 is the bubbling phase; same as standards)
charCode:	MSIE’s event.keycode
offsetX:	↓→mouse offset from the “target” element:
offsetY:	↑→calculated for standards-complient browsers when applicable to the event type
currentX:	↓→mouse offset from the “currentTarget” element:
currentY:	↑→calculated for standards-complient browsers when applicable to the event type
stopPropagation:	with MSIE: function() {this.cancelBubble=true;} This will also stop propagation during the simulated capturing phase.
preventDefault:	with MSIE: function() {this.returnValue=false;}
MSIE:	true when using legacy DOM event-handling with old versions (IE9 & earlier) of Microsoft’s Internet Exploder; undefined otherwise.  Do note that IE9 can use standard DOM event-handling (as well as its legacy DOM package), and when using the standards, this property’s value will be undefined.
}

useCapture

Boolean: default=false  For Microsoft’s Internet Exploder, the “capturing phase” of an event is simulated, provided that both the “capturing” event handlers and any event handlers on descendent elements are registered with UniDOM.  See also the UniDOM.enable_oldMSIE_capture() function to guarantee this provision when also using third-party software that doesn’t use UniDOM.  You should use event.stopPropagation() as with the standard DOM, within any phase of the event.

userArg … … …

You may pass in any number of optional user arguments, and each will be passed as a unique argument to every one of your event handlers in your handler-array.  For example, you might have an HTML photo gallery, with photos displayed in order of popularity.  The page is loaded with the gallery, and on the side-bar you want to use JavaScript™ to add an alphabetized list of people who took each photo.  So your script would gather the images and their respective data, build the sidebar menu, and attach an onClick or onMouseOver event-handler to each menu item: //given an Object containing the <img/> tags // and an alphabetized array of objects holding the photographer’s name & rank: for (var i=0; i<data.length; i++) {   li=build_li_(data[i].name); // use your function defined elsewhere   UniDOM.addEventHandler(li, ['onMouseOver', 'onClick'], popPic, false,       images[data[i].imageName], data[i].imageName, data[i].photographer, data[i].rank, document.body); } // and now our popPic function is very generic, versatile, and easy to read: function popPic(event, imageTag, imageName, photographer, rank, container) {   var popup, old;   popup=document.createElement('div');   popup.appendChild(imageTag.cloneNode(false));   popup.appendChild(document.createTextNode(imageName + ' by ' + photographer + ': ' + rank + '%'));   popup.id='rank_popup';   if (old=document.getElementById('rank_popup'))     old.parentNode.replaceChild(old, popup);   else container.appendChild(popup);   if (event.type==='click') imageTag.scrollIntoView(); }

removeEventHandler(EventHandler_instance) //preferred removeEventHandler(element, eventType, handler, useCapture)

It is easiest to keep track of the UniDOM.EventHandler instance returned when you add an event handler.  In that case, you can simply use myEH.remove(); (see UniDOM.EventHandler).  If you want or need to, you may instead pass the whole EventHandler instance to this function.

If you don’t have access in the scope of a function to the EventHandler instance returned when the handler was added by UniDOM, you can use the long-form of this function instead (similar to the DOM standard way).

See getEventHandler (below) for info on the arguments passed in to this function when using its long-form.

getEventHandler(element, eventType, handler, useCapture)

If you don’t have access in the scope of a function to the UniDOM.EventHandler instance returned when the handler was added by UniDOM, you can use this function to get it.

element *only when called as a functional

The DOM Element the event-handler is attached to.  You may pass in a single Element, or a UniDOM ElementWrapper instance.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 3 arguments, as the element is then figured by this method’s Object.

eventType

You may pass in only one Event-type.  Event-types may be passed in with or without the prefixed “on” and are case-insensitive.

handler

You must pass in the same handler function that you added, or an array that contains the same handler functions in the same order.  Since a UniDOM.EventHandler array is {{LIVE}} (you can change it at any time) if you do change it after you “addEventHandler” you must pass in the modified current handler selection.

useCapture

must match the Boolean value you passed in when you added the event handler.

removeAllEventHandlers(element, [goDeep])

element *only when called as a functional

The DOM Element the event-handlers are attached to.  You may pass in a single Element, or a UniDOM ElementWrapper instance.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; the element is then figured by this method’s Object.

goDeep

Optional: default is false.  Whether to remove handlers from DOM childnodes and recursively their children.  See getElements for more details on the use of this parameter.

generateEvent(element, eventType, eSpecs)

For high-level event-creation.  This will create a new Event-Object and then dispatch/fire an event using it, and is cross-browser friendly.  For legacy versions of MSIE that do not recognize custom user-defined (synthetic) event-types, this method will simulate properly “firing” the custom event if it was registered using UniDOM’s addEventHandler.

element *only when called as a functional

The DOM Element to generate the event on.  You may pass in a single Element, or a UniDOM ElementWrapper instance.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 2 arguments, as the element is then figured by this method’s Object.

eventType

You may pass in one Event-type or an Array of Event-types.  Event-types may be passed in with or without the prefixed “on” and are case-insensitive.

eSpecs

An object with property names to define the specifications for the Event you want to generate.  Please refer to a good book on JavaScript™ for further info.  Note you must supply a value for eSpecs.view if you want to set any other explicit specifications (except eSpecs.bubbles and eSpecs.cancelable).  Some example specs are below for all browsers except old MSIE:

eSpecs.bubbles, eSpecs.cancelable	all Events
eSpecs.view, eSpecs.detail	UIEvents (includes key events and mouse events)
eSpecs.screenX, eSpecs.screenY, eSpecs.clientX, eSpecs.clientY, eSpecs.ctrlKey, eSpecs.altKey, eSpecs.shiftKey, eSpecs.metaKey, eSpecs.button, eSpecs.relatedTarget	MouseEvents
eSpecs.buttons, eSpecs.movementX, eSpecs.movementY, eSpecs.offsetX, eSpecs.offsetY, eSpecs.region, eSpecs.which	MouseEvents in newer browsers

For all browsers including old MSIE: if (eSpecs.userArgs) for (p in eSpecs.userArgs) {event[p]=eSpecs.userArgs[p];}

triggerEvent(element, event)

For low-level event-creation.  You must create your own new Event-Object (you can not reuse one once the event has occurred).  You must determine the proper method (old MSIE or standard) for creating your new Event-Object, but this function is then cross-browser friendly.  This method is currently not available in the “Element-prototype” programming style.

element *only when called as a functional

The DOM Element to dispatch the event on.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument, as the element is then figured by this method’s Object.

event

An Event-object created with your low-level code using document.createEvent or document.createEventObject.

enable_oldMSIE_capture()

If you want to use UniDOM’s simulated capture function with old versions Microsoft’s Internet Exploder, and you need to be able to use third-party JavaScript™ scripts at the same time, call this function before loading any third-party scripts.  This will modify the DOM’s ElementNode prototype “attachEvent” method to run through UniDOM’s script for compatibility; otherwise, third-party event-handlers can not be blocked during the simulated capture, or bubbling may occur twice. 

setMouseEventOffsets(event)

For Firefox® and other older browsers that do not support the non-standard event.offsetX, event.offsetY, event.currentX, and event.currentY properties introduced by MSIE.  This function is called automatically by UniDOM’s event-handler “wrappers” as needed, so there is no need to call this function independently if you use UniDOM.addEventHandler.  Note that this is only available in the functional programming styles, not as a method of an Element or ElementWrapper.

event

A standard event-Object (which holds the mouse position on the window).

getMouseOffset(element, event)

element *only when called as a functional

The DOM Element from which to figure the mouse position {x,y} distance.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument, as the element is then figured by this method’s Object.

event

A standard event-Object (which holds the mouse position on the window).

getScreenX(_window_) getScreenY(_window_)

These functions are only available in the functional programming styles.

_window_

Optional window-object reference; default is the current window the script is running in.

getInnerWidth(_window_) getInnerHeight(_window_)

These functions are only available in the functional programming styles.

_window_

Optional window-object reference; default is the current window the script is running in.

getScrollX(_window_) getScrollY(_window_)

These functions are only available in the functional programming styles.

_window_

Optional window-object reference; default is the current window the script is running in.

getDocumentWidth(_window_) getDocumentHeight(_window_)

These functions are only available in the functional programming styles.

_window_

Optional window-object reference; default is the current window the script is running in.

window.getComputedStyle(element)

For old versions of Microsoft’s Internet Exploder that don’t have a native version of this global function, UniDOM gives you a cross-browser shell-wrapper-function as defined below:

function getComputedStyle(element) {return element.currentStyle}

getElementOffset(element, [scroll]) getElementOffset(element, [ancestor])

element *only when called as a functional

The DOM Element from which to figure the offset distance {x,y} from either the •beginning of the document, or the •viewport (see scroll below), or the •ancestor.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style accepts only 1 optional argument, as the element is then figured by this method’s Object.

scroll

Optional Boolean: if true, the offset is figured from the top-left corner of the viewport.  The default value is false.

ancestor

If a DOM Element which is an ancestor to element is passed, the offset is figured from the ancestor instead of the document or viewport.

isElementNode(unknown)

unknown *only when called as a functional

The value to test.  You may pass in a single unknown value.  Do not pass in a value for unknown when using the ElementWrapper—based Object-oriented programming style; the value is then figured by this method’s Object.  Note that UniDOM’s Element-gathering functions can also gather DOM Nodes other than Elements, and these may then be wrapped with a UniDOM.ElementWrapper.  Note also that while this is primarily used as a functional (as UniDOM.isElementNode() or the equivalent as a global function) and also a —method— of an ElementWrapper, logically there is no equivalent method in UniDOM’s Element-prototype—based programming style.

getAncestor(element, cb [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document backwards to find the matching ancestor element of element, and possibly recursively its ancestors, depending on goDeep.

element *only when called as a functional

The DOM Element from which to begin crawling the document.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus any of the optional arguments), as the element is then figured by this method’s Object.

cb

Callback function: should decide whether each element passed to it is the ancestor of choice and return a Boolean value indicating such choice.

goDeep

Whether to (continue to) recursively check the parentNode(s) of the matching element(s).  May be: •Boolean (default is false for getAncestor methods, true for getElements methods) or a •function that evaluates each individual element passed to it and returns a Boolean value.  When goDeep is a function, a second argument is also passed to it referring back to the “context” element which was passed into this getAncestor function.  UniDOM’s getAncestor() and getElements() each work a little different depending on the value of goDeep.  With getAncestor() methods, goDeep is ignored until the first match is found.  If goDeep==false or alternatively goDeep()==false after a match is found, then the query ends and the matching ancestor(s) will be returned.

ojbFltr

An Object-property-name-filter function to enhance the returned Array value with named properties referring to members of the Array.  See: objectify.

applyDirect

Boolean:  ¿Apply “power methods” directly to returned arrays?  See the UniDOM.ElementWrapperArray constructor.

powerSelect

Boolean:  ¿Apply nonstandard methods (getSelected() & setSelected()) to <select> elements?  See: powerSelect.

getElements(element, cb [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document to gather the matching childNodes of element, and possibly recursively their children depending on goDeep.

element *only when called as a functional

The DOM Element from which to begin crawling the document.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus any of the optional arguments), as the element is then figured by this method’s Object.

cb

Callback function: should decide whether each element passed to it is the descendent of choice and return a Boolean value indicating such choice.

goDeep

Whether to recursively check childNodes of the element.  May be: •Boolean (default is true for getElements methods, false for getAncestor methods) or a •function that evaluates each individual element passed to it and returns a Boolean value.  When goDeep is a function, a second argument is also passed to it referring back to the “context” element which was passed into this getElements function.  UniDOM’s getAncestor() and getElements() each work a little different depending on the value of goDeep.  With getElements() methods, if goDeep=false then the children of each element will not be considered.  For getElements, getJuniors, and getElders methods, when goDeep is a function, it may also set the doContinue property of itself to false using the code arguments.callee.doContinue=false (or even the callback cb function may set goDeep.doContinue=false), and the query will terminate immediately.  Note that UniDOM always resets the doContinue property to true when it starts a query, so you don’t need to worry about resetting it.

ojbFltr

An Object-property-name-filter function to enhance the returned Array value with named properties referring to members of the Array.  See: objectify.

applyDirect

Boolean:  ¿Apply “power methods” directly to returned arrays?  See the UniDOM.ElementWrapperArray constructor.

powerSelect

Boolean:  ¿Apply nonstandard methods (getSelected() & setSelected()) to <select> elements?  See: powerSelect.

getJuniors(element, cb [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document of all DOM Elements following element (its childNodes and following siblings), and possibly recursively their children and ancestors’ following siblings depending on goDeep, to gather matching DOM Elements.  See getElements for details on arguments passed to this function, and the return value from this function.

This useful example below uses the getJuniors method; but it also exemplifies for getAncestor, getElements, and getElders how to use the callback cb function and how to pass a function for goDeep.  It also exemplifies using goDeep.doContinue, but that feature is not available for getAncestor since it is illogical: you simply pass false from goDeep() to achieve the same result of immediately terminating the query.

var goDeep=function(e) {return !(e.className.match( /\bdisabled\b/ ));},   cb=function(e) {   if (( (e.nodeName==='INPUT' && e.type==='text')   || e.nodeName==='TEXTAREA' )   && !e.disabled) {   goDeep.doContinue=false;   return true; }   else return false; },   nextTextIn=UniDOM.getJuniors(currentTextIn, cb, goDeep)[0];

getElders(element, cb [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document backwards of all DOM Elements preceding element (its preceding siblings and parentNode), and possibly recursively their children and ancestors’ previous siblings depending on goDeep, to gather matching DOM Elements.  See getElements for details on arguments passed to this function, and the return value from this function, except:  ¡Note that the returned array is in reverse order from the document contents!

hasAncestor(element, unknown)

Crawls (transverses) the document to see if unknown is an ancestor of element.

element *only when called as a functional

The DOM Element from which to begin crawling the document.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument, as the element is then figured by this method’s Object.

unknown

The variable you want to check to see if it is an ancestor of element.

hasElement(element, unknown)

Crawls (transverses) the document to see if unknown is a descendent of element.  Note that this function is the inverse of hasAncestor; internally it uses the code hasAncestor(unknown, element) which is faster than transversing the DOM tree forward through all branches.  But also note that unknown may be any value, whereas element should be a DOM element node; this function therefore gives the user two advantages: a logical syntax that is easy to understand when read, and an extra condition to check that unknown is indeed an element before internally calling hasAncestor which requires its first argument to be an element.

element *only when called as a functional

The DOM Element from which to begin crawling the document.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument, as the element is then figured by this method’s Object.

unknown

The variable you want to check to see if it is a descendent of element.

getElementsByName(element, name [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document to gather the matching childNodes of element, and possibly recursively their children depending on goDeep. See getElements for details on arguments other than name passed to this function, with the following exception:  ¡Note that this function is unique in that it supplies a default objFltr-function which will add object-property names to the returned array that match the name attributes of the selected Elements!

name

Each Element’s name attribute is compared with the name you pass into this function.  You may pass in a String, a Regular-Expression, or a “logic-Array” of Strings, Regular-Expressions, and/or more nested “logic-Arrays”.  See UniDOM’s has function for more info on “logic-Arrays”.  If you don’t pass in a value for name (or pass in null or an empty string) all elements with a name attribute will be collected (typically, <input>s, <textarea>s and <select>s).

getAncestorByClass(element, className [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document to gather the matching ancestor(s) of element. See getAncestor for details on arguments other than className passed to this function, and the return value from this function.

className

Each Element’s className attribute is “properly” compared with the className you pass into this function.  See hasClass for detailed information.

getElementsByClass(element, className [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document to gather the matching childNodes of element, and possibly recursively their children depending on goDeep. See getElements for details on arguments other than className passed to this function, and the return value from this function.

className

Each Element’s className attribute is “properly” compared with the className you pass into this function.  See hasClass for detailed information.

getAncestorByComplex(element, conditions [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document to gather the matching ancestor(s) of element. See getAncestor for details on arguments other than “conditions” passed to this function, and the return value from this function.

conditions

Should be an Object with two properties: data and filter.  data should be a “logic-Array,” and filter should be a callback function that decides whether each Element passed to it passes each “condition” of the logic array.  See UniDOM’s has function for more info on using filter callback functions with “logic-Arrays”.

getElementsByComplex(element, conditions [, goDeep [, objFltr [, applyDirect [, powerSelect]]]])

Crawls (transverses) the document to gather the matching childNodes of element, and possibly recursively their children depending on goDeep. See getElements for details on arguments other than “conditions” passed to this function, and the return value from this function.

conditions

Should be an Object with two properties: data and filter.  data should be a “logic-Array,” and filter should be a callback function that decides whether each Element passed to it passes each “condition” of the logic array.  See UniDOM’s has function for more info on using filter callback functions with “logic-Arrays”.

hasClass(element, className [, logic])

element *only when called as a functional

The DOM Element who’s class name to check.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus 1 optional argument), as the element is then figured by this method’s Object.

className

The Element’s className property (similar to its className attribute) is “properly” compared with the className you pass into this function.  You may pass in a •String, a •Regular-Expression, a •callback Function, or a •“logic-Array” of Strings, Regular-Expressions, callbacks, and/or more nested “logic-Arrays”.  ¡Note how hasClass() works differently when using a String compared with getElementsByClass() and getAncestorByClass()!  If you pass in multiple class names as a string with a space, the className property (attribute value) of a matching element must have these class names in the given order, adjacent to each-other.  For example, given four elements: <div class='foo bar'> <div class='baz foo bar buz'> <div class='foo buz bar'> <div class='bar foo'> only the first two match hasClass( 'foo bar' )
but all four match hasClass( ['foo', 'bar'] )
You can use this fact to style Elements with CSS in a similar fashion, but gather them for use by JavaScript™ in different groups. ¡Contrast this with getElementsByClass() and getAncestorByClass() which convert a single-string with spaces to an Array before internally calling hasClass()!  So: getElementsByClass( 'foo bar' ) ≡≡≡ hasClass( ['foo', 'bar'] ) getElementsByClass( ['foo bar'] ) ≡≡≡ hasClass( 'foo bar' ) getElementsByClass( ['foo', 'bar'] ) ≡≡≡ hasClass( ['foo', 'bar'] ) getElementsByClass( ['foo bar', 'buz'] ) ≡≡≡ hasClass( ['foo bar', 'buz'] ) ← matches only the second div in the above example Note that the examples above demonstrate the fact that when className is a “logic-Array,” the Boolean logical relationship between Array members is “and;” that is, all array members must match the Element’s className.  You may change this logical relationship between members by setting the “logic” property of this Array, or by passing a value for logic (see below). Given the four <div> elements in the example above, mySub=['baz', 'buz']; mySub.logic='xor'; hasClass(['foo', 'bar', mySub]); Above matches <div class='foo fuq bar buz'> and matches only the third <div> above. See UniDOM’s has function for more info on “logic-Arrays.”
In addition to the relational logic in a “logic-Array,” you may also prefix any string you pass in with the ! character for logical “not.”  Using the example HTML of 4 <div>s given above, the following example matches only the third <div>: hasClass(['buz', '!baz']);  while hasClass(['foo', 'bar', '!foo bar']) only matches the last two <div>s.  Note then how '!foo bar' negates the complete string, not just the first className foo.  And finally, any Regular Expression or callback Function that you pass in as a className may have a property, “not,” that will negate its evaluated return value.  In the example below, an online restaurant menu may have a section that lets users choose certain food-groups or ingredients that they either prefer or don’t want.  You could create one RegExp and toggle its “not” property: // high-calibre example: myViceToAvoid=new RegExp( 'cheese', 'i' ); myViceToAvoid.not= (UniDOM.getElementsByName(dinner_menu_form, 'cheese').getSelected().value==='no'); // ===true myClassnameQuery = [ "dinner", "!Italian", /salad/, myViceToAvoid ]; //pasta and cheese line the gut with paper-maché // above matches: "dinner Peruvian Andes_salad blackBeans" // above matches: "Mexican pintoBeans dinner Acapolco_salad" // but not: "dinner Italian Caesar_salad parmaseanCheese" // but not: "lunch Greek_salad feta_cheese" // continuing example: myClassnameQuery.logic='or' // above matches: "dinner Peruvian Andes_salad blackBeans" // above matches: "Mexican pintoBeans dinner Acapolco_salad" // above matches: "dinner Italian Caesar_salad parmaseanCheese" // above matches: "lunch Greek_salad feta_cheese" // continuing example: myClassnameQuery.logic='xor' // no match: "dinner Peruvian Andes_salad blackBeans" // no match: "Mexican pintoBeans dinner Acapolco_salad" // no match: "dinner Italian Caesar_salad parmaseanCheese" // no match: "lunch Greek_salad feta_cheese" // above matches: "lunch Italian Greek_salad feta_cheese"

logic

If you pass in a “logic-Array” for the className, you may set its “logic” property by passing it as an optional last argument.  This facilitates easy function calling with one step instead of 3: hasClass(['cats', 'dogs'], 'xor');   vs. var query=['cats', 'dogs']; query.logic='xor'; hasClass(query);

addClass(element, className)

element *only when called as a functional

The DOM Element who’s class name to add to.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus 1 optional argument), as the element is then figured by this method’s Object.

className

Must be a String of the class-name to add, or an array of these.  Each className String is added to element’s className, if it does not exist already.  Note this function is indiscriminate when a className String has two or more space-separated class-names, in that it will not allow you to add "foo bar" to the existing className "baz foo bar buz", but you can add it to the existing className "bar baz foo buz".  You should instead pass an array: ['foo', 'bar'].  It also does not check the validity of the className you pass in.  This function also automatically cleans extra white-space from the element’s existing/final className.

removeClass(element, className)

element *only when called as a functional

The DOM Element who’s class name to remove from.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus 1 optional argument), as the element is then figured by this method’s Object.

className

Must be a String of the class-name to remove, a Regular-Expression to match the class-name to remove, or an array of these.  All copies of the className String are removed from the element’s className.  Note this function is indiscriminate when a className String has two or more space-separated class-names, in that it will allow you to remove "foo bar" from the existing className "baz foo bar buz", but you can not remove it from the existing className "bar baz foo buz".  You should instead pass an array: ['foo', 'bar'].  This function also automatically cleans extra white-space from the element’s existing/final className.

useClass(element, className, flag)

element *only when called as a functional

The DOM Element who’s class name is to be modified.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus 1 optional argument), as the element is then figured by this method’s Object.

className

Must be a String or an array of Strings, of the class-name to add or remove (depending on flag).  See addClass and removeClass for more info, except that note that since the addClass function does not use Regular-Expressions, neither can this one.

flag

Boolean: whether to add (flag=true) or remove (flag=false) the className.

swapOutClass(element, removals, additions)

At least one browser I’ve seen will update the DOM immediately upon changing a className as opposed to changing a style-attribute of an Element, which may be postponed until the current (event) function is complete.  So if you remove a class in one statement and add another in the next, you still get a “farc-flash” effect displayed to the user.  Use this for less farc. 

element *only when called as a functional

The DOM Element who’s class name is to be modified.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus 1 optional argument), as the element is then figured by this method’s Object.

removals

See removeClass’ className description.

additions

See addClass’ className description.

disable(element, flag [, className])

When you disable/enable a document section, the containing element has the className (or its default) added/removed, and its “disabled” property is set to equal flag.  All descendents of element that can accept user input or keyboard “focus” also have their “disabled” property set to equal flag, excepting that if you disable a section «A», as well as a sub-section «B» of «A», when you then enable (flag=false) section «A», its sub-section «B» will remain disabled if you pass in the same className (or use the default) for both section «A» and its sub-section «B».

For standards-complient browsers that have the capability (not legacy versions of Micorsoft’s Internet Exploder), an “onDisabledStateChange” event is also fired/triggered on the element as well as on all of its above-noted user-input descendents.  The Event-object passed into your onDisabledStateChange handler will have a property (event.disable) with a Boolean value corresponding to flag.

element *only when called as a functional

The DOM Element containing the document section to be disabled.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus 1 optional argument), as the element is then figured by this method’s Object.

flag

Boolean: whether to disable (flag=true) or enable (flag=false) this document section.

className

Must be a String or an array of Strings, of the class-name(s) to add or remove (depending on flag).  The default value for className is “disabled”.  See addClass and removeClass for more info, except that note that since the addClass function does not use Regular-Expressions, neither can this one.

has(element, data, filter) Object.has(data, filter) SoftMoon.WebWare.objHas(obj, data, filter)

UniDOM’s has method is a simple but flexible “logic engine” that allows a programmer to write code that can easily create complex, powerful, and highly specialized dynamic queries in real-time.  This tool is the heart of all of UniDOM’s query functions/methods.  But it is flexible enough to work with any JavaScript™ Object.  So not only is it available as a function/method to work with the DOM, it is also available in “raw” form as a static property of the JavaScript™ constructor Object.  (Note that this is not a property of Object.prototype — don’t confuse this fact.)  You can use it like this:

MyObject={foo: "bar", fi: "buz", fo: "baz", fum: "boz"}; // this way allows you to do many queries simply: MyObject.has=Object.has; MyObject.has(data,filter); //now perform a query on myObject // this way allows you to do one query fast: Object.has.call(MyObject, data, filter); myElement=document.getElementById('myElement'); query_result=UniDOM.has(myElement, data, filter); //functional style query_result=UniDOM(myElement).has(data, filter); //Object-oriented wrapper style // or prototypify the DOM at page load UniDOM.prototypify(); query_result=document.getElementById('myElement').has(data, filter); //prototypical style: makes it simple

There are many practical examples shown for hasClass that demonstrate basic “logic-Arrays.”  The UniDOM functions that utilize this “has” method accept a “logic-Array” and then use a filter function similar to this one used by hasClass shown below:

function(e, c) { //is passed one className in the “logic-Array“ at a time var not=false; if (typeof c === 'function') return c(e)^c.not; if (typeof c !== 'object' || !(c instanceof RegExp)) { if (typeof c == 'string' && c.charAt(0)==='!') {c=c.substr(1); not=true;} c=new RegExp('\\b'+c+'\\b'); } return (not || c.not) ? (e.className.match(c)===null) : e.className.match(c); }

element *only when called as a functional

The DOM Element to query.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus 1 optional argument), as the element is then figured by this method’s Object.

data

A random-length “logic-Array” of a user-defined set of “conditions” to be met.  Data members that have a “logic” property should be Arrays that are considered a sub-set of conditions; and this is recursive, so you may have deeply nested sub-set “logic-Arrays.”  The “logic” property may be any of the following (strings) ('and' is default if no “logic” property is defined): 'and' 'or' 'nor' 'not' 'nand' 'xor' 'xnor' 'xnot' (“nor” and “not” have the same logical meaning)  Note that these logical operators take on a slightly new, expanded meaning, as they can operate on multiple values, not only two.  For example: ([false, true, true]).logic='or' // logic-Array evaluates to true ([false, true, true]).logic='xor' // logic-Array evaluates to false ([false, true, true]).logic='and' // logic-Array evaluates to false ([false, true, true]).logic='xnor' // logic-Array evaluates to false ([false, true, true]).logic='nand' // logic-Array evaluates to true ([false, true, true]).logic='not' // logic-Array evaluates to false ([false, true, true]).logic='xnot' // logic-Array evaluates to true

filter

Your filtering function should accept the arguments: filter(obj, query_condition) and should return true if “query_condition” is met, false if not.  The filter function receives the Object that UniDOM’s has is applied as a method of (either the DOM Element or a user-Object) as the first argument, and individually each of the members of the data “logic-Array,” excepting if any of these members is itself (recursively) a sub-set “logic-Array,” its individual members will each be passed to the filter function.

objFltr objectify(filter [, applyDirect [, powerSelect]]) Array.objectify(filter) SoftMoon.WebWare.objectifyArray(arr, filter)

For functions/methods that return UniDOM.ElementWrapperArrays (really just a simple Array with some standard methods & properties tacked on), additional “named” properties may be added to the Array, holding members of the Array for quick access in the future without having to know which Array-member (integer) contains the needed element(s). If the filter (a.k.a. objFltr) callback Function returns the same property name for two or more elements in the Array, the property will then hold another UniDOM.ElementWrapperArray containing the multiple elements.

==== example: // first we pass in an “objFltr” directly through the “getElementsByClass” method → ↓ myElementsArray = UniDOM.getElementsByClass(myPageSectionElement, /^my...Blocks/ , true, function(e) {return e.className.match( /_(.+)$/ )[1];} ); // then we further “objectify” the “UniDOM.ElementWrapperArray” with a second “filter” myElementsArray._.objectify( function(e) {return e.className.match( /my(...)Blocks/ )[1];} ); // myElementArray results might return something like this Array-Object (note it IS a real JavaScript™ Array): { [0] → <div id='b0' class='mySqrBlocks _red'> [1] → <div id='b1' class='mySqrBlocks _green'> [2] → <div id='b2' class='mySqrBlocks _blue'> [3] → <div id='b3' class='mySqrBlocks _yellow'> [4] → <div id='b4' class='myTriBlocks _blue'> [5] → <div id='b5' class='myTriBlocks _green'> [6] → <div id='b6' class='myLogBlocks _green'> [7] → <div id='b7' class='myLogBlocks _blue'> [length] → 8 [_] → the “UniDOM power methods” object for this Array [red] → <div id='b0' class='mySqrBlocks _red'> [green] → [ <div id='b1' class='mySqrBlocks _green'> , <div id='b5' class='myTriBlocks _green'> , <div id='b6' class='myLogBlocks _green'> ] ← the “power methods” for this Array are also available through its Array._ [blue] → [ <div id='b2' class='mySqrBlocks _blue'> , <div id='b4' class='myTriBlocks _blue'> , <div id='b7' class='myLogBlocks _blue'> ] ← the “power methods” for this Array are also available through its Array._ [yellow] → <div id='b3' class='mySqrBlocks _yellow'> [Sqr] → [ <div id='b0' class='mySqrBlocks _red'> , <div id='b1' class='mySqrBlocks _green'> , <div id='b2' class='mySqrBlocks _blue'> , <div id='b3' class='mySqrBlocks _yellow'> ] [Tri] → [ <div id='b4' class='myTriBlocks _blue'> , <div id='b5' class='myTriBlocks _green'> ] [Log] → [ <div id='b6' class='myLogBlocks _green'> , <div id='b7' class='myLogBlocks _blue'> ] }

But it is flexible enough to work with any JavaScript™ Array.  So not only is it available as a function/method to work with DOM query results, it is also available in “raw” form as a static property of the JavaScript™ constructor Array.  (Note that this is not a property of Array.prototype — don’t confuse this fact.)  You can use it like this:

myArray=["bar", "buz", "baz", "boz"]; Array.objectify.call(myArray, filter); //or if it better suits your coding style and/or needs: myArray.objectify=Array.objectify; //do this once… myArray.objectify(filter); // do this as many times as you need with different filters.

arr

The array to objectify.

objFltr
filter

Pass in a callback-function as the filter (a.k.a. objFltr) which should return a property-name (¡numerical values may override existing array members!) for the element passed into the callback, to be added as an Object-property to the finally-returned Array.  ¡¡¡ the returned Array may have nonstandard properties added to <select> elements if you pass “true” for powerSelect !!!  Each added property usually reflects a single member of the returned Array.  If the filter callback returns the same name for multiple elements in the returned Array, the added property will be a sub- Array of elements, each reflecting a member of the overall returned Array.

applyDirect

Boolean:  ¿Apply “power methods” directly to sub-arrays when multiple elements share the same property name?  See the UniDOM.ElementWrapperArray constructor.

powerSelect

Boolean:  ¿Apply nonstandard methods (getSelected() & setSelected()) to <select> elements?  See: powerSelect.

powerSelect getSelected(forceReturnArray) setSelected(value) UniDOM.addPowerSelect(select) UniDOM.getSelectedOptions(select [, forceReturnArray]) UniDOM.setSelectedOptions(select, value) UniDOM.powerSelect=true

When using UniDOM’s “element-gathering” functions/methods that return UniDOM.ElementWrapperArrays (really just a simple Array with some standard methods & properties tacked on), or when using the objectify method, you may pass in a final optional Boolean argument “powerSelect” which will add nonstandard methods (getSelected() & setSelected()) directly to <select> elements.  These methods mirror the same methods that are found on the returned ElementWrapperArrays.  You can then write code that can get/set either a <select> or a group of <input>s in a UniDOM.ElementWrapperArray without worrying about if the form-format may change a little in the future, giving more flexibility to the HTML developer. Consider an online menu where users can choose one large side item and one small side item:

==== example: name of the element(s) that match ↓ ↓deep ↓ returns “objectify” property names applyDirect↓ ↓powerSelect   sideOrders = UniDOM.getElementsByName(myMenu, /sideOrders/, true, function(e) {return e.name.match( /\[(.+)\]/ )[1]}, true, true)   largeSide = sideOrders.large.getSelected().value;   smallSide = sideOrders.small.getSelected().value;

May return something like:

  sideOrders =  { //Array-Object: a UniDOM.ElementWrapperArray ← also has standard “power methods” “applied directly” (too many to list)   [0] → <input type='radio' name='sideOrders[large]' value='baked potato with cheese' />   [1] → <input type='radio' name='sideOrders[large]' value='cheesy broccoli' />   [2] → <input type='radio' name='sideOrders[large]' value='vegi-baked beans with cheese' />   [3] → <input type='radio' name='sideOrders[large]' value='Greek salad' checked='checked'/>   [4] → <select name='sideOrders[small]'> ← has options (these options are NOT “in” this array):   <option value='snow peas' selected='selected'>   <option value='string beans'>   <option value='creamed corn'>   [length] → 5   [_] → the “power methods” object for this Array - they are also “applied directly,” but they are not shown here for space limitations   [large] → { //Array-Object: a UniDOM.ElementWrapperArray ← also has standard “power methods” “applied directly” (too many to list)   [0] → <input type='radio' name='sideOrders[large]' value='baked potato with cheese' />   [1] → <input type='radio' name='sideOrders[large]' value='cheesy broccoli' />   [2] → <input type='radio' name='sideOrders[large]' value='vegi-baked beans with cheese' />   [3] → <input type='radio' name='sideOrders[large]' value='Greek salad' checked='checked'/>   [length] → 4   [_] → the “power methods” object for this Array   }   [small] → <select name='sideOrders[small]'> ← has options (these options are NOT “in” this array):   <option value='snow peas' selected='selected'>   <option value='string beans'>   <option value='creamed corn'>  }   largeSide='Greek salad'   smallSide='snow peas'

Now we can develop an online-menu manager software-package that allows restaurant managers to manage their menu which may change daily based on locally available ingredients or the chef’s specials, etc.  The restaurant manager can choose a <select> or list of <input>s for the ingredients or menu items, and the high-end JavaScript™ logic that puts together a customer’s order need not worry about the form’s format.  How's that go?……write less, do more… …

Also provided, the UniDOM.addPowerSelect() function will add nonstandard methods getSelected() & setSelected() directly to <select> elements;  and the static functions UniDOM.getSelectedOptions() & UniDOM.setSelectedOptions() are available if you don’t want to tarnish the DOM.

powerSelect

(The final optional argument passed into UniDOM’s “element-gathering” (and other) methods.)  Boolean: ¿Add nonstandard methods (getSelected() & setSelected()) to <select> elements?

forceReturnArray

Boolean.  The getSelected methods by default will return a single <input type='radio'> element from a UniDOM.ElementWrapperArray, or a single <option> element from a <select>-one field.  In opposition, by default it will return an Array of one or more <input type='checkbox'> elements, or an Array of one or more <option> elements from a <select>-multiple field.  By default it will return null if there are none checked or selected.  By passing a Boolean value for forceReturnArray you may override these defaults:  passing true will always return an array, with zero, one, or more elements as members; and passing false will return only one element (no Array) if only one is checked or selected. 

value

String or an Array of Strings.  Any <input> or <option> (of a UniDOM.ElementWrapperArray or <select> element) with a value attribute, or the text of an <option>, that matches the value (or if value is an Array, one of its members) you pass into the setSelected() method will be checked or selected.

select

The <select> element you want to empower with getSelected() & setSelected() methods.

UniDOM(element [, applyDirect]) UniDOM(ElementWrapper [, applyDirect]) UniDOM(CSSQueryString [, applyDirect]) ↑ the third argument, passData, must be ==false (or undefined) UniDOM(element‖ElementWrapper, CSSQueryString [, applyDirect]) UniDOM(eArray [, applyDirect [, passData]]) UniDOM(element‖ElementWrapper‖eArray‖userData, applyDirect, passData=true)

The basic UniDOM() function is a catch-all for creating ElementWrappers with UniDOM’s “power-methods” to work on your chosen DOM element(s).  It is the basis for using the “wrapper-based Object-oriented programming style.”  In this respect, it is similar in function to jQuery’s “$”.  However in contrast, note UniDOM’s “$” function only acts as a CSS-selector-query Engine without “wrapping” the gathered elements.

element

The DOM element you want to wrap with UniDOM’s ElementWrapper power methods.

ElementWrapper

The UniDOM.ElementWrapper containing the DOM element you want to “re-wrap” with UniDOM’s power methods.  (note technically “wrappers” are just Objects that “point” to the element, and only give the illusion of “wrapping-around,” so you may have as many ElementWrappers pointing to a single element as you want, and none will be “wrapped-around” interfering with another)

CSSQueryString

A Cascading-Style-Sheet category of a query-string to gather DOM elements that will each be individually wrapped with UniDOM.ElementWrappers, and collected in a UniDOM.ElementWrapperArray.  See UniDOM’s “$” function for more info.  ¡Note that you may not pass true for the passData argument (see below) if you want to use this query-string as the first argument!

eArray

An Array that may contain any number of legal arguments for the first value passed to this UniDOM function including nested Arrays.  Each member (recursively) will be “wrapped” in UniDOM.ElementWrappers, and the group of them will be returned in one (or more when nested) UniDOM.ElementWrapperArray(s).

userData

Any type of data may be passed through the UniDOM() function when its passData argument is true.  See passData below.

applyDirect

Boolean: this flag does not affect the ElementWrapper created with UniDOM(), rather it is passed on automatically to any of UniDOM’s power methods that are called on the wrapper, and when they return a UniDOM.ElementWrapperArray this applyDirect flag will affect whether UniDOM’s power methods will be added directly to the said returned ElementWrapperArray.  See UniDOM.ElementWrapperArray for more details.

passData

This argument is used internally by UniDOM’s ElementWrapperArray “power-methods” to pass raw data returned by the methods through the UniDOM() function without error or confusion of data-type.  There is generally no reason for you to need to use it; however if you want to play “hackey-sack” with it, go ahead…  Passing true for this argument will still “wrap” elements, “rewrap” existing ElementWrappers, and array members of these two former; and this passData value will be simply ignored in those cases.  In contrast, when passData=true, passing a String for the first argument will simply return the string as user-data instead of treating the string as a CSS selector to gather elements;  and as well, passing through any other variable-type for the first argument is simply passed back instead of throwing an Error.

$(CSSQueryString , element [, objFltr [, applyDirect [, powerSelect]]])

UniDOM’s “dollar–sign” function/method $ integrates UniDOM’s total functionality with the “CSS-Engine” of your choice.  UniDOM does not have an Engine of its own (but given enough free time I plan on writing one that utilizes UniDOM’s powerful “has” method) but it will automatically use the standard JavaScript™—DOM interface method querySelectorAll if it is available, or else look for “Sizzle” (jQuery’s Engine) or “Slick” (MooTools’ Engine) (see: http://sizzlejs.com/  &  http://mootools.net/docs/core/Slick/Slick).  Of course you may specify exactly which CSS-Engine to use including any other similarly compatible.  See the UniDOM.CSSEngine property specs below.

¡Note that if you call UniDOM.globalize() to use the global-functional programming style, this method’s name $ will over-write any same-named variable in the window, commonly used by jQuery and many other toolkits!

CSSQueryString

String: A standard Cascading-Style-Sheet type of description to identify the Elements to be “gathered.”  The exact specifications of this query String may very slightly depending on the “CSS-Engine” you use.  Please refer to a good tutorial on using the native JavaScript™ querySelectorAll method, or if using “Sizzle” or “Slick” (or another CSS Engine), their documentation.

element *only when called as a functional

The DOM Element from which to begin crawling the document.  You may pass in a single Element, or a UniDOM ElementWrapper.  Do not pass in a value for element when using ElementWrapper— or prototype— based Object-oriented programming styles; using an Object-oriented style requires only 1 argument (plus any of the optional arguments), as the element is then figured by this method’s Object.

ojbFltr

An Object-property-name-filter function to enhance the returned Array value with named properties referring to members of the Array.  See: objectify.

applyDirect

Boolean:  ¿Apply “power methods” directly to returned arrays?  See the UniDOM.ElementWrapperArray constructor.

powerSelect

Boolean:  ¿Apply nonstandard methods (getSelected() & setSelected()) to <select> elements?  See: powerSelect.