Skip to content

Latest commit

 

History

History
352 lines (205 loc) · 15.9 KB

DOM.md

File metadata and controls

352 lines (205 loc) · 15.9 KB

DOM

The DOM class, when instantiated, parses the HTML that is passed as the first argument, with the newly constructed instance acting as the document's root node. The DOM class extends Node, providing document instances with the full suite of Node methods and properties with a couple overrides. The properties and methods described below are only those that are unique to the DOM class or have been overridden from the implementation of the same name in the Node class.

Table of Contents

Construction

new DOM( htmlContent[, options] )

Parameters

  • htmlContent String

    The HTML to parse into an editable DOM object.

  • options Object (optional)

    An object with some or all of the following properties:

    • allowCustomRootElement Boolean (default: false)

      Whether to allow the document type Node to specify the tag name of the root Node. In HTML documents, the root Node is always an <html> element, but in XML documents, the <!DOCTYPE> node's name is used to specify which element is the root.

      For example, <!DOCTYPE doc> indicates the root node to be the <doc> element. However, for that to work, the <doc> element has to be the top most Node in the document's hierarchy.

    • allowSelfClosingSyntax Boolean (default: false)

      Whether to allow tags to be self-closing (ie. have a forward-slash "/" at the very end of the open tag instead of having a closing tag, like <div />). Useful for parsing XML.

    • allowCDATA Boolean (default: false)

      Whether to parse XML CDATA tags (like <![CDATA[ data ]]>). When this is false, any CDATA tags that are encountered will be parsed as comments.

    • allowProcessingInstructions Boolean (default: false)

      Whether to parse processing instructions (like <?instruction data?>). When this is false, any processing instructions that are encountered will be parsed as comments.

    • decodeEntities Boolean (default: false)

      Whether to decode HTML entities (eg. turning &amp; into &) while parsing HTML.

    • encodeEntities Boolean or RegExp (default: false)

      If specified as a Boolean, whether to encode HTML entities (eg. turning & into &amp;) when serializing nodes as text.

      If specified as a RegExp, the regular expression will be used to determine which characters (or sequences of characters) should be encoded as entities. The entities have to exist in this document's entityEncoder, or the match made by the RegExp will be ignored.

    • entities Entities (default: undefined)

      If specified, this will be the set of entities used during entity encoding and decoding. Leaving this undefined, or setting it to a falsy value, results in the set of default entities being used instead. The default set of entities can be changed by assigning a set of entities to EntityEncoder.defaultEntities.

    • collapseWhitespace Boolean (default: false)

      Whether to collapse multiple consecutive whitespace characters in text nodes into a single space character, mimicking how browsers render consecutive whitespace characters. This option is ignored if trimWhitespace is true.

    • trimWhitespace Boolean (default: false)

      Whether to remove whitespace characters from both ends of text nodes, which is useful for minifying HTML documents. When this option is true, the collapseWhitespace option is ignored.

    • lowerAttributeCase Boolean (default: false)

      Whether to convert attribute names on tags to lower case. When this is false, attribute selectors will be case sensitive (ie. the selector [CaSe] will match the element <div CaSe></div>, but the selector [case] will not). This is false by default for performance reasons, but should be true if you want standards-compliant behaviour.

Properties

Non-standard

  • entityEncoder EntityEncoder (read-only)

    The EntityEncoder instance used by this DOM instance for entity encoding and decoding. Changing the entities of this EntityEncoder will only affect this document.

  • innerHTML String (override)

    Gets or sets the HTML markup of the entire document, including any <!DOCTYPE> node that may be present. When setting this with markup that either doesn't specify a <!DOCTYPE> or doesn't have an <html> element as the root node, the document's nodeType property will be DOCUMENT_FRAGMENT_NODE instead of DOCUMENT_NODE. When specifying a <!DOCTYPE>, the node that is named in the document type tag will be expected as the document's root instead of <html>.

  • outerHTML Null (override)

    This simply overrides Node.outerHTML, making it do nothing on DOM instances.

Semi-standard

  • doctype Node, Object, or Null — [standard] [MDN]

    Gets the document type node associated with the document if one is present, or null otherwise. Unlike the standard, you may set this property using a document type node (such as from DOM.createDocumentType()), or an Object with name (required), publicId (optional), and systemId (optional) properties as strings. You may also set this to null to remove an existing document type from a document.

    When set to an Object, if the object either doesn't have a name property, or the property's value isn't a string, the document type's name, publicId, and systemId properties will be set to empty strings.

  • documentElement Node (read-only) — [standard] [MDN]

    Gets the document's root Node, or null if there is no root Node (such as when the DOM instance represents a document fragment).

Standard

  • body Node — [standard] [MDN]

    Gets the document's <body> element, or null if one doesn't exist. When setting, if the node's tag name is either "BODY" or "FRAMESET", this will add the Node to the document's root node if the document doesn't already have a body element, or the existing body element will be replaced by the Node.

  • head Node (read-only) — [standard] [MDN]

    Gets the document's <head> element, or null if one doesn't exist.

  • title String — [standard] [MDN]

    Gets or sets the value of the document's <title> element if the document has a <head> element, creating the <title> element (when setting) if it doesn't exist.

Methods

document.createCDATASection( data )

[standard] [MDN]

Creates a new Node of type CDATA_SECTION_NODE.

Parameters

  • data String

    A String that is used as the contents of the CDATA section (eg. " data " in <![CDATA[ data ]]>).

Return Value

The new Node.

Exceptions

An Error is thrown if data contains the end sequence ]]>.

document.createComment( data )

[standard] [MDN]

Creates a new Node of type COMMENT_NODE.

Parameters

  • data String

    A String that is used as the contents of the comment.

    ⚠️ Caution: No check is performed for the sequence -->, which can result in the early termination of the comment when the document is output as text, making the remaining contents of the comment appear as text in the document.

Return Value

The new Node.

document.createDocumentType( name[, publicId[, systemId]] )

[standard] [MDN]

Creates a new Node of type DOCUMENT_TYPE_NODE.

Parameters

  • name String

    A String that is used as the document type's name (eg. "html" in <!DOCTYPE html>).

  • publicId String (optional)

    A String that is used as the document type's public identifier. If this isn't a non-empty string, an empty string will be used instead.

  • systemId String (optional)

    A String that is used as the document type's system identifier. If this isn't a non-empty string, an empty string will be used instead.

Return Value

The new Node.

document.createElement( tagName )

[standard] [MDN]

Creates a new Node of type ELEMENT_NODE.

Parameters

  • tagName String

    A String that specifies the tagName of the element (eg. <name></name>)

Return Value

The new Node, or undefined if the specified tagName parameter isn't a String or is an empty string.

document.createProcessingInstruction( target, data )

[standard] [MDN]

Creates a new Node of type PROCESSING_INSTRUCTION_NODE.

Parameters

  • target String

    A String representing the target of the processing instruction (eg. "target" in <?target?>).

  • data String

    A String containing the data of the processing instruction (eg. "data" in <?target data?>). This string can be anything, except the sequence ?> which indicates the end of the processing instruction node.

Return Value

The new Node.

Exceptions

An Error is thrown if either of the following is true:

  • target is invalid — it must be a String that is a valid XML name.
  • data contains the end sequence ?>.

document.createTextNode( text )

[standard] [MDN]

Creates a new Node of type TEXT_NODE.

Parameters

  • text String

    A String that is used as the contents of the new text node.

Return Value

The new Node.

document.getElementsByName( name )

[standard] [MDN]

Gets all elements (ELEMENT_NODE type nodes) which have a name attribute that matches the specified name parameter string.

Parameters

  • name String

    The name attribute of the elements to locate. The comparison is case sensitive.

Return Value

An Array of all elements in the document whose name attribute matches the specified name. The array can be empty if no elements matched.

Node.js Only (Non-standard)

The below convenience methods read and parse the file "lib/entities.json" (which includes all standard HTML 5 entities) and are only available when using FauxDOM in Node.js.

ℹ️ Note: As the standard set of entities is extremely comprehensive, using the standard set can lead to potentially undesirable output, such as encoding new-line characters (which would normally be ignored by browsers) as &NewLine;. This sort of unintended encoding of entities can lead to rather broken looking documents.

To avoid this, either create your document using the encodeEntities option as a RegExp that matches only the entities you care about, or use a custom set of entities that only defines the entities you care about.

document.importStandardEntities()

Sets the entities of this document's entityEncoder to the standard set of HTML 5 entities.

DOM.importStandardEntities()

The static version of the above method. Sets EntityEncoder.defaultEntities to the standard set of HTML 5 entities.