DOM:document.getElementsByName

From MDC

« Gecko DOM Reference

Contents 1 Summary 2 Syntax 3 Example 4 Notes 5 Name attribute availability 6 Specification

[edit] Summary

Returns a list of elements with a given name in the (X)HTML document.

[edit] Syntax

elements = document.getElementsByName(name) 

• elements is a NodeList of elements.
• name is the value of the name attribute of the element.

[edit] Example

// return some of the forms 
//<form name="up"><input type="text"/></form> 
//<form name="up"><input type="text"/></form> 
//<form name="down"><input type="text"/></div> 
//<form name="down"><input type="text"/></div> 
up_forms = document.getElementsByName("up"); 
dump(up_forms.item(0).tagName); // returns "div"

[edit] Notes

The name attribute is only applicable to (X)HTML documents.

Although the standard behavior is supposed to only return name attributes in XHTML for form controls, this behavior is not implemented per bug 242808. (In XHTML, the method returns all elements with a name attribute, such as <meta> or <object> or even if 'name' is placed on elements which do not support a name attribute at all. This is standard behavior for HTML, but not for XHTML.)

document.getElementsByName returns a NodeList of all the elements with a given value for the name attribute. Unlike getElementsByTagName, which uses the name of the tag itself, this method applies only to elements that have been given a value for their name attribute.

[edit] Name attribute availability

The name attribute has gone through a period of changes.

As of XHTML 1.0:

• the use of the name attribute was deprecated on <a>, <applet>, <form>, <frame>, <iframe>, <img>, and <map>[1]
• the <applet> tag itself was itself deprecated

In XHTML 1.0 Transitional:

• <frame> was dropped

In XHTML 1.0 Strict:

• 'name' was dropped from <img> and <form>
• <iframe> itself was dropped

As of XHTML 1.1:

• the name attribute was dropped entirely for <a> and <map> (though it can be included with the deprecated Name Identification module), leaving name only on the following elements for which they have always been allowed:

<meta>, <object>, <param> (required), <input> ('name' required for all types besides submit and reset types), <select>, <textarea>, <button>

This method might be questionable for use given the above changes between document types and the current non-standard behavior for this method in XHTML.

[edit] Specification

DOM Level 2 HTML: getElementsByName