Skip to content

Commit e57b595

Browse files
usernaneusernane
committed
Update HTMLNode.php
1 parent 1a5bce4 commit e57b595

File tree

1 file changed

+134
-23
lines changed

1 file changed

+134
-23
lines changed

‎WebFiori/UI/HTMLNode.php‎

Lines changed: 134 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,11 @@ class HTMLNode implements Countable, Iterator {
2626
/**
2727
* A constant that indicates a node is of type comment.
2828
*
29+
* Used when creating comment nodes or checking node types.
30+
* Comment nodes are rendered as <!-- content --> in HTML output.
31+
*
2932
* @var string
33+
* @see isComment() To check if node is comment type
3034
*/
3135
const COMMENT_NODE = '#COMMENT';
3236
/**
@@ -79,8 +83,12 @@ class HTMLNode implements Countable, Iterator {
7983
];
8084
/**
8185
* A constant that indicates a node is of type text.
86+
*
87+
* Used for nodes that contain only text content without HTML tags.
88+
* Text nodes can have HTML entities escaped for security.
89+
*
8290
* @var string
83-
*
91+
* @see isTextNode() To check if node is text type
8492
*/
8593
const TEXT_NODE = '#TEXT';
8694
/**
@@ -232,8 +240,7 @@ class HTMLNode implements Countable, Iterator {
232240
*
233241
* @param array $attrs An optional array that contains node attributes.
234242
*
235-
* @throws InvalidNodeNameException The method will throw an exception if given node
236-
* name is not valid.
243+
* @throws InvalidNodeNameException When the provided node name is invalid, empty, or contains illegal characters
237244
*/
238245
public function __construct(string $name = 'div', array $attrs = []) {
239246
$this->null = null;
@@ -409,6 +416,14 @@ public function addTextNode(string $text, bool $escHtmlEntities = true) {
409416
* @return HTMLNode The method will return the instance that this
410417
* method is called on.
411418
*
419+
* @example
420+
* ```php
421+
* $node->setStyle([
422+
* "color" => "red",
423+
* "background-color" => "#ffffff",
424+
* "margin" => "10px 5px"
425+
* ]);
426+
* ```
412427
*
413428
*/
414429
public function anchor(string|HTMLNode $body, array $attributes = []) : HTMLNode {
@@ -516,6 +531,14 @@ public function asCode(array $formattingOptions = HTMLNode::DEFAULT_CODE_FORMAT)
516531
* @return HTMLNode The method will return the instance that this
517532
* method is called on.
518533
*
534+
* @example
535+
* ```php
536+
* $node->setStyle([
537+
* "color" => "red",
538+
* "background-color" => "#ffffff",
539+
* "margin" => "10px 5px"
540+
* ]);
541+
* ```
519542
*
520543
*/
521544
public function br() : HTMLNode {
@@ -672,6 +695,14 @@ public function codeSnippet(string $title, $code, array $attributes = []) : HTML
672695
* @return HTMLNode The method will return the instance that this
673696
* method is called on.
674697
*
698+
* @example
699+
* ```php
700+
* $node->setStyle([
701+
* "color" => "red",
702+
* "background-color" => "#ffffff",
703+
* "margin" => "10px 5px"
704+
* ]);
705+
* ```
675706
*
676707
*/
677708
public function comment(string $txt) {
@@ -840,23 +871,30 @@ public function form(array $attributes = []) : HTMLNode {
840871

841872
/**
842873
* Create HTML from template or HTML file.
874+
*
875+
* This is a factory method that creates HTMLNode instances from external files.
876+
* Supports both HTML templates with slots ({{variable}}) and PHP templates with variables.
843877
*
844-
* @param string $absPath The absolute path to HTML document. This can
845-
* also be the path to PHP template file.
878+
* @param string $absPath Absolute path to template file (.html or .php extension)
879+
* @param array $slotsOrVars For HTML templates: slot values. For PHP templates: variables to extract
846880
*
847-
* @param array $slotsOrVars An associative array that have slots values of
848-
* the template. This also can be the values that will be passed to PHP
849-
* template.
881+
* @return array|HeadNode|HTMLDoc|HTMLNode Return type depends on template structure:
882+
* - HTMLDoc: Complete HTML document with DOCTYPE, html, head, body
883+
* - HTMLNode: Single root element template
884+
* - array: Multiple root elements (fragment)
885+
* - HeadNode: If template contains only head section
850886
*
851-
* @return array|HeadNode|HTMLDoc|HTMLNode If the given template represents HTML document,
852-
* an object of type 'HTMLDoc' is returned. If the given code has multiple top level nodes
853-
* (e.g. '&lt;div&gt;&lt;/div&gt;&lt;div&gt;&lt;/div&gt;'),
854-
* an array that contains an objects of type 'HTMLNode' is returned. If the
855-
* given code has one top level node, an object of type 'HTMLNode' is returned.
856-
* Note that it is possible that the method will return an instance which
857-
* is a subclass of the class 'HTMLNode'.
858-
*
859-
* @throws TemplateNotFoundException
887+
* @throws TemplateNotFoundException When template file does not exist
888+
* @throws InvalidNodeNameException When template contains invalid HTML elements
889+
*
890+
* @example
891+
* ```php
892+
* // HTML template with slots
893+
* $node = HTMLNode::fromFile('page.html', ['title' => 'My Page']);
894+
*
895+
* // PHP template with variables
896+
* $node = HTMLNode::fromFile('list.php', ['items' => $dataArray]);
897+
* ```
860898
*/
861899
public static function fromFile(string $absPath, array $slotsOrVars = []) {
862900
$compiler = new TemplateCompiler($absPath, $slotsOrVars);
@@ -942,9 +980,9 @@ public function getAttributeValue(string $attrName) {
942980
* @param int $index The position of the child node. This must be an integer
943981
* value starting from 0.
944982
*
945-
* @return HTMLNode|null If the child does exist, the method will return
946-
* an object of type 'HTMLNode'. If no element was found, the method will
947-
* return null.
983+
* @return HTMLNode|null Return value depends on index validity:
984+
* - HTMLNode: When child exists at the specified index
985+
* - null: When index is out of bounds (< 0 or >= childrenCount())
948986
*
949987
*
950988
*/
@@ -985,8 +1023,9 @@ public function getChildByAttributeValue(string $attrName, string $attrVal) {
9851023
*
9861024
* @param string $val The value to search for. The ID of the child.
9871025
*
988-
* @return null|HTMLNode The method returns an object of type HTMLNode
989-
* if found. If no node has the given ID, the method will return null.
1026+
* @return HTMLNode|null Return value depends on search result:
1027+
* - HTMLNode: When a child with the specified ID is found
1028+
* - null: When no child has the given ID or ID is empty
9901029
*
9911030
*
9921031
*/
@@ -1249,6 +1288,14 @@ public function hasChild($node) : bool {
12491288
* @return HTMLNode The method will return the instance that this
12501289
* method is called on.
12511290
*
1291+
* @example
1292+
* ```php
1293+
* $node->setStyle([
1294+
* "color" => "red",
1295+
* "background-color" => "#ffffff",
1296+
* "margin" => "10px 5px"
1297+
* ]);
1298+
* ```
12521299
*
12531300
*/
12541301
public function hr() : HTMLNode {
@@ -1515,6 +1562,14 @@ public function label($body, array $attributes = []) : HTMLNode {
15151562
* @return HTMLNode The method will return the instance that this
15161563
* method is called on.
15171564
*
1565+
* @example
1566+
* ```php
1567+
* $node->setStyle([
1568+
* "color" => "red",
1569+
* "background-color" => "#ffffff",
1570+
* "margin" => "10px 5px"
1571+
* ]);
1572+
* ```
15181573
*
15191574
*/
15201575
public function li($itemBody, array $attributes = []) : HTMLNode {
@@ -1984,6 +2039,14 @@ public function setIsVoidNode(bool $bool) {
19842039
* @return HTMLNode The method will return the instance that this
19852040
* method is called on.
19862041
*
2042+
* @example
2043+
* ```php
2044+
* $node->setStyle([
2045+
* "color" => "red",
2046+
* "background-color" => "#ffffff",
2047+
* "margin" => "10px 5px"
2048+
* ]);
2049+
* ```
19872050
*
19882051
*/
19892052
public function setName(string $val) : HTMLNode {
@@ -2045,7 +2108,7 @@ public function setNodeName(string $name) : bool {
20452108
/**
20462109
* Sets the value of the attribute 'style' of the node.
20472110
*
2048-
* @param array $cssStyles An associative array of CSS declarations. The keys of the array should
2111+
* @param array $cssStyles Associative array of CSS declarations. Keys are CSS property names (e.g., "color", "background-color"), values are CSS values (e.g., "red", "#ffffff"). The keys of the array should
20492112
* be the names of CSS Properties and the values should be the values of
20502113
* the attributes (e.g. 'color'=>'white').
20512114
*
@@ -2056,6 +2119,14 @@ public function setNodeName(string $name) : bool {
20562119
* @return HTMLNode The method will return the instance that this
20572120
* method is called on.
20582121
*
2122+
* @example
2123+
* ```php
2124+
* $node->setStyle([
2125+
* "color" => "red",
2126+
* "background-color" => "#ffffff",
2127+
* "margin" => "10px 5px"
2128+
* ]);
2129+
* ```
20592130
*
20602131
*/
20612132
public function setStyle(array $cssStyles, bool $override = false) : HTMLNode {
@@ -2106,6 +2177,14 @@ public function setStyle(array $cssStyles, bool $override = false) : HTMLNode {
21062177
* @return HTMLNode The method will return the instance that this
21072178
* method is called on.
21082179
*
2180+
* @example
2181+
* ```php
2182+
* $node->setStyle([
2183+
* "color" => "red",
2184+
* "background-color" => "#ffffff",
2185+
* "margin" => "10px 5px"
2186+
* ]);
2187+
* ```
21092188
*
21102189
*/
21112190
public function setTabIndex(int $val) : HTMLNode {
@@ -2128,6 +2207,14 @@ public function setTabIndex(int $val) : HTMLNode {
21282207
* @return HTMLNode The method will return the instance that this
21292208
* method is called on.
21302209
*
2210+
* @example
2211+
* ```php
2212+
* $node->setStyle([
2213+
* "color" => "red",
2214+
* "background-color" => "#ffffff",
2215+
* "margin" => "10px 5px"
2216+
* ]);
2217+
* ```
21312218
*
21322219
*/
21332220
public function setText(string $text, bool $escHtmlEntities = true) : HTMLNode {
@@ -2153,6 +2240,14 @@ public function setText(string $text, bool $escHtmlEntities = true) : HTMLNode {
21532240
* @return HTMLNode The method will return the instance that this
21542241
* method is called on.
21552242
*
2243+
* @example
2244+
* ```php
2245+
* $node->setStyle([
2246+
* "color" => "red",
2247+
* "background-color" => "#ffffff",
2248+
* "margin" => "10px 5px"
2249+
* ]);
2250+
* ```
21562251
*
21572252
*/
21582253
public function setTitle(string $val) : HTMLNode {
@@ -2179,6 +2274,14 @@ public function setUseForwardSlash(bool $hasForward) {
21792274
* @return HTMLNode The method will return the instance that this
21802275
* method is called on.
21812276
*
2277+
* @example
2278+
* ```php
2279+
* $node->setStyle([
2280+
* "color" => "red",
2281+
* "background-color" => "#ffffff",
2282+
* "margin" => "10px 5px"
2283+
* ]);
2284+
* ```
21822285
*
21832286
*/
21842287
public function setWritingDir(string $val) : HTMLNode {
@@ -2221,6 +2324,14 @@ public function table(array $attributes = []) : HTMLNode {
22212324
* @return HTMLNode The method will return the instance that this
22222325
* method is called on.
22232326
*
2327+
* @example
2328+
* ```php
2329+
* $node->setStyle([
2330+
* "color" => "red",
2331+
* "background-color" => "#ffffff",
2332+
* "margin" => "10px 5px"
2333+
* ]);
2334+
* ```
22242335
*
22252336
*/
22262337
public function text(string $txt, bool $escEntities = true) : HTMLNode {

0 commit comments

Comments
 (0)