Version 1.5 glow.dom.NodeList
API Quick Reference
JavaScript is required to use the quick reference
An array-like collection of DOM Elements.
It is recommended you create a NodeList using glow.dom.get, or glow.dom.create, but you can also use the constructor to create an empty NodeList.
Unless otherwise specified, all methods of NodeList return the NodeList itself, allowing you to chain methods calls together.
Further Info & Examples
Constructor
new glow.dom.NodeList()-
Examples
// empty NodeList var nodes = new glow.dom.NodeList();// using get to return a NodeList then chaining methods glow.dom.get("p").addClass("eg").append("<b>Hello!</b>");
Properties
- length
-
Number of nodes in the NodeList
- Type
Example
// get the number of paragraphs on the page glow.dom.get("p").length;
Methods
- addClass
-
Adds a class to each node.
Synopsis
myNodeList.addClass(name);Parameters
- name
-
- Type
The name of the class to add.
Returns
Description
This method is not applicable to XML NodeLists.
Example
glow.dom.get("#login a").addClass("highlight"); - after
-
Inserts elements after each node.
Synopsis
myNodeList.after(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
HTML string, Element or NodeList to insert after each node
Returns
Description
If there is more than one node in the NodeList, the elements will be inserted after the first node and clones inserted after each subsequent node.
Example
// adds a paragraph after each heading glow.dom.get('h1, h2, h3').after('<p>...</p>'); - append
-
Appends the given elements to each node.
Synopsis
myNodeList.append(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
HTML string, Element or NodeList to append to each node.
Returns
Description
If there is more than one node in the NodeList, then the given elements are appended to the first node and clones are appended to the other nodes.
String nodespecs cannot be used with XML NodeLists
Example
// ends every paragraph with '...' glow.dom.get('p').append( '<span>...</span>' ); - appendTo
-
Appends the NodeList to elements.
Synopsis
myNodeList.appendTo(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
CSS selector string, Element or NodeList to append the NodeList to.
Returns
Description
If more than one element is given (i.e. if the nodespec argument is an array of nodes or a NodeList) the NodeList will be appended to the first element and clones to each subsequent element.
Example
// appends '...' to every paragraph glow.dom.create('<span>...</span>').appendTo('p'); - attr
-
Gets or sets attributes
Synopsis
myNodeList.attr(name, value);Parameters
- name
-
- Type
- |
The name of the attribute, or an object of name/value pairs
- value
-
- Type
- Optional
- Yes
The value to set the attribute to.
Returns
When setting attributes it returns the NodeList, otherwise returns the attribute value.
Description
When getting an attribute, it is retrieved from the first node in the NodeList. Setting attributes applies the change to each element in the NodeList.
To set an attribute, pass in the name as the first parameter and the value as a second parameter.
To set multiple attributes in one call, pass in an object of name/value pairs as a single parameter.
For browsers that don't support manipulating attributes using the DOM, this method will try to do the right thing (i.e. don't expect the semantics of this method to be consistent across browsers as this is not possible with currently supported browsers).
Example
var myNodeList = glow.dom.get("myImgClass"); // get an attribute myNodeList.attr("class") == "myImgClass" // set an attribute myNodeList.attr("class", "anotherImgClass"); // set multiple attributes myNodeList.attr({ src : "a.png", alt : "a PNG" }); - before
-
Inserts elements before each node.
Synopsis
myNodeList.before(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
HTML string, Element or NodeList to insert before each node
Returns
Description
If there is more than one node in the NodeList, the elements will be inserted before the first node and clones inserted before each subsequent node.
Example
// adds a heading before each glow.dom.get('p').before('<h1>Paragraph:</h1>'); - children
-
Gets the child elements of each node as a new NodeList.
Synopsis
myNodeList.children();Returns
Returns a new NodeList containing all the child nodes
Example
// get all list items var items = glow.dom.get("ul, ol").children(); - clone
-
Gets a new NodeList containing a clone of each node.
Synopsis
myNodeList.clone(cloneListeners);Parameters
- cloneListeners
-
- Type
- Default
- false
- Optional
- Yes
Also clone any event listeners assigned using Glow
Returns
Returns a new NodeList containing clones of all the nodes in the NodeList
Example
// get a copy of all heading elements var myClones = glow.dom.get("h1, h2, h3, h4, h5, h6").clone();// get a copy of all anchor elements with var myAnchors = glow.dom.get("a").clone(true); - css
-
Gets a CSS property for the first node or sets a CSS property on all nodes.
Synopsis
myNodeList.css(property, value);Parameters
- property
-
- Type
- |
The CSS property name or array of names
- value
-
- Type
- Optional
- Yes
The value to apply
Returns
Returns the CSS value from the first node, or NodeList when setting values
Description
This method is not applicable to XML NodeLists.
If a single property name is passed, the corresponding value from the first node will be returned.
If a single property name is passed with a value, that value will be set on all nodes on the NodeList.
If an array of properties name is passed with no value, the return value is the sum of those values from the first node in the NodeList. This can be useful for getting the total of left and right padding, for example.
Return values are strings. For instance, "height" will return "25px" for an element 25 pixels high. You may want to use parseInt to convert these values.
Here are the compatible properties you can get, if you use one which isn't on this list the return value may differ between browsers.
- width
- Returns pixel width, eg "25px". Can be used even if width has not been set with CSS.
- height
- Returns pixel height, eg "25px". Can be used even if height has not been set with CSS.
- top, right, bottom, left
- Pixel position relative to positioned parent, or original location if position:relative, eg "10px". These can be used even if position:static.
- padding-top
- Pixel size of top padding, eg "5px"
- padding-right
- Pixel size of right padding, eg "5px"
- padding-bottom
- Pixel size of bottom padding, eg "5px"
- padding-left
- Pixel size of left padding, eg "5px"
- margin-top
- Pixel size of top margin, eg "5px"
- margin-right
- Pixel size of right margin, eg "5px"
- margin-bottom
- Pixel size of bottom margin, eg "5px"
- margin-left
- Pixel size of left margin, eg "5px"
- border-top-width
- Pixel size of top border, eg "5px"
- border-right-width
- Pixel size of right border, eg "5px"
- border-bottom-width
- Pixel size of bottom border, eg "5px"
- border-left-width
- Pixel size of left border, eg "5px"
- border-*-style
- eg "dotted"
- border-*-color
- returns colour in format "rgb(255, 255, 255)", return value also has properties r, g & b to get individual values as integers
- color
- returns colour in format "rgb(255, 255, 255)", return value also has properties r, g & b to get individual values as integers
- list-style-position
- eg "outside"
- list-style-type
- eg "square"
- list-style-image
- Returns full image path, eg "url(http://www.bbc.co.uk/lifestyle/images/bullets/1.gif)" or "none"
- background-image
- Returns full image path, eg "url(http://www.bbc.co.uk/lifestyle/images/bgs/1.gif)" or "none"
- background-attachment
- eg "scroll"
- background-repeat
- eg "repeat-x"
- direction
- eg "ltr"
- font-style
- eg "italic"
- font-variant
- eg "small-caps"
- line-height
- Pixel height, eg "30px". Note, Opera may return value with 2 decimal places, eg "30.00px"
- letter-spacing
- Pixel spacing, eg "10px"
- text-align
- eg "right"
- text-decoration
- eg "underline"
- text-indent
- Pixel indent, eg "10px"
- white-space
- eg "nowrap"
- word-spacing
- Pixel spacing, eg "5px"
- float
- eg "left"
- clear
- eg "right"
- opacity
- Value between 0 & 1. In IE, this value comes from the filter property (/100)
- position
- eg "relative"
- z-index
- eg "32"
- display
- eg "block"
- text-transform
- eg "uppercase"
The following return values that may be usable but have differences in browsers
- font-family
- Some browsers return the font used ("Verdana"), others return the full list found in the declaration ("madeup, verdana, sans-serif")
- font-size
- Returns size as pixels except in IE, which will return the value in the same units it was set in ("0.9em")
- font-weight
- Returns named values in some browsers ("bold"), returns computed weight in others ("700")
Example
// get value from first node glow.dom.get("#myDiv").css("display");// set left padding to 10px on all nodes glow.dom.get("#myDiv").css("padding-left", "10px");// "30px", total of left & right padding glow.dom.get("#myDiv").css(["padding-left", "padding-right"]);// where appropriate, px is assumed when no unit is passed glow.dom.get("#myDiv").css("height", 300); - destroy
-
Removes each node from the DOM
Synopsis
myNodeList.destroy();Returns
An empty NodeList
Description
The node will actually be destroyed to free up memory
Example
// destroy all links in the document glow.dom.get("a").destroy(); - each
-
Calls a function for each node.
Synopsis
myNodeList.each(callback);Parameters
- callback
-
- Type
The function to run for each node.
Returns
Description
The supplied function will be called for each node in the NodeList.
The index of the node will be provided as the first parameter, and 'this' will refer to the node.
Example
var myNodeList = glow.dom.get("a"); myNodeList.each(function(i){ this == myNodeList[i]; }); - empty
-
Removes the contents of all the nodes.
Synopsis
myNodeList.empty();Returns
Example
// remove the contents of all textareas glow.dom.get("textarea").empty(); - eq
-
Compares the NodeList to an element, array of elements or another NodeList
Synopsis
myNodeList.eq(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
The element, array or NodeList the NodeList is being compared to.
Returns
Description
Returns true if the items are the same and are in the same order.
Example
// the following returns true glow.dom.get('#blah').eq( document.getElementById('blah') ); - filter
-
Filter the NodeList using a function
Synopsis
myNodeList.filter(func);Parameters
- func
-
- Type
Function to test each node
Returns
Returns a new NodeList containing the filtered nodes
Description
The supplied function will be called for each node in the NodeList.
The index of the node will be provided as the first parameter, and 'this' will refer to the node.
Return true to keep the node, or false to remove it.
Example
// return images with a width greater than 320 glow.dom.get("img").filter(function (i) { return this.width > 320; }); - get
-
Gets decendents of nodes that match a CSS selector.
Synopsis
myNodeList.get(selector);Parameters
- selector
-
- Type
CSS selector
Returns
Returns a new NodeList containing matched elements
Example
// create a new NodeList var myNodeList = glow.dom.create("<div><a href='s.html'>Link</a></div>"); // get 'a' tags that are decendants of the NodeList nodes myNewNodeList = myNodeList.get("a"); - hasAttr
-
Does the node have a particular attribute?
Synopsis
myNodeList.hasAttr(name);Parameters
- name
-
- Type
The name of the attribute to test for.
Returns
Description
The first node in the NodeList is tested
Example
if ( glow.dom.get("#myImg").hasAttr("alt") ){ // ... } - hasClass
-
Tests if a node has a given class.
Synopsis
myNodeList.hasClass(name);Parameters
- name
-
- Type
The name of the class to test for.
Returns
Description
Will return true if any node in the NodeList has the supplied class
This method is not applicable to XML NodeLists.
Example
if (glow.dom.get("a").hasClass("termsLink")){ // ... } - height
-
Gets the height of the first element in pixels or sets the height of all nodes
Synopsis
myNodeList.height(height);Parameters
- height
-
- Type
- Optional
- Yes
New height in pixels.
Returns
Height of first element in pixels, or NodeList when setting heights.
Description
This method is not applicable to XML NodeLists.
Return value does not include the padding or border of the element in browsers supporting the correct box model.
You can use this to easily get the height of the document or window, see example below.
Example
// get the height of #myDiv glow.dom.get("#myDiv").height();// set the height of list items in #myDiv to 200 pixels glow.dom.get("#myDiv li").height(200);// get the height of the document glow.dom.get(document).height()// get the height of the window glow.dom.get(window).height() - hide
-
Hides all items in the NodeList.
Synopsis
myNodeList.hide();Returns
Example
// Hides all list items within #myDiv glow.dom.get("#myDiv li").hide(); - html
-
Gets the HTML content of the first node, or set the HTML content of all nodes.
Synopsis
myNodeList.html(html);Parameters
- html
-
- Type
- Optional
- Yes
String to set as inner HTML of nodes
Returns
If the html argument is passed, then the NodeList is returned, otherwise the inner HTML of the first node is returned.
Description
This method is not applicable to XML NodeLists.
Example
// get the html in #footer var footerContents = glow.dom.get("#footer").html();// set a new footer glow.dom.get("#footer").html("<strong>Hello World!</strong>"); - insertAfter
-
Insert the NodeList after each of the given elements.
Synopsis
myNodeList.insertAfter(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
CSS selector string, Element or NodeList to insert the NodeList after
Returns
Description
If more than one element is passed in, the NodeList will be inserted after the first element and clones inserted after each subsequent element.
Example
// adds a paragraph after each heading glow.dom.create('<p>HAI!</p>').insertAfter('h1, h2, h3'); - insertBefore
-
Insert the NodeList before each of the given elements.
Synopsis
myNodeList.insertBefore(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
CSS selector string, Element or NodeList to insert the NodeList before
Returns
Description
If more than one element is passed in, the NodeList will be inserted before the first element and clones inserted before each subsequent element.
Example
// adds a heading before each paragraph glow.dom.create('<h1>Paragraph:</h1>').insertBefore('p'); - is
-
Tests if all the nodes match a CSS selector.
Synopsis
myNodeList.is(selector);Parameters
- selector
-
- Type
A CSS selector string
Returns
Description
Jake: I'm deprecating this until we have time to make it faster (probably when we change our CSS selector engine)
Example
var bigHeadings = glow.dom.get("h1, h2, h3"); // true if (bigHeadings.is("h1, h2, h3, h4, h5, h6")) ... // false if (bigHeadings.is("a")) ... - isWithin
-
Tests if all the nodes are decendents of an element.
Synopsis
myNodeList.isWithin(nodespec);Parameters
- nodespec
-
- Type
- | glow.dom.NodeList
The element or NodeList that the NodeList is being tested against.
If nodespec is a NodeList, then the its first node will be used.
Returns
Example
var myNodeList = glow.dom.get("input"); if (myNodeList.isWithin(glow.dom.get("form")) { // do something } - item
-
Returns a node from the NodeList.
Synopsis
myNodeList.item(index);Parameters
- index
-
- Type
The numeric index of the node to return.
Returns
Example
// get the fourth node var node = myNodeList.item(3);// another way to get the fourth node var node = myNodeList[3]; - next
-
Gets the next sibling element for each node as a new NodeList.
Synopsis
myNodeList.next();Returns
A new NodeList containing the next sibling elements.
Example
// gets the element following #myLink (if there is one) var next = glow.dom.get("#myLink").next(); - offset
-
Gets the offset from the top left of the document.
Synopsis
myNodeList.offset();Returns
Returns an object with "top" & "left" properties in pixels
Description
If the NodeList contains multiple items, the offset of the first item is returned.
Example
glow.dom.get("#myDiv").offset().top - parent
-
Gets the unique parent nodes of each node as a new NodeList.
Synopsis
myNodeList.parent();Returns
Returns a new NodeList containing the parent nodes, with duplicates removed
Example
// elements which contain links var parents = glow.dom.get("a").parent(); - prepend
-
Prepends the given elements to each node.
Synopsis
myNodeList.prepend(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
HTML string, Element or NodeList to prepend to each node.
Returns
Description
If there is more than one node in the NodeList, then the given elements are prepended to the first node and clones are prepended to the other nodes.
String nodespecs cannot be used with XML NodeLists
Example
// prepends every paragraph with 'Paragraph: ' glow.dom.get('p').prepend( '<span>Paragraph: </span>' ); - prependTo
-
Prepends the NodeList to elements.
Synopsis
myNodeList.prependTo(nodespec);Parameters
- nodespec
-
- Type
- | | glow.dom.NodeList
CSS selector string, Element or NodeList to prepend the NodeList to.
Returns
Description
If more than one element is given (i.e. if the nodespec argument is an array of nodes or a NodeList) the NodeList will be prepended to the first element and clones to each subsequent element.
Example
// prepends 'Paragraph: ' to every paragraph glow.dom.create('<span>Paragraph: </span>').prependTo('p'); - prev
-
Gets the previous sibling element for each node as a new NodeList.
Synopsis
myNodeList.prev();Returns
A new NodeList containing the previous sibling elements.
Example
// gets the elements before #myLink (if there is one) var previous = glow.dom.get("#myLink").previous(); - push
-
Adds Elements to the NodeList.
Synopsis
myNodeList.push(nodespec+);Parameters
- nodespec+
-
- Type
- | | glow.dom.NodeList
One or more Elements, Arrays of Elements or NodeLists.
Returns
Example
var myNodeList = glow.dom.create("<div>Hello world</div>"); myNodeList.push("<div>Foo</div>", glow.dom.get("#myList li")); - remove
-
Removes each node from its parent node.
Synopsis
myNodeList.remove();Returns
Description
If you no longer need the nodes, consider using destroy
Example
// take all the links out of a document glow.dom.get("a").remove(); - removeAttr
-
Removes an attribute from each node.
Synopsis
myNodeList.removeAttr(name);Parameters
- name
-
- Type
The name of the attribute to remove.
Returns
Example
glow.dom.get("a").removeAttr("target"); - removeClass
-
Removes a class from each node.
Synopsis
myNodeList.removeClass(name);Parameters
- name
-
- Type
The name of the class to remove.
Returns
Description
This method is not applicable to XML NodeLists.
Example
glow.dom.get("#footer #login a").removeClass("highlight"); - replaceWith
-
Replace nodes on the page with given elements.
Synopsis
myNodeList.replaceWith(nodespec);Parameters
- nodespec
-
- Type
- glow.dom.NodeList |
Elements to insert into the document.
If more than one node is to be replaced then nodespec will be cloned for additional elements. If a string is provided it will be treated as HTML and converted into elements.
Returns
Returns a new NodeList containing the nodes which have been removed
- show
-
Shows all hidden items in the NodeList.
Synopsis
myNodeList.show();Returns
Example
// Show element with ID myDiv glow.dom.get("#myDiv").show();// Show all list items within #myDiv glow.dom.get("#myDiv li").show(); - slice
-
Extracts nodes from a NodeList and returns them as a new NodeList.
Synopsis
myNodeList.slice(start, end);Parameters
- start
-
- Type
The NodeList index at which to begin extraction.
If negative, this param specifies a position measured from the end of the NodeList
- end
-
- Type
- Optional
- Yes
The NodeList index immediately after the end of the extraction.
If not specified the extraction includes all nodes from the start to the end of the NodeList. A Negative end specifies an position measured from the end of the NodeList.
Returns
Returns a new NodeList containing the extracted nodes
Example
var myNodeList = glow.dom.create("<div></div><div></div>"); myNodeList = myNodeList.slice(1, 2); // just second div - sort
-
Returns a new NodeList containing the same nodes in order.
Synopsis
myNodeList.sort(func);Parameters
- func
-
- Type
- Optional
- Yes
Function to determine sort order
This function will be passed 2 nodes (a, b). The function should return a number less than 0 to sort a lower than b and greater than 0 to sort a higher than b.
Returns
Returns a new NodeList containing the sorted nodes
Description
Sort order defaults to document order if no sort function is passed in.
Example
// heading elements in document order var headings = glow.dom.get("h1, h2, h3, h4, h5, h6").sort(); //get links in alphabetical (well, lexicographical) order var links = glow.dom.get("a").sort(function(a, b) { return ((a.textContent || a.innerText) < (b.textContent || b.innerText)) ? -1 : 1; }) - text
-
Gets the inner text of the first node, or set the inner text of all matched nodes.
Synopsis
myNodeList.text(text);Parameters
- text
-
- Type
- Optional
- Yes
String to set as inner text of nodes
Returns
If the text argument is passed then the NodeList is returned, otherwise the text is returned.
Example
// set text var div = glow.dom.create("<div></div>").text("Hello World!"); // get text var greeting = div.text(); - toggleClass
-
Toggles a class on each node.
Synopsis
myNodeList.toggleClass(name);Parameters
- name
-
- Type
The name of the class to toggle.
Returns
Description
This method is not applicable to XML NodeLists.
Example
glow.dom.get(".onOffSwitch").toggleClass("on"); - val
-
Gets or sets form values for the first node.
Synopsis
myNodeList.val(value);Parameters
- value
-
- Type
- |
- Optional
- Yes
The value to set the form element/elements to.
Returns
When used to set a value it returns the NodeList, otherwise returns the value as described above.
Description
This method is not applicable to XML NodeLists.
Getting values from form elements
The returned value depends on the type of element, see below:
- Radio button or checkbox
- If checked, then the contents of the value attribute, otherwise an empty string.
- Select
- The contents of value attribute of the selected option
- Select (multiple)
- An array of selected option values.
- Other form element
- The value of the input.
Getting values from a form
If the first element in the NodeList is a form, then an object is returned containing the form data. Each item property of the object is a value as above, apart from when multiple elements of the same name exist, in which case the it will contain an array of values.
Setting values for form elements
If a value is passed and the first element of the NodeList is a form element, then the form element is given that value. For select elements, this means that the first option that matches the value will be selected. For selects that allow multiple selection, the options which have a value that exists in the array of values/match the value will be selected and others will be deselected.
Currently checkboxes and radio buttons are not checked or unchecked, just their value is changed. This does mean that this does not do exactly the reverse of getting the value from the element (see above) and as such may be subject to change
Setting values for forms
If the first element in the NodeList is a form and the value is an object, then each element of the form has its value set to the corresponding property of the object, using the method described above.
Example
// get a value var username = glow.dom.get("input#username").val();// get values from a form var userDetails = glow.dom.get("form").val();// set a value glow.dom.get("input#username").val("example username");// set values in a form glow.dom.get("form").val({ username : "another", name : "A N Other" }); - width
-
Gets the width of the first node in pixels or sets the width of all nodes
Synopsis
myNodeList.width(width);Parameters
- width
-
- Type
- Optional
- Yes
New width in pixels.
Returns
Width of first element in pixels, or NodeList when setting widths
Description
This method is not applicable to XML NodeLists.
Return value does not include the padding or border of the element in browsers supporting the correct box model.
You can use this to easily get the width of the document or window, see example below.
Example
// get the width of #myDiv glow.dom.get("#myDiv").width();// set the width of list items in #myDiv to 200 pixels glow.dom.get("#myDiv li").width(200);// get the height of the document glow.dom.get(document).width()// get the height of the window glow.dom.get(window).width()
