SpryDOMUtils.js contains utility functions that make common DOM manipulation tasks a bit easier.
Nicknamed the "Element Selector", this utility function returns an array of elements within the document that match the specified CSS selector.
Spry.$$(cssSelectorString)
cssSelectorString - String. A CSS selector sequence or comma separated set of selector sequences to use to find elements within the document. For the list of supported CSS 3 selectors, checkout the Element Selector Overview.
Array. An array containing the elements matched with the specified CSS selector. The array returned is augmented with additional utility functions that operate on all elements within the array. Each of these utility functions returns the array itself, which makes it possible to chain successive function calls with dot notation. The list of functions are as follows:
// Add a class to every span.
var spans = Spry.$$("span");
spans.addClassName("foo");
// Since the functions added to the array returned by $$ also return the
// array itself, it is possible to chain the functions together with dot notation.
Spry.$$("div").addClassName("address").addEventListener("click", function(){ alert("clicked!"); }, false);
Adds a class name to the class attribute of the elements returned by the $$() function.
Opposite of removeClassName.
Spry.$$(cssSelector).addClassName(className);
className - String. The name of the class to add to the class attribute of every element returned by the $$() function.
Array. Returns the array it operated on.
// Find all spans and add the class "foo" to each one.
Spry.$$("span").addClassName("foo");
Registers a handler/callback for a specific event on all elements returned by the $$() function.
Opposite of removeEventListener.
Spry.$$(cssSelector).addEventListener(eventType, handler, capture);
eventType - String. The name of the event that will trigger the specified handler/callback.
handler - Function. The handler to call when the specified event is triggered. When called, the browser's native event object is passed as the 1st argument to the handler. When called, the 'this' reference within the handler will be the element the handler was registered on. The handler can return a value of false to prevent the event from propagating any further and to prevent the default event action from executing.
capture - Boolean. If true, the handler is triggered during the "capture" phase of the event processing. If false, the handler is triggered during the propagation (bubble up) phase of event processing.
Array. Returns the array it operated on.
// Define a handler function.
function MyOnClickHandler(e)
{
alert("Link was clicked!");
return false;
}
// Add a click listener on all links on the page.
Spry.$$("a").addEventListener("click", MyOnClickHandler, false);
Calls the specified function for each element returned from the $$() function.
Spry.$$(cssSelector).forEach(elementFunc)
elementFunc - Function. A reference to a function that will be invoked for each element in the array returned by the $$() function. When invoked, an element from the array returned by $$() will be passed as the first argument to the function.
Array. Returns the array it operated on.
// Find all elements with a class of "Accordion" and invoke the Accordion widget
// constructor for each match.
Spry.$$(".Accordion").forEach(function(n) { var a = new Spry.Widget.Accordion(n); });
Removes the specified attribute from all elements returned by the $$() function.
Opposite of setAttribute.
Spry.$$(cssSelector).removeAttribute(attributeName)
attributeName - String. The name of the attribute to remove from each element.
Array. Returns the array it operated on.
// Remove the border attribute from all table tags.
Spry.$$("table").removeAttribute("border");
Removes a handler/callback function, that was previously registered with addEventListener(), for a specific event from all elements returned by the $$() function.
Opposite of addEventListener.
Spry.$$(cssSelector).removeEventListener(eventType, handler, capture)
eventType - String. The name of the event that triggers the specified handler/callback.
handler - Function. The handler/callback function to remove. This function must be the *exact* same function that was used when addEventListener() was called to register the handler with the element.
capture - Boolean. If true, the handler was to be triggered during the "capture" phase of event processing. If false, the handler was to be triggered during the propagation (bubble up) phase of event processing. The value here must match the value that was used at the time addEventListener() was called.
Array. Returns the array it operated on.
function MyClickHandler(e)
{
alert("MyClickHandler was called!");
}
// Register the MyClickHandler as an event listener on all divs.
Spry.$$("div").addEventListener("click", MyClickHandler, "false");
...
// INCORRECT: The following example specifies a different event so
// nothing is removed.
Spry.$$("div").removeEventListener("mouseover", MyClickHandler, "false");
// INCORRECT: The following example specifies a different capture value
// so nothing is removed.
Spry.$$("div").removeEventListener("click", MyClickHandler, "true");
// CORRECT: The following example specifies the exact same set of arguments
// that were used when addEventListener() was called so the MyClickHandler
// is removed from the listener queue of each element.
Spry.$$("div").removeEventListener("click", MyClickHandler, "false");
Removes the specified class name from the class attribute of all the elements returned from the $$() function. If the class attribute of a given element contains more than one class name, this function will only remove the specified class name, leaving all other class names in tact. If you want to remove *all* classes from and element, use removeAttribute("class") instead.
Opposite of addClassName.
Spry.$$(cssSelector).removeClassName(className)
className - String. The name of the class to remove from the class attribute of each element.
Array. Returns the array it operated on.
// Look for all elements that have a class name of "foo" and "bar" on them
// and remove only the "foo" class name from each element.
Spry.$$(".foo.bar").removeClassName("foo");
Sets the specified attribute and value on each element returned from the $$() function. If a given element already has the specified attribute defined, this function will override its value with the specified value.
To remove an attribute from each element, use the removeAttribute() function.
Special Note:
The underlying implementation of setAttribute() uses the DOM setAttribute() method on each element. In Safari 2.x browsers, calling this function with an attribute that is namespaced results in an attribute being added to the element *without* the prefix. So for example, if you called setAttribute("spry:region", "ds1"), Safari 2.x browsers treat it as if you called setAttribute("region", "ds1"). This behavior is different from all other browsers, and seems to have been fixed in the latest Safari 3.0 beta.
Spry.$$(cssSelector).setAttribute(name, value)
name - String. The name of the attribute to set on each element.
value - String. The value of the attribute to set on each element.
Array. Returns the array it operated on.
// Find the element that has an id of "mainImage" and add a tabindex attribute to it.
Spry.$$("#mainImage").setAttribute("tabindex", "0");
// WARNING: The following attempts to set a namespaced attribute on an element
// this will not work on Safari 2.x browsers.
Spry.$$("#content").setAttribute("spry:region", "ds1");
Sets the specified property and value on the elements returned by the $$() function. It's important to note that properties are *NOT* the same as attributes on a given element.
Spry.$$(cssSelector).setProperty(name, value)
name - String. The name of the property to set on each element.
value - String. The value of the property to set on each element.
Array. Returns the array it operated on.
// The following example creates a tooltip widget and then uses the element
// selector and setProperty() functions to store a handle to the widget object
// on each element that has a class of 'tooltipTrigger'.
var tt = new Spry.Widget.Tooltip("foo");
Spry.$$.("[class='tooltipTrigger']").setProperty("spryToolTip", tt);
Adds the specified CSS properties and values to all of the elements returned by the $$() function.
Spry.$$(cssSelector).setStyle(cssProperties)
cssProperties - String. The CSS properties and values to set on each element. The format of this string is identical to the format that is used by the style attribute.
Array. Returns the array it operated on.
// Change the background color, top and left margin to all divs with a class of "indented".
Spry.$$("div.indented").setStyle("margin-left: 8em; margin-top: 2em; background-color: #FF00FF;")
Adds the specified class name to the class attribute of all the elements returned by the $$() function if the class attribute does not already contain it. Removes the class name from a given element if it was already present.
Spry.$$(cssSelector).toggleClassName(className)
className - String. The name of the class to add or remove from the class attribute of each element.
Array. Returns the array it operated on.
// The following example illustrates a scenario where a class name of "selected"
// is added to elements on the page to give it the appearance of being selected.
// The following code simulates a situation where the developer wants to invert
// what is selected, that is, anything that is already selected on screen becomes
// unselected, and anything that was not previously selected becomes selected.
Spry.$$("div.item").toggleClassName("selected");
Copyright © 2007. Adobe Systems Incorporated.
All rights reserved.