diff --git a/files/en-us/web/api/document/all/index.md b/files/en-us/web/api/document/all/index.md index 6185f53543bd00e..37b5fd1958ba46e 100644 --- a/files/en-us/web/api/document/all/index.md +++ b/files/en-us/web/api/document/all/index.md @@ -10,10 +10,7 @@ browser-compat: api.Document.all {{APIRef("DOM")}}{{Deprecated_Header}} -The {{DOMxRef("Document")}} interface's read-only **`all`** -property returns an {{DOMxRef("HTMLAllCollection")}} rooted at the document node. In -other words, it returns all of the document's elements, accessible by order (like an -array) and by ID (like a regular object). +The {{DOMxRef("Document")}} interface's read-only **`all`** property returns an {{DOMxRef("HTMLAllCollection")}} rooted at the document node. Rather than using `document.all` to return an {{DOMxRef("HTMLAllCollection")}} of all the document's elements in document order, you can use {{DOMxRef("Document.querySelectorAll")}} to return a {{DOMxRef("NodeList")}} of all the document's elements in document order: @@ -25,30 +22,6 @@ const allElements = document.querySelectorAll("*"); An {{DOMxRef("HTMLAllCollection")}} which contains every element in the document. -## Special type conversion behavior - -For historical reasons, `document.all` is an object that in many ways behaves like `undefined`. Specifically: - -- It is [loosely equal](/en-US/docs/Web/JavaScript/Reference/Operators/Equality) to `undefined` and `null`. -- It is [falsy](/en-US/docs/Glossary/Falsy) in boolean contexts. -- Its [`typeof`](/en-US/docs/Web/JavaScript/Reference/Operators/typeof) is `"undefined"`. - -These special behaviors ensure that code like: - -```js -if (document.all) { - // Assume that we are in IE; provide special logic -} -// Assume that we are in a modern browser -``` - -Will continue to provide modern behavior even if the code is run in a browser that implements `document.all` for compatibility reasons. - -However, in all other contexts, `document.all` remains an object. For example: - -- It is not [strictly equal](/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) to either `undefined` or `null`. -- When used on the left-hand side of the [nullish coalescing operator](/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) (`??`) or the [optional chaining operator](/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) (`?.`), it will not cause the expression to short-circuit. - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/htmlallcollection/index.md b/files/en-us/web/api/htmlallcollection/index.md new file mode 100644 index 000000000000000..885bbef7046c9ac --- /dev/null +++ b/files/en-us/web/api/htmlallcollection/index.md @@ -0,0 +1,70 @@ +--- +title: HTMLAllCollection +slug: Web/API/HTMLAllCollection +page-type: web-api-interface +browser-compat: api.HTMLAllCollection +--- + +{{APIRef("DOM")}}{{Deprecated_Header}} + +The **`HTMLAllCollection`** interface represents a collection of _all_ of the document's elements, accessible by index (like an array) and by the element's [`id`](/en-US/docs/Web/HTML/Global_attributes/id). It is returned by the {{domxref("document.all")}} property. + +`HTMLAllCollection` has a very similar shape to {{domxref("HTMLCollection")}}, but there are many subtle behavior differences — for example, `HTMLAllCollection` can be called as a function, and its `item()` method can be called with a string representing an element's `id` or `name` attribute. + +## Instance properties + +- {{domxref("HTMLAllCollection.length")}} {{ReadOnlyInline}} + - : Returns the number of items in the collection. + +## Instance methods + +- {{domxref("HTMLAllCollection.item()")}} + - : Returns the element located at the specified offset into the collection, or the element with the specified value for its `id` or `name` attribute. Returns `null` if no element is found. +- {{domxref("HTMLAllCollection.namedItem()")}} + - : Returns the first [element](/en-US/docs/Web/API/Element) in the collection whose [`id`](/en-US/docs/Web/HTML/Global_attributes/id) or `name` attribute match the given string name, or `null` if no element matches. + +## Usage in JavaScript + +### Indexed access + +In addition to the methods above, elements in an `HTMLAllCollection` can be accessed by integer indices and string property names. The HTML `id` attribute may contain `:` and `.` as valid characters, which would necessitate using bracket notation for property access. `collection[i]` is equivalent to `collection.item(i)`, where `i` can be an integer, a string containing an integer, or a string representing an `id`. + +### Calling as a function + +An `HTMLAllCollection` object is callable. When it's called with no arguments or with `undefined`, it returns `null`. Otherwise, it returns the same value as the {{domxref("HTMLAllCollection/item", "item()")}} method when given the same arguments. + +### Special type conversion behavior + +For historical reasons, `document.all` is an object that in the following ways behaves like `undefined`: + +- It is [loosely equal](/en-US/docs/Web/JavaScript/Reference/Operators/Equality) to `undefined` and `null`. +- It is [falsy](/en-US/docs/Glossary/Falsy) in boolean contexts. +- Its [`typeof`](/en-US/docs/Web/JavaScript/Reference/Operators/typeof) is `"undefined"`. + +These special behaviors ensure that code like: + +```js +if (document.all) { + // Assume that we are in IE; provide special logic +} +// Assume that we are in a modern browser +``` + +Will continue to provide modern behavior even if the code is run in a browser that implements `document.all` for compatibility reasons. + +However, in all other contexts, `document.all` remains an object. For example: + +- It is not [strictly equal](/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) to either `undefined` or `null`. +- When used on the left-hand side of the [nullish coalescing operator](/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) (`??`) or the [optional chaining operator](/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) (`?.`), it will not cause the expression to short-circuit. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLCollection")}} diff --git a/files/en-us/web/api/htmlallcollection/item/index.md b/files/en-us/web/api/htmlallcollection/item/index.md new file mode 100644 index 000000000000000..df5d9e6ac4baceb --- /dev/null +++ b/files/en-us/web/api/htmlallcollection/item/index.md @@ -0,0 +1,34 @@ +--- +title: "HTMLAllCollection: item() method" +short-title: item() +slug: Web/API/HTMLAllCollection/item +page-type: web-api-instance-method +browser-compat: api.HTMLAllCollection.item +--- + +{{APIRef("HTML DOM")}} + +The **`item()`** method of the {{domxref("HTMLAllCollection")}} interface returns the element located at the specified offset into the collection, or the element with the specified value for its `id` or `name` attribute. + +## Syntax + +```js-nolint +item(nameOrIndex) +``` + +### Parameters + +- `nameOrIndex` + - : If this parameter is an integer, or a string that can be converted to an integer, then it represents the position of the {{domxref("Element")}} to be returned. Elements appear in an `HTMLAllCollection` in the same order in which they appear in the document's source. If the parameter is a string can't be converted to an integer, it will be interpreted as the `name` or `id` of the element to be returned. + +### Return value + +If `nameOrIndex` represents an index, `item()` returns the {{domxref("Element")}} at the specified index, or `null` if `nameOrIndex` is less than zero or greater than or equal to the length property. If `nameOrIndex` represents a name, `item()` returns the same value as {{domxref("HTMLAllCollection/namedItem", "namedItem()")}}. + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLCollection.item()")}} diff --git a/files/en-us/web/api/htmlallcollection/length/index.md b/files/en-us/web/api/htmlallcollection/length/index.md new file mode 100644 index 000000000000000..f95a639ff69103b --- /dev/null +++ b/files/en-us/web/api/htmlallcollection/length/index.md @@ -0,0 +1,27 @@ +--- +title: "HTMLAllCollection: length property" +short-title: length +slug: Web/API/HTMLAllCollection/length +page-type: web-api-instance-property +browser-compat: api.HTMLAllCollection.length +--- + +{{APIRef("DOM")}} + +The **`HTMLAllCollection.length`** property returns the number of items in this {{domxref("HTMLAllCollection")}}. + +## Value + +An integer value representing the number of items in this `HTMLAllCollection`. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLCollection.length")}} diff --git a/files/en-us/web/api/htmlallcollection/nameditem/index.md b/files/en-us/web/api/htmlallcollection/nameditem/index.md new file mode 100644 index 000000000000000..d812baba77d8b77 --- /dev/null +++ b/files/en-us/web/api/htmlallcollection/nameditem/index.md @@ -0,0 +1,38 @@ +--- +title: "HTMLAllCollection: namedItem() method" +short-title: namedItem() +slug: Web/API/HTMLAllCollection/namedItem +page-type: web-api-instance-method +browser-compat: api.HTMLAllCollection.namedItem +--- + +{{APIRef("DOM")}} + +The **`namedItem()`** method of the {{domxref("HTMLAllCollection")}} interface returns the first {{domxref("Element")}} in the collection whose `id` or `name` attribute matches the specified name, or `null` if no element matches. + +## Syntax + +```js-nolint +namedItem(name) +``` + +### Parameters + +- `name` + - : A string representing the value of the `id` or `name` attribute of the element we are looking for. + +### Return value + +The first {{domxref("Element")}} in the {{domxref("HTMLAllCollection")}} matching the `name`, or [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null), if there are none. + +## Specification + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLAllCollection.namedItem()")}}