Introduction
The DOM object parses HTML into a mutable document tree. It can be used to inspect elements, find elements by ID, tag name or class name, change the resulting maps and lists, and convert the document back into HTML.
The DOM object was introduced in ZPE 1.14.9. It uses ZPE's native HTML parser and does not require permission to parse or inspect HTML.
A document can be supplied to the constructor or parsed using the static
DOM::parse function. Malformed HTML causes a runtime exception
containing the parser error and line number.
Document structure
A DOM document is represented by a list. Each element in the list is either a text string or an ordered map with the following entries:
-
name⇒ string -
The name of the element, such as
porsection. -
attributes⇒ ordered map - A map containing the element's attribute names and values.
-
children⇒ list - A list containing child elements and text strings.
The maps and lists returned by DOM functions belong to the live document. Changes made to them are included when the document is converted back into HTML.
DOM object functions
The following is a list of the native functions exposed by the DOM object. All functions require permission level 0.
-
DOM(string html) ⇒ DOM - Creates a DOM object by parsing html.
-
DOM::parse(string html) ⇒ DOM - Parses html and returns a new DOM object. This is a static function and can be called without first creating a DOM object.
-
document() ⇒ list - Returns the document's root list. Changes made to this list or its element maps modify the DOM.
-
to_html() ⇒ string - Serialises the current document tree and returns it as HTML.
-
text() ⇒ string - Returns the combined text content of the document and all its descendants. HTML tags are omitted.
-
get_element_by_id(string id) ⇒ ordered map | undefined -
Returns the first element whose
idattribute exactly matches id. Returns undefined when no matching element exists. -
get_elements_by_tag_name(string tag) ⇒ list - Returns every element with the specified tag name. Tag-name matching is case-insensitive.
-
get_elements_by_class_name(string class_name) ⇒ list -
Returns every element containing class_name in its space-separated
classattribute. The class name must match exactly.
Examples
Parsing and querying some HTML:
$html = "<main><h1 id='title'>Hello</h1><p class='note'>Welcome</p></main>" $dom = new DOM($html) $heading = $dom->get_element_by_id("title") print($heading["children"][0]) print($dom->text())
Editing the document and converting it back into HTML:
$dom = DOM::parse("<p id='message'>Old text</p>") $message = $dom->get_element_by_id("message") $message["attributes"]["class"] = "updated" $message["children"] = ["New text"] print($dom->to_html())
Finding all elements with a class name:
$dom = new DOM("<p class='item active'>One</p><p class='item'>Two</p>") $items = $dom->get_elements_by_class_name("item") for each ($items as $item) print($item["children"][0]) end
Notes:
- Live values: Query functions return the actual element maps, rather than copies.
-
Text nodes: Text inside an element is stored as a string in
its
childrenlist. - Serialisation: Printing or beautifying a DOM object uses its current HTML representation.
-
Declarations: HTML declarations such as
<!DOCTYPE html>are ignored by the parser.
There are no comments on this page.
Comments are welcome and encouraged, including disagreement and critique. However, this is not a space for abuse. Disagreement is welcome; personal attacks, harassment, or hate will be removed instantly. This site reflects personal opinions, not universal truths. If you can’t distinguish between the two, this probably isn’t the place for you. The system temporarily stores IP addresses and browser user agents for the purposes of spam prevention, moderation, and safeguarding. This data is automatically removed after fourteen days. Your email address is stored so that replies can be sent to your email address.
Comments powered by BalfComment