Dodo
DOm DOcument implementation
|
Public Member Functions | |
__construct (Document $nodeDocument) | |
Create a Node whose node document is the given $nodeDocument. | |
int | getNodeType () |
Return the node type enumeration for this node. | |
string | getNodeName () |
Return the nodeName for this node. | |
string | getNodeValue () |
Return the value for this node. | |
setNodeValue (?string $val) | |
string | getTextContent () |
Return the textContent for this node. | |
setTextContent (?string $val) | |
Document | getOwnerDocument () |
The ownerDocument getter steps are to return null, if this is a document; otherwise this’s node document. | |
Node | getParentNode () |
Nodes might not have a parentNode. | |
Element | getParentElement () |
This value is the same as parentNode, except it puts an extra condition, that the parentNode must be an Element. | |
Wikimedia IDLeDOM Node | getRootNode ($options=null) |
Return this' shadow-including root if options['composed'] is true; otherwise return this' root. | |
Node | getPreviousSibling () |
Node | getNextSibling () |
getChildNodes () | |
This should be overridden in ContainerNode and Leaf. | |
getFirstChild () | |
This should be overridden in ContainerNode and Leaf. | |
getLastChild () | |
This should be overridden in ContainerNode and Leaf. | |
_roothook () | |
<script> elements need to know when they're inserted into the document. | |
Node | insertBefore ($node, $refNode=null) |
Insert $node as a child of $this, and insert it before $refChild in the document order. | |
appendChild ( $node) | |
Node | _unsafeAppendChild (Node $node) |
Does not check for insertion validity. | |
Node | replaceChild ( $new, $old) |
Node | removeChild ( $node) |
normalize () | |
Puts $this and the entire subtree rooted at $this into "normalized" form. | |
int | compareDocumentPosition ( $that) |
bool | contains ( $node) |
bool | isSameNode ( $node) |
bool | isEqualNode ( $node) |
Determine whether this node and $other are equal. | |
Node | cloneNode (bool $deep=false) |
Clone this Node. | |
string | lookupPrefix (?string $ns) |
Return DOMString containing prefix for given namespace URI. | |
string | lookupNamespaceURI (?string $prefix) |
Return DOMString containing namespace URI for a given prefix. | |
bool | isDefaultNamespace (?string $ns) |
Determine whether this is the default namespace. | |
string | getNodePath () |
Get an XPath for a node. | |
_resetNodeDocument (Document $doc) | |
Set the ownerDocument reference on a subtree rooted at $this. | |
bool | getIsConnected () |
Determine whether this Node is rooted (belongs to the tree rooted at the node document). | |
int | _getSiblingIndex () |
The index of this Node in its parent's childNodes list. | |
int | _lastModTime () |
Return the lastModTime value for this node. | |
_modify () | |
Increment the owner document's modclock [and use the new value to update the lastModTime value for this node and all of its ancestors. | |
_htmlSerialize (array &$result, array $options) | |
Convert the children of a node to an HTML string. | |
_xmlSerialize (?string $namespace, NamespacePrefixMap $prefixMap, int &$prefixIndex, array $options, array &$markup) | |
XML serialize the given node. | |
int | _length () |
bool | _empty () |
mixed | getExtensionData (string $key, $defaultValue=null) |
Get "extension data" associate with this node, using the given $key. | |
setExtensionData (string $key, $value) | |
Set "extension data" associate with this node, using the given $key. | |
Public Member Functions inherited from Wikimedia::IDLeDOM::EventTarget | |
void | addEventListener (string $type, $callback, $options=null) |
void | removeEventListener (string $type, $callback, $options=null) |
bool | dispatchEvent ( $event) |
Public Member Functions inherited from Wikimedia::IDLeDOM::Node | |
string | getBaseURI () |
bool | hasChildNodes () |
Public Attributes | |
Document | $_nodeDocument |
The document this node is associated to. | |
Node null | $_parentNode |
should be considered read-only | |
Node | $_nextSibling |
The sibling list is stored as a circular linked list: the node "before" the first sibling is the last sibling, and the node "after" the last sibling is the first sibling. | |
Node | $_previousSibling |
int | $_documentIndex = null |
DEVELOPERS NOTE: An index is assigned when a node is added to a Document (becomes rooted). | |
int | $_cachedSiblingIndex = null |
DEVELOPERS NOTE: An index is assigned on INSERTION. | |
Protected Member Functions | |
bool | _subclassIsEqualNode (Node $node) |
Delegated subclass method called by Node::isEqualNode() | |
Node | _subclassCloneNodeShallow () |
Delegated subclass method called by Node::cloneNode() | |
_setMissingProp (string $name, $value) | |
_getMissingProp (string $name) | |
Defines a "Node", the primary datatype of the W3C Document Object Model.
Conforms to W3C Document Object Model (DOM) Level 1 Recommendation (see: https://www.w3.org/TR/2000/WD-DOM-Level-1-20000929) -forbid-undeclared-magic-properties
Wikimedia\Dodo\Node::__construct | ( | Document | $nodeDocument | ) |
Create a Node whose node document is the given $nodeDocument.
Document | $nodeDocument |
Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\DocumentFragment.
|
abstract |
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CharacterData, Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\DocumentType.
|
protected |
int Wikimedia\Dodo\Node::_getSiblingIndex | ( | ) |
The index of this Node in its parent's childNodes list.
Throwable if we have no parent
NOTE Calling Node::_getSiblingIndex() will automatically trigger a switch to the NodeList representation (see Node::childNodes()).
Wikimedia\Dodo\Node::_htmlSerialize | ( | array & | $result, |
array | $options ) |
Convert the children of a node to an HTML string.
This is effectively 'innerHTML' for nodes in HTML documents. This is overridden in specific children, in particular HTMLTemplateElement.
string[] | &$result | The result is accumulated here |
array | $options | Format options passed to WhatWG::htmlSerialize |
Reimplemented in Wikimedia\Dodo\HTMLTemplateElement.
int Wikimedia\Dodo\Node::_lastModTime | ( | ) |
Return the lastModTime value for this node.
(For use as a cache invalidation mechanism. If the node does not already have one, initialize it from the owner document's modclock property. (Note that modclock does not return the actual time; it is simply a counter incremented on each document modification.)
|
abstract |
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CharacterData, Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\DocumentType.
Wikimedia\Dodo\Node::_modify | ( | ) |
Increment the owner document's modclock [and use the new value to update the lastModTime value for this node and all of its ancestors.
Nodes that have never had their lastModTime value queried do not need to have a lastModTime property set on them since there is no previously queried value to ever compare the new value against, so only update nodes that already have a _lastModTime property.]
Wikimedia\Dodo\Node::_resetNodeDocument | ( | Document | $doc | ) |
Set the ownerDocument reference on a subtree rooted at $this.
Called by Document::adoptNode()
Document | $doc |
Wikimedia\Dodo\Node::_roothook | ( | ) |
<script> elements need to know when they're inserted into the document.
See Document::_root(Node). Override this method to invoke such a hook.
|
protected |
Reimplemented in Wikimedia\Dodo\CharacterData, and Wikimedia\Dodo\Element.
|
abstractprotected |
Delegated subclass method called by Node::cloneNode()
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\Comment, Wikimedia\Dodo\Document, Wikimedia\Dodo\DocumentFragment, Wikimedia\Dodo\DocumentType, Wikimedia\Dodo\Element, Wikimedia\Dodo\ProcessingInstruction, and Wikimedia\Dodo\Text.
|
abstractprotected |
Delegated subclass method called by Node::isEqualNode()
Node | $node |
Reimplemented in Wikimedia\Dodo\DocumentFragment, and Wikimedia\Dodo\Element.
Does not check for insertion validity.
This out-performs PHP DOMDocument by over 2x.
Node | $node |
Reimplemented in Wikimedia\Dodo\Document.
Wikimedia\Dodo\Node::_xmlSerialize | ( | ?string | $namespace, |
NamespacePrefixMap | $prefixMap, | ||
int & | $prefixIndex, | ||
array | $options, | ||
array & | $markup ) |
XML serialize the given node.
This is overridden in subclasses. Note that this is effectively "outerHTML", due to a spec inconsistency: https://github.com/w3c/DOM-Parsing/issues/28 .
?string | $namespace | |
NamespacePrefixMap | $prefixMap | |
int | &$prefixIndex | |
array | $options | |
string[] | &$markup | accumulator for the result |
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CDATASection, Wikimedia\Dodo\Comment, Wikimedia\Dodo\Document, Wikimedia\Dodo\DocumentFragment, Wikimedia\Dodo\DocumentType, Wikimedia\Dodo\Element, Wikimedia\Dodo\ProcessingInstruction, and Wikimedia\Dodo\Text.
Wikimedia\Dodo\Node::appendChild | ( | $node | ) |
Implements Wikimedia::IDLeDOM::Node.
Node Wikimedia\Dodo\Node::cloneNode | ( | bool | $deep = false | ) |
Clone this Node.
spec DOM-LS
NOTE:
bool | $deep | if true, clone entire subtree |
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Document.
|
final |
Implements Wikimedia::IDLeDOM::Node.
|
final |
Implements Wikimedia::IDLeDOM::Node.
|
abstract |
This should be overridden in ContainerNode and Leaf.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Leaf.
mixed Wikimedia\Dodo\Node::getExtensionData | ( | string | $key, |
$defaultValue = null ) |
Get "extension data" associate with this node, using the given $key.
string | $key | Distinguishes between various types of extension data. |
mixed | $defaultValue | The value to return if the extension data is not present on this node; defaults to null . |
|
abstract |
This should be overridden in ContainerNode and Leaf.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Leaf.
bool Wikimedia\Dodo\Node::getIsConnected | ( | ) |
Determine whether this Node is rooted (belongs to the tree rooted at the node document).
NOTE Document nodes maintain a list of all the nodes inside their tree, assigning each an index, Node::_documentIndex.
Therefore if we are currently rooted, we can tell by checking that we have one of these.
Implements Wikimedia::IDLeDOM::Node.
|
abstract |
This should be overridden in ContainerNode and Leaf.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Leaf.
|
final |
Implements Wikimedia::IDLeDOM::Node.
|
abstract |
Return the nodeName
for this node.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CDATASection, Wikimedia\Dodo\Comment, Wikimedia\Dodo\Document, Wikimedia\Dodo\DocumentFragment, Wikimedia\Dodo\DocumentType, Wikimedia\Dodo\Element, Wikimedia\Dodo\ProcessingInstruction, and Wikimedia\Dodo\Text.
string Wikimedia\Dodo\Node::getNodePath | ( | ) |
Get an XPath for a node.
This is a PHP-compatibility extension to the DOM spec.
|
abstract |
Return the node type enumeration for this node.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CDATASection, Wikimedia\Dodo\Comment, Wikimedia\Dodo\Document, Wikimedia\Dodo\DocumentFragment, Wikimedia\Dodo\DocumentType, Wikimedia\Dodo\Element, Wikimedia\Dodo\ProcessingInstruction, and Wikimedia\Dodo\Text.
string Wikimedia\Dodo\Node::getNodeValue | ( | ) |
Return the value
for this node.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Attr, and Wikimedia\Dodo\CharacterData.
Document Wikimedia\Dodo\Node::getOwnerDocument | ( | ) |
The ownerDocument getter steps are to return null, if this is a document; otherwise this’s node document.
We will override this implementation to return null in the Document class.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Document.
|
final |
This value is the same as parentNode, except it puts an extra condition, that the parentNode must be an Element.
Accordingly, it requires no additional backing property, and can exist only as an accessor.
Implements Wikimedia::IDLeDOM::Node.
|
final |
Nodes might not have a parentNode.
Perhaps they have not been inserted into a DOM, or are a Document node, which is the root of a DOM tree and thus has no parent. In those cases, the value of parentNode is null.
Implements Wikimedia::IDLeDOM::Node.
|
final |
Implements Wikimedia::IDLeDOM::Node.
Wikimedia IDLeDOM Node Wikimedia\Dodo\Node::getRootNode | ( | $options = null | ) |
Return this' shadow-including root if options['composed'] is true; otherwise return this' root.
NOTE that the root of a node is not (necessarily) the ownerDocument or node document of the node!
GetRootNodeOptions | associative-array | null | $options |
Implements Wikimedia::IDLeDOM::Node.
string Wikimedia\Dodo\Node::getTextContent | ( | ) |
Return the textContent
for this node.
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CharacterData, Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Document.
Node Wikimedia\Dodo\Node::insertBefore | ( | $node, | |
$refNode = null ) |
Insert $node as a child of $this, and insert it before $refChild in the document order.
spec DOM-LS
THINGS TO KNOW FROM THE SPEC:
THINGS TO KNOW IN LIFE:
Despite its weird syntax (blame the spec), this is a real workhorse, used to implement all of the non-replacing insertion mutations.
INode | $node | To be inserted |
?INode | $refNode | Child of this node before which to insert $node |
DOMException | "HierarchyRequestError" or "NotFoundError" |
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Document, and Wikimedia\Dodo\Leaf.
bool Wikimedia\Dodo\Node::isDefaultNamespace | ( | ?string | $ns | ) |
Determine whether this is the default namespace.
Implements Wikimedia::IDLeDOM::Node.
bool Wikimedia\Dodo\Node::isEqualNode | ( | $node | ) |
Determine whether this node and $other are equal.
spec: DOM-LS
NOTE: Each subclass of Node has its own criteria for equality. Rather than extend Node::isEqualNode(), subclasses must implement _subclassIsEqualNode(), which is called from Node::isEqualNode() and handles all of the equality testing specific to the subclass.
This allows the recursion and other fast checks to be handled here and written just once.
Yes, we realize it's a bit weird.
Implements Wikimedia::IDLeDOM::Node.
|
final |
Implements Wikimedia::IDLeDOM::Node.
string Wikimedia\Dodo\Node::lookupNamespaceURI | ( | ?string | $prefix | ) |
Return DOMString containing namespace URI for a given prefix.
NOTE Inverse of Node::lookupPrefix
Implements Wikimedia::IDLeDOM::Node.
string Wikimedia\Dodo\Node::lookupPrefix | ( | ?string | $ns | ) |
Return DOMString containing prefix for given namespace URI.
spec DOM-LS
NOTE Think this function looks weird? It's actually spec: https://dom.spec.whatwg.org/#locate-a-namespace
Implements Wikimedia::IDLeDOM::Node.
|
final |
Puts $this and the entire subtree rooted at $this into "normalized" form.
In a normalized sub-tree, no text nodes in the sub-tree are empty, and there are no adjacent text nodes.
Implements Wikimedia::IDLeDOM::Node.
Node Wikimedia\Dodo\Node::removeChild | ( | $node | ) |
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Document, and Wikimedia\Dodo\Leaf.
Node Wikimedia\Dodo\Node::replaceChild | ( | $new, | |
$old ) |
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Document, and Wikimedia\Dodo\Leaf.
Wikimedia\Dodo\Node::setExtensionData | ( | string | $key, |
$value ) |
Set "extension data" associate with this node, using the given $key.
string | $key | Distinguishes between various types of extension data. |
mixed | $value | The value to store under this $key on this node. |
Wikimedia\Dodo\Node::setNodeValue | ( | ?string | $val | ) |
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Attr, and Wikimedia\Dodo\CharacterData.
Wikimedia\Dodo\Node::setTextContent | ( | ?string | $val | ) |
Implements Wikimedia::IDLeDOM::Node.
Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CharacterData, Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Document.
int Wikimedia\Dodo\Node::$_cachedSiblingIndex = null |
DEVELOPERS NOTE: An index is assigned on INSERTION.
It uniquely identifies the Node among its siblings.
It is used to help compute document position and to mark where insertion should occur.
Its existence is, frankly, mostly for convenience due to the fact that the most common representation of child nodes is a linked list that doesn't have numeric indices otherwise.
FIXME It is public because it gets used by the whatwg algorithms page.
int Wikimedia\Dodo\Node::$_documentIndex = null |
DEVELOPERS NOTE: An index is assigned when a node is added to a Document (becomes rooted).
It uniquely identifies the Node within its owner Document.
This index makes it simple to represent a Node as an integer.
This is also used to determine if a Node is currently rooted.
It allows this optimization: If two Elements have the same id, they will be stored in an array under their $document_index. This means we don't have to search the array for a matching Node when another node with the same ID is added or removed from the document; we can do a look up in O(1). If your document contains lots of elements with identical IDs, this prevents a quadratic slowdown.
Node Wikimedia\Dodo\Node::$_nextSibling |
The sibling list is stored as a circular linked list: the node "before" the first sibling is the last sibling, and the node "after" the last sibling is the first sibling.
This makes finding the last sibling as quick as finding the first.
As a consequence, if a Node has no siblings, i.e. it is the 'only child' of $_parentNode, then the properties $_nextSibling and $_previousSibling are set equal to $this (ie, a single-element circular list).
Obviously, the DOM LS accessors return 'null' at the beginning and ends of the list (as well as for both siblings when the node is an only child); we tweak the getters to make this work.
But be very careful when you access _nextSibling
directly! If you want a null-terminated list, use getNextSibling()
instead!
Document Wikimedia\Dodo\Node::$_nodeDocument |
The document this node is associated to.
spec DOM-LS
NOTE This is different from ownerDocument: According to DOM-LS, Document::ownerDocument() must equal NULL, even though it's often more convenient if a document is its own owner.
What we're looking for is the "node document" concept, as laid out in the DOM-LS spec:
-"Each node has an associated node document, set upon creation, that is a document." -"A node's node document can be changed by the 'adopt' algorithm." -"The node document of a document is that document itself." -"All nodes have a node document at all times."
NOTE The DOM-LS method Node::getRootNode (and the "root" of a node) is not the same thing: the root of a node which hasn't been added to the document is the highest ancestor; while the node document is always the owning document even if this node hasn't yet been added to it.
Node Wikimedia\Dodo\Node::$_previousSibling |