DOMAssistant Core Module
The DOMAssistant Core module is required and it lays the groundwork for all DOMAssistant functionality. It consists of core functionality and a few important methods to work with.
$(cssSelector/elementRef)
The $ method is used to get a reference to one or several elements. It supports a CSS selector as a string, or an already established element reference. It will return the matching element(s) with all the extra DOMAssistant methods applied. A call of any of those methods will fail silently, if the $ method returned an empty array.
Parameters
Send in a CSS selector or an object reference.
Return value
Always return an array of matching elements for a CSS selector. If one single object is sent in, it return that same reference, and if several object references are sent in, it will return an array of those.
Example calls
$("#container input[type=text]");
$("#navigation a");
$("#news-list");
$("#container", "#navigation .important-item", "#content");
$(document.body);
$$(elementId)
The $$ method is used to get a quick reference to one element, just like document.getElementById. It will return a direct reference to the found DOM element, with all the DOMAssistant methods applied to it.
Contrary to the $ method, if the $$ method didn't return any match, it will throw an error if you try to call any method on it.
Parameters
Send in the id of the element you're looking for.
Return value
Returns a DOM reference.
Example calls
$$("container");
$$("navigation");
cssSelect(cssSelector)
Intended to be used on existing object references, to use a CSS selector to find children element(s) of the current object.
Parameters
- cssSelector
- Used to select elements. Required.
Return value
All calls return an array of element references.
Example calls
$(document).cssSelect(".mandatory");
$$(DOMElementReference).cssSelect(".important[type=test]");
elmsByClass(className, tag)
For getting elements based on their className. The method has a required parameter which is the desired className, and one optional if you want to limit the search to a certain tag.
Parameters
- className
- Class name to search for. Required.
- tag
- Only search elements that have this tag name. Optional.
Return value
All calls return an array of element references.
Example calls
$("#container").elmsByClass("mandatory");
$$("container").elmsByClass("external-link", "a");
elmsByAttribute(attr, attrVal, tag)
For getting elements based on if they have a certain attribute. You can also specify if that attribute should have a speific value and if you want to limit the search to a certain tag. Only the first parameter specifying the attribute is required.
Parameters
- attr
- Attribute name to look for. Required.
- attrVal
- Value that the desired attribute has to have. Optional. Use wildcard character ("*") if you want any attribute value but still want to specify
tag. - tag
- Only search elements that have this tag name. Optional.
Return value
All calls return an array of element references.
Example calls
$("#container").elmsByAttribute("href");
$$("container").elmsByAttribute("name", "subscription");
$$("container").elmsByAttribute("type", "text", "input");
elmsByTag(tag)
For getting elements based on their tag, i.e. what element it is. The method has one required parameter which is the name of the desired tag.
Return value
All calls return an array of element references.
Parameters
- tag
- Tag name to search for. Required.
Example calls
$$("container").elmsByTag("input");
hasChild(elementRef)
Returns true if elementRef is a descendant of the current element.
Return value
True if elementRef is a child (direct or non-direct), false otherwise.
Parameters
- elementRef
- An element reference of the item to test for.
Example calls
if (outerElm.hasChild(innerElm))
alert("innerElm is a child of outerElm!");
prev()
Gets a reference to the previous HTML element, automatically bypassing any text nodes that might be in between.
Parameters
None.
Return value
Element's previous sibling element.
Example calls
$("container").prev();
next()
Gets a reference to the next HTML element, automatically bypassing any text nodes that might be in between.
Parameters
None.
Return value
Element's next sibling element.
Example calls
$("container").next();
each(functionRef)
For running a function on each of the items in a returned array element reference collection.
Return value
All calls return either a single element reference or an array of element references.
Parameters
- functionRef
- Function which will be called for each item in the array of elements it's called on. Can be an anonymous function or a function reference. Traversal can be terminated by returning false in the function. This function is invoked with three arguments: the current item, the index of the item, and the element collection being traversed.
Example calls
$("#navigation a").each( function(elm, idx, set) {
alert("This is item " + idx);
if (idx === 5) return false; //Stop counting after 5
});
indexOf(elementRef)
Returns the index of the first occurrence of the item within the collection of elements.
Return value
Zero-based index of the element if found, and -1 otherwise.
Parameters
- elementRef
- An element reference of the item to search for.
Example calls
var elm = $$("content");
var idx = $("div").indexOf(elm);
map(functionRef)
Runs a function on each item, and returns the results in an array.
Return value
An array of the mapped results.
Parameters
- functionRef
- Mapping function to be applied to each item. This function is invoked with three arguments: the current item, the index of the item, and the element collection being traversed.
Example calls
// Creates an array of element ID
var arrayID = $("div").map( function(elm, idx, set) {
return this.id;
});
filter(functionRef)
Runs a function to filter the element collection, and returns all items where the function returned true.
Return value
The filtered element collection.
Parameters
- functionRef
- Filtering function to be applied to each item. This function is invoked with three arguments: the current item, the index of the item, and the element collection being traversed.
Example calls
var oddItems = $("div").filter( function(elm, idx, set) {
return (idx % 2 === 1);
});
every(functionRef)
Runs a function on each item in the element collection, while it returns true.
Return value
Boolean value, true if all items return true on the function, false otherwise.
Parameters
- functionRef
- Function to be applied to each item. Returns either true or false. This function is invoked with three arguments: the current item, the index of the item, and the element collection being traversed.
Example calls
var allHaveChildren = $("div").every( function(elm, idx, set) {
return (this.childNodes.length > 0);
});
some(functionRef)
Runs a function on each item in the element collection, while it returns false.
Return value
Boolean value, true if some items return true on the function, false otherwise.
Parameters
- functionRef
- Function to be applied to each item. Returns either true or false. This function is invoked with three arguments: the current item, the index of the item, and the element collection being traversed.
Example calls
var someHaveChildren = $("div").some( function(elm, idx, set) {
return (this.childNodes.length > 0);
});
first()
To get a reference to the first match in a collection.
Return value
Returns a reference to the first element match in a collection, with the DOMAssistant methods applied.
Parameters
None.
Example calls
$("#navigation a").first();
end()
To step one step up in the currect chaining context.
Return value
Returns a value to the previous element set in the chain.
Parameters
None.
Example calls
// Returns a reference to the a elements
$("#navigation a").create("span", null, true).end();
store(key, value)
To store arbitrary data to the current element.
Return value
Element which called the method.
Parameters
- key
- Name of the data being stored. Can be a string, and is then used in conjunction with the value, or as an object with several key-value pairs. Required.
- value
- The value of the data being stored, if the key parameter is a string. Optional.
Example calls
$$("elem").store("foo", "bar");
$$("child").store( { "name": "Tom", "age": 6, "sex": "M" } );
retrieve(key)
To retrieve data that has previously been stored to the current element.
Return value
Value of the key if it is specified, otherwise the unique ID of the element.
Parameters
- key
- Name of the data to be retrieved. Optional. If unspecified, the unique ID of the current element is returned.
Example calls
var foo = $$("elem").retrieve("foo"); //bar
var age = $$("child").retrieve("age"); //6
alert("Unique ID is " + $$("child").retrieve());
unstore(key)
To remove data that has previously been stored to the current element.
Return value
Element which called the method.
Parameters
- key
- Name of the data to be removed. Optional. If unspecified, all data associated with the current element is removed.
Example calls
$$("elem").unstore("foo");
$$("child").unstore(); //Removes all data
harmonize()
Allows DOMAssistant to co-exist in harmony with other Javascript libraries, by avoiding global namespace collision of $ and $$. The dollar methods are still accessible via DOMAssistant.$ and DOMAssistant.$$
Return value
None
Parameters
None
Example calls
<script type="text/javascript" src="OtherLib.js"> </script>
<script type="text/javascript" src="DOMAssistantCompressed.js"> </script>
<script type="text/javascript">
DOMAssistant.DOMReady( function() {
// Your DOMAssistant code
} );
DOMAssistant.harmonize();
// Other library's code here
</script>
