Add doc Head::class. (#269)

php-forge · Feb 1, 2024 · a0388bf · a0388bf
1 parent c6f41ff
commit a0388bf
Show file tree

Hide file tree

Showing 4 changed files with 177 additions and 24 deletions.
diff --git a/docs/tag/H.md b/docs/tag/H.md
@@ -118,7 +118,7 @@ The following methods are available for customizing the `HTML` output:
 | ---------- | -------------------------------------------------------------------------------------------------------- |
 | `begin()  `| Start the `h` element.                                                                                   |
 | `end()`    | End the `h` element, and generate the `HTML` output.                                                     |
+| `render()` | Generates the `HTML` output.                                                                             |
 | `tagName()`| Set the `tag` name.                                                                                      |
 |            | Alowed values: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`. For default value its `h1`.                           |
-| `render()` | Generates the `HTML` output.                                                                             |
 | `widget()` | Instantiates the `Body::class`.                                                                          |
diff --git a/docs/tag/Head.md b/docs/tag/Head.md
@@ -0,0 +1,118 @@
+# Head
+
+The `<head>` `HTML` element contains machine-readable information (metadata) about the document, like its title,
+scripts, and style sheets.
+
+## Basic Usage
+
+Instantiate the `Head` class using `Head::widget()`.
+
+```php
+$head = Head::widget();
+```
+
+Or, block style instantiation.
+
+```php
+<?= Head::begin() ?>
+    // ... content to be wrapped by `head` element
+<?= Head::end() ?>
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting href attribute
+$head->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$head->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding Content
+
+If you want to include content within the `head` tag, use the `content` method.
+
+```php
+$head->content('My content');
+```
+
+Or, use `begin()` and `end()` methods to wrap content.
+
+```php
+<?= Head::begin() ?>
+    My content
+<?= Head::end() ?>
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $head->render();
+```
+
+For block style instantiation, use the `end()` method, which returns the `HTML` output.
+
+```php
+$html = Head::end();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $head;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$head->class('external')->content('My content');
+
+// using data attributes
+$head->dataAttributes(['analytics' => 'trackClick']);
+```
+
+Explore additional methods for setting various attributes such as `lang`, `name`, `style`, `title`, etc.
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Head/AttributeTest.php) for
+comprehensive examples.
+
+The following methods are available for setting attributes:
+
+| Method            | Description                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `attributes()`    | Set multiple `attributes` at once.                                                               |
+| `class()`         | Set the `class` attribute.                                                                       |
+| `content()`       | Set the `content` within the `head` element.                                                     |
+| `dataAttributes()`| Set multiple `data-attributes` at once.                                                          |
+| `id()`            | Set the `id` attribute.                                                                          |
+| `lang()`          | Set the `lang` attribute.                                                                        |
+| `name()`          | Set the `name` attribute.                                                                        |
+| `style()`         | Set the `style` attribute.                                                                       |
+| `title()`         | Set the `title` attribute.                                                                       |
+
+## Custom methods
+
+Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/Head/CustomMethodTest.php) for
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method    | Description                                                                                              |
+| --------- | -------------------------------------------------------------------------------------------------------- |
+| `begin() `| Start the `head` element.                                                                                |
+| `end()`   | End the `head` element, and generate the `HTML` output.                                                  |
+| `render()`| Generates the `HTML` output.                                                                             |
+| `widget()`| Instantiates the `Body::class`.                                                                          |
diff --git a/tests/Head/RenderTest.php → tests/Head/AttributeTest.php b/tests/Head/RenderTest.php → tests/Head/AttributeTest.php
@@ -11,101 +11,105 @@
 /**
  * @psalm-suppress PropertyNotSetInConstructor
  */
-final class RenderTest extends TestCase
+final class AttributeTest extends TestCase
 {
     public function testAttributes(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head class="test-class">
+            <head class="value">
             </head>
             HTML,
-            Head::widget()->attributes([
-                'class' => 'test-class',
-            ])->render(),
+            Head::widget()->attributes(['class' => 'value'])->render(),
         );
     }
 
     public function testClass(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head class="test-class">
+            <head class="value">
             </head>
             HTML,
-            Head::widget()->class('test-class')->render(),
+            Head::widget()->class('value')->render(),
         );
     }
 
-    public function testBlockLevelElements(): void
+    public function testContent(): void
     {
-        $this->assertSame('<head>test block</head>', Head::widget()->begin() . 'test block' . Head::end());
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <head>
+            test content
+            </head>
+            HTML,
+            Head::widget()->content('test content')->render(),
+        );
     }
 
-    public function testElement(): void
+    public function testDataAttributes(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head>
-            test element
+            <head data-value="value">
             </head>
             HTML,
-            Head::widget()->content('test element')->render(),
+            Head::widget()->dataAttributes(['value' => 'value'])->render(),
         );
     }
 
     public function testId(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head id="test-id">
+            <head id="value">
             </head>
             HTML,
-            Head::widget()->id('test-id')->render(),
+            Head::widget()->id('value')->render(),
         );
     }
 
     public function testLang(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head lang="en">
+            <head lang="value">
             </head>
             HTML,
-            Head::widget()->lang('en')->render(),
+            Head::widget()->lang('value')->render(),
         );
     }
 
     public function testName(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head name="test-name">
+            <head name="value">
             </head>
             HTML,
-            Head::widget()->name('test-name')->render(),
+            Head::widget()->name('value')->render(),
         );
     }
 
     public function testStyle(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head style="color: red;">
+            <head style="value">
             </head>
             HTML,
-            Head::widget()->style('color: red;')->render(),
+            Head::widget()->style('value')->render(),
         );
     }
 
     public function testTitle(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <head title="test-title">
+            <head title="value">
             </head>
             HTML,
-            Head::widget()->title('test-title')->render(),
+            Head::widget()->title('value')->render(),
         );
     }
 

diff --git a/tests/Head/CustomMethodTest.php b/tests/Head/CustomMethodTest.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Head;
+
+use PHPForge\Html\Head;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class CustomMethodTest extends TestCase
+{
+    public function testBeginEnd(): void
+    {
+        $this->assertSame('<head>value</head>', Head::widget()->begin() . 'value' . Head::end());
+    }
+
+    public function testRender(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <head>
+            </head>
+            HTML,
+            Head::widget()->render(),
+        );
+    }
+}