MensBeam
/
HTML-DOM
3
0
Fork 0
Code Issues Pull Requests Releases Activity
Browse Source

More documentation updates, started on Element documentation

split-manual
Dustin Wilson 3 years ago
parent
89f1b6eebc
commit
0d7f7ef0bf
10 changed files with 208 additions and 11 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 7
      docs/en/030_Document_Object_Model/010_Document/index.md
  2. 24
      docs/en/030_Document_Object_Model/020_Element/010_getAttribute.md
  3. 26
      docs/en/030_Document_Object_Model/020_Element/010_getAttributeNS.md
  4. 88
      docs/en/030_Document_Object_Model/020_Element/index.md
  5. 44
      docs/en/030_Document_Object_Model/Moonwalk/010_moonwalk.md
  6. 11
      docs/en/030_Document_Object_Model/Moonwalk/index.md
  7. 2
      docs/en/030_Document_Object_Model/Walk/010_walk.md
  8. 1
      lib/DOM/Document.php
  9. 8
      lib/DOM/traits/Moonwalk.php
  10. 8
      lib/DOM/traits/Walk.php

7
docs/en/030_Document_Object_Model/010_Document/index.md
View File

@ -2,7 +2,7 @@
title: Document
---
# The Document class #
# The Document Class #
## Introduction ##
@ -10,7 +10,10 @@ Represents an entire HTML document; serves as the root of the document tree. Unl
<div class="info"><p><strong>Info</strong> Only new methods and methods which make outward-facing changes from <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> will be documented here, otherwise they will be linked back to PHP's documentation.</p></div>
## Class Synopsis ##
<pre><code class="php">MensBeam\HTML\Document extends <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> {
use <a href="../Node/index.html">Node</a>, <a href="../Walk/index.html">Walk</a>;
/* Constants */
@ -70,7 +73,7 @@ Represents an entire HTML document; serves as the root of the document tree. Unl
public <a href="../Node/insertBefore.html">Node::insertBefore</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $node , <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null $child = null ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
/* Methods from <a href="../Walk/index.html">Walk</a> */
public <a href="../Walk/walk.html">walk</a> ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
public <a href="../Walk/walk.html">walk</a> ( ?<a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter = null ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
/* Methods inherited from <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> */
public <a href="https://www.php.net/manual/en/domdocument.createattribute.php">createAttribute</a> ( string $localName ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|false

24
docs/en/030_Document_Object_Model/020_Element/010_getAttribute.md
View File

@ -0,0 +1,24 @@
---
title: Element::getAttribute
---
Element::getAttribute — Returns value of attribute
## Description ##
```php
public Element::getAttribute ( string $qualifiedName ) : string|null
```
Gets the value of the attribute with name `qualifiedName` for the current node.
## Parameters ##
<dl>
<dt><code>qualifiedName</code></dt>
<dd>The name of the attribute.</dd>
</dl>
## Return Values ##
Returns a string on success or <code>null</code> if no attribute with the given `qualifiedName` is found. `\DOMElement::getAttribute` returns an empty string on failure which is incorrect in newer versions of the DOM.

26
docs/en/030_Document_Object_Model/020_Element/010_getAttributeNS.md
View File

@ -0,0 +1,26 @@
---
title: Element::getAttributeNS
---
Element::getAttributeNS — Returns value of attribute
## Description ##
```php
public Element::getAttribute ( string|null $namespace , string $localName ) : string|null
```
Gets the value of the attribute in namespace `namespace` with local name `localName` for the current node.
## Parameters ##
<dl>
<dt><code>namespace</code></dt>
<dd>The namespace URI.</dd>
<dt><code>localName</code></dt>
<dd>The local name of the attribute.</dd>
</dl>
## Return Values ##
Returns a string on success or <code>null</code> if no attribute with the given `localName` and `namespace` is found. `\DOMElement::getAttribute` returns an empty string on failure which is incorrect in newer versions of the DOM.

88
docs/en/030_Document_Object_Model/020_Element/index.md
View File

@ -0,0 +1,88 @@
---
title: Element
---
# The Element Class #
## Introduction ##
<div class="info"><p><strong>Info</strong> Only new methods and methods which make outward-facing changes from <a href="https://www.php.net/manual/en/class.domelement.php">\DOMElement</a> will be documented here, otherwise they will be linked back to PHP's documentation.</p></div>
## Class Synopsis ##
<pre><code class="php">MensBeam\HTML\Element extends <a href="https://www.php.net/manual/en/class.domelement.php">\DOMElement</a> {
use <a href="../Moonwalk/index.html">Moonwalk</a>, <a href="../Node/index.html">Node</a>, <a href="../Walk/index.html">Walk</a>;
/* Inherited properties from <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> */
public readonly string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nodename">$nodeName</a> ;
public string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nodevalue">$nodeValue</a> ;
public readonly int <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nodetype">$nodeType</a> ;
public readonly <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.parentnode">$parentNode</a> ;
public readonly <a href="https://www.php.net/manual/en/class.domnodelist.php">\DOMNodeList</a> <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.childnodes">$childNodes</a> ;
public readonly <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.firstchild">$firstChild</a> ;
public readonly <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.lastchild">$lastChild</a> ;
public readonly <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.previoussibling">$previousSibling</a> ;
public readonly <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nextsibling">$nextSibling</a> ;
public readonly <a href="https://www.php.net/manual/en/class.domnamednodemap.php">\DOMNamedNodeMap</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.attributes">$attributes</a> ;
public readonly Document|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.ownerdocument">$ownerDocument</a> ;
public readonly string|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.namespaceuri">$namespaceURI</a> ;
public string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.prefix">$prefix</a> ;
public readonly string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.localname">$localName</a> ;
public readonly string|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.baseuri">$baseURI</a> ;
public string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.textcontent">$textContent</a> ;
/* Methods */
public <a href="getAttribute.html">getAttribute</a> ( string $qualifiedName ) : string|null
public <a href="getAttributeNS.html">getAttributeNS</a> ( string|null $namespace , string $localName ) : string|null
/* Magic Methods */
public __toString() : string
/* Methods from <a href="../Moonwalk/index.html">Moonwalk</a> */
public <a href="../Moonwalk/moonwalk.html">moonwalk</a> ( ?<a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter = null ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
/* Methods from <a href="../Node/index.html">Node</a> */
public <a href="../Node/appendChild.html">Node::appendChild</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $node ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
public <a href="../Node/C14N.html">Node::C14N</a> ( bool $exclusive = false , bool $withComments = false , null $xpath = null , null $nsPrefixes = null ) : false
public <a href="../Node/C14NFile.html">Node::C14NFile</a> ( string $uri , bool $exclusive = false , bool $withComments = false , null $xpath = null , null $nsPrefixes = null ) : false
public <a href="../Node/insertBefore.html">Node::insertBefore</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $node , <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null $child = null ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
/* Methods from <a href="../Walk/index.html">Walk</a> */
public <a href="../Walk/walk.html">walk</a> ( ?<a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter = null ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
/* Methods inherited from <a href="https://www.php.net/manual/en/class.domelement.php">\DOMElement</a> */
public <a href="https://www.php.net/manual/en/domelement.construct.php">__construct</a> ( string $qualifiedName , string|null $value = null , string $namespace = "" )
public <a href="https://www.php.net/manual/en/domelement.getattributenode.php">getAttributeNode</a> ( string $qualifiedName ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|false
public <a href="https://www.php.net/manual/en/domelement.getattributenodens.php">getAttributeNodeNS</a> ( string|null $namespace , string $localName ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|null
public <a href="https://www.php.net/manual/en/domelement.getelementsbytagname.php">getElementsByTagName</a> ( string $qualifiedName ) : <a href="https://www.php.net/manual/en/class.domnodelist.php">\DOMNodeList</a>
public <a href="https://www.php.net/manual/en/domelement.getelementsbytagnamens.php">getElementsByTagNameNS</a> ( string $namespace , string $localName ) : <a href="https://www.php.net/manual/en/class.domnodelist.php">\DOMNodeList</a>
public <a href="https://www.php.net/manual/en/domelement.hasattribute.php">hasAttribute</a> ( string $qualifiedName ) : bool
public <a href="https://www.php.net/manual/en/domelement.hasattributens.php">hasAttributeNS</a> ( string|null $namespace , string $localName ) : bool
public <a href="https://www.php.net/manual/en/domelement.removeattribute.php">removeAttribute</a> ( string $qualifiedName ) : bool
public <a href="https://www.php.net/manual/en/domelement.removeattributenode.php">removeAttributeNode</a> ( <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a> $attr ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|false
public <a href="https://www.php.net/manual/en/domelement.removeattributenodens.php">removeAttributeNS</a> ( string|null $namespace , string $localName ) : void
public <a href="https://www.php.net/manual/en/domelement.setattribute.php">setAttribute</a> ( string $qualifiedName , string $value ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|bool
public <a href="https://www.php.net/manual/en/domelement.setattributenode.php">setAttributeNode</a> ( <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a> $attr ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|null|false
public <a href="https://www.php.net/manual/en/domelement.setattributenodens.php">setAttributeNodeNS</a> ( <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a> $attr ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|null|false
public <a href="https://www.php.net/manual/en/domelement.setattributens.php">setAttributeNS</a> ( string|null $namespace , string $qualifiedName , string $value ) : void
public <a href="https://www.php.net/manual/en/domelement.setidattribute.php">setIdAttribute</a> ( string $qualifiedName , bool $isId ) : void
public <a href="https://www.php.net/manual/en/domelement.setidattributenode.php">setIdAttributeNode</a> ( <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a> $attr , bool $isId ) : void
public <a href="https://www.php.net/manual/en/domelement.setidattributens.php">setIdAttributeNS</a> ( string $namespace , string $qualifiedName , bool $isId ) : void
/* Methods inherited from <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> */
public <a href="https://www.php.net/manual/en/domnode.clonenode.php">\DOMNode::cloneNode</a> ( bool $deep = false ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
public <a href="https://www.php.net/manual/en/domnode.getlineno.php">\DOMNode::getLineNo</a> ( ) : int
public <a href="https://www.php.net/manual/en/domnode.getnodepath.php">\DOMNode::getNodePath</a> ( ) : string|null
public <a href="https://www.php.net/manual/en/domnode.hasattributes.php">\DOMNode::hasAttributes</a> ( ) : bool
public <a href="https://www.php.net/manual/en/domnode.haschildnodes.php">\DOMNode::hasChildNodes</a> ( ) : bool
public <a href="https://www.php.net/manual/en/domnode.isdefaultnamespace.php">\DOMNode::isDefaultNamespace</a> ( string $namespace ) : bool
public <a href="https://www.php.net/manual/en/domnode.issamenode.php">\DOMNode::isSameNode</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $otherNode ) : bool
public <a href="https://www.php.net/manual/en/domnode.issupported.php">\DOMNode::isSupported</a> ( string $feature , string $version ) : bool
public <a href="https://www.php.net/manual/en/domnode.lookupnamespaceuri.php">\DOMNode::lookupNamespaceUri</a> ( string $prefix ) : string
public <a href="https://www.php.net/manual/en/domnode.lookupprefix.php">\DOMNode::lookupPrefix</a> ( string $namespace ) : string|null
public <a href="https://www.php.net/manual/en/domnode.normalize.php">\DOMNode::normalize</a> ( ) : void
public <a href="https://www.php.net/manual/en/domnode.removechild.php">\DOMNode::removeChild</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $child ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
public <a href="https://www.php.net/manual/en/domnode.replacechild.php">\DOMNode::replaceChild</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $node , <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $child ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
}</code></pre>

44
docs/en/030_Document_Object_Model/Moonwalk/010_moonwalk.md
View File

@ -0,0 +1,44 @@
---
title: Moonwalk::moonwalk
---
Moonwalk::moonwalk — Output generator for walking up the DOM tree
## Description ##
```php
public Moonwalk::moonwalk ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
```
Non-standard. Creates a [`\Generator`](https://www.php.net/manual/en/class.generator.php) object for walking up the DOM tree. This is in lieu of recreating the awful [DOM TreeWalker API](https://developer.mozilla.org/en-US/docs/Web/API/Treewalker).
## Examples ##
**Example \#1 Print name of all ancestors of the H1 element**
```php
<?php
namespace MensBeam\HTML;
$dom = new Document();
$dom->loadHTML('<!DOCTYPE html><html><head><title>Ook!</title></head><body><h1>Eek</h1></body></html>');
$h1 = $dom->getElementsByTagName('h1')->item(0);
// All ancestors will be elements so there's no reason to have a filter.
$tree = $h1->moonwalk();
foreach ($tree as $t) {
echo "{$t->nodeName}\n";
}
?>
```
The above example will output something similar to:
```php
body
html
```

11
docs/en/030_Document_Object_Model/Moonwalk/index.md
View File

@ -0,0 +1,11 @@
# The Moonwalk trait #
## Introduction ##
Allows the extended PHP DOM classes to Moonwalk up the DOM via a [`\Generator`](https://www.php.net/manual/en/class.generator.php). This is in lieu of recreating the awful [DOM TreeMoonwalker API](https://developer.mozilla.org/en-US/docs/Web/API/TreeMoonwalker).
<pre><code class="php">trait MensBeam\HTML\Moonwalk {
public <a href="Moonwalk.html">Moonwalk</a> ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
}</code></pre>

2
docs/en/030_Document_Object_Model/Walk/010_walk.md
View File

@ -10,7 +10,7 @@ Walk::walk — Output generator for walking down the DOM tree
public Walk::walk ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
```
Creates a [`\Generator`](https://www.php.net/manual/en/class.generator.php) object for walking down the DOM tree. This is in lieu of recreating the awful [DOM TreeWalker API](https://developer.mozilla.org/en-US/docs/Web/API/Treewalker).
Non-standard. Creates a [`\Generator`](https://www.php.net/manual/en/class.generator.php) object for walking down the DOM tree. This is in lieu of recreating the awful [DOM TreeWalker API](https://developer.mozilla.org/en-US/docs/Web/API/Treewalker).
## Examples ##

1
lib/DOM/Document.php
View File

@ -168,6 +168,7 @@ class Document extends \DOMDocument {
do {
if ($n instanceof Element && $n->namespaceURI === null && ($n->nodeName === 'body' || $n->nodeName === 'frameset')) {
$body = $n;
break;
}
} while ($n = $n->nextSibling);

8
lib/DOM/traits/Moonwalk.php
View File

@ -7,13 +7,13 @@ declare(strict_types=1);
namespace MensBeam\HTML;
trait Moonwalk {
public function moonwalk(\Closure $filter): \Generator {
public function moonwalk(?\Closure $filter = null): \Generator {
return $this->moonwalkGenerator($this, $filter);
}
private function moonwalkGenerator(\DOMNode $node, \Closure $filter) {
private function moonwalkGenerator(\DOMNode $node, ?\Closure $filter = null) {
do {
if ($filter($node)) {
if ($filter === null || $filter($node)) {
yield $node;
}
} while ($node = $node->parentNode);

8
lib/DOM/traits/Walk.php
View File

@ -7,12 +7,12 @@ declare(strict_types=1);
namespace MensBeam\HTML;
trait Walk {
public function walk(\Closure $filter): \Generator {
public function walk(?\Closure $filter = null): \Generator {
return $this->walkGenerator($this, $filter);
}
private function walkGenerator(\DOMNode $node, \Closure $filter) {
if ($filter($node)) {
private function walkGenerator(\DOMNode $node, ?\Closure $filter = null) {
if ($filter === null || $filter($node)) {
yield $node;
}

Write Preview
Loading…
Cancel
Save