Add docs Img::class. (#274)

php-forge · Feb 6, 2024 · 2a1e2f9 · 2a1e2f9
1 parent 1a49ddf
commit 2a1e2f9
Show file tree

Hide file tree

Showing 12 changed files with 511 additions and 28 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -22,6 +22,7 @@ The following tags are currently supported:
 - [header](/docs/tag/Header.md)
 - [html](/docs/tag/Html.md)
 - [i](/docs/tag/I.md)
+- [img](/docs/tag/Img.md)
 
 ## Input Tags
 

diff --git a/docs/tag/Img.md b/docs/tag/Img.md
@@ -0,0 +1,141 @@
+# Img
+
+The `<img>` `HTML` element embeds an image into the document.
+
+## Basic Usage
+
+Instantiate the `Img` class using `Img::widget()`.
+
+```php
+$img = Img::widget();
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$img->class('external');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$img->attributes(['class' => 'external', 'title' => 'External Link']);
+```
+
+## Adding source
+
+If you want to include an image, use the `src` method.
+
+```php
+$img->src('https://example.com/image.jpg');
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method.
+
+```php
+$html = $img->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $img;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$img->class('external')->title('External Link');
+
+// using data attributes
+$img->dataAttributes(['bs-toggle' => 'modal', 'bs-target' => '#exampleModal', 'analytics' => 'trackClick']);
+```
+
+Explore additional methods for setting various attributes such as `crossorigin`, `ismap`, `lang`, `loading`, `tabindex`,
+`title`, and more.
+
+## Prefix and Suffix
+
+Use `prefix` and `suffix` methods to add text before and after the `img` tag, respectively.
+
+```php
+// adding a prefix
+$html = $img->src('https://example.com/image.jpg')->prefix('prev')->render();
+
+// adding a suffix
+$html = $img->src('https://example.com/image.jpg')->suffix('Next')->render();
+```
+
+## Template
+
+The `template` method allows you to customize the `HTML` output of the a element.
+
+The following template tags are available:
+
+| Tag        | Description      |
+| ---------- | ---------------- |
+| `{prefix}` | The prefix text. |
+| `{tag}`    | The a element.   |
+| `{suffix}` | The suffix text. |
+
+```php
+// using a custom template
+$img->template('<span>{tag}</span>');
+```
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Img/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.                                                                       |
+| `crossorigin()`   | Set the `crossorigin` attribute.                                                                 |
+| `dataAttributes()`| Set multiple `data-attributes` at once.                                                          |
+| `height()`        | Set the `height` attribute.                                                                      |
+| `id()`            | Set the `id` attribute.                                                                          |
+| `ismap()`         | Set the `ismap` attribute.                                                                       |
+| `lang()`          | Set the `lang` attribute.                                                                        |
+| `loading()`       | Set the `loading` attribute.                                                                     |
+| `name()`          | Set the `name` attribute.                                                                        |
+| `sizes()`         | Set the `sizes` attribute.                                                                       |
+| `src()`           | Set the `src` attribute.                                                                         |
+| `srcset()`        | Set the `srcset` attribute.                                                                      |
+| `style()`         | Set the `style` attribute.                                                                       |
+| `title()`         | Set the `title` attribute.                                                                       |
+| `width()`         | Set the `width` attribute.                                                                       |
+
+## Custom methods
+
+Refer to the [Custom Method Test](https://github.com/php-forge/html/blob/main/tests/Img/CustomMethodTest.php) for 
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method                       | Description                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `prefix()`                   | Add text before the `img` element.                                                    |
+| `prefixContainer()`          | Set enabled or disabled for the `prefix-container` element.                           |
+| `prefixContainerAttributes()`| Set `attributes` for the `prefix-container` element.                                  |                                            
+| `prefixContainerClass()`     | Set the `class` attribute for the `prefix-container` element.                         |
+| `prefixContainerTag()`       | Set the `tag` for the `prefix-container` element.                                     |
+| `render()`                   | Generates the `HTML` output.                                                          |
+| `suffix()`                   | Add text after the `img` element.                                                     |
+| `suffixContainer()`          | Set enabled or disabled for the `suffix-container` element.                           |
+| `suffixContainerAttributes()`| Set `attributes` for the `suffix-container` element.                                  |
+| `suffixContainerClass()`     | Set the `class` attribute for the `suffix-container` element.                         |
+| `suffixContainerTag()`       | Set the `tag` for the `suffix-container` element.                                     |
+| `template()`                 | Set the `template` for the `img` element.                                             |
+| `widget()`                   | Instantiates the `Img::class`.                                                        |
diff --git a/src/A.php b/src/A.php
@@ -19,6 +19,7 @@ final class A extends Base\AbstractElement
     use Attribute\Aria\HasRole;
     use Attribute\CanBeAutofocus;
     use Attribute\CanBeHidden;
+    use Attribute\Custom\HasContent;
     use Attribute\HasTabindex;
     use Attribute\Input\HasType;
     use Attribute\Tag\HasDownload;
@@ -31,6 +32,6 @@ final class A extends Base\AbstractElement
 
     protected function run(): string
     {
-        return $this->buildElement('a');
+        return $this->buildElement('a', $this->content);
     }
 }
diff --git a/src/Base/AbstractElement.php b/src/Base/AbstractElement.php
@@ -14,7 +14,6 @@
 abstract class AbstractElement extends Element
 {
     use Attribute\Custom\HasAttributes;
-    use Attribute\Custom\HasContent;
     use Attribute\Custom\HasPrefixAndSuffix;
     use Attribute\Custom\HasTemplate;
     use Attribute\HasClass;
@@ -41,18 +40,19 @@ protected function loadDefaultDefinitions(): array
      * Generate the HTML representation of the element.
      *
      * @param string $tagName The tag name of the element.
+     * @param string $content The content of the element.
      * @param array $tokenValues The token values to be used in the template.
      *
      * @return string The HTML representation of the element.
      */
-    protected function buildElement(string $tagName, array $tokenValues = []): string
+    protected function buildElement(string $tagName, string $content = '', array $tokenValues = []): string
     {
         $attributes = $this->attributes;
         $attributes['id'] ??= $this->id;
 
         $tokenTemplateValues = [
             '{prefix}' => $this->renderPrefixTag(),
-            '{tag}' => HtmlBuilder::create($tagName, $this->content, $attributes),
+            '{tag}' => HtmlBuilder::create($tagName, $content, $attributes),
             '{suffix}' => $this->renderSuffixTag(),
         ];
         $tokenTemplateValues += $tokenValues;

diff --git a/src/I.php b/src/I.php
@@ -12,8 +12,10 @@
  */
 final class I extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
+
     protected function run(): string
     {
-        return $this->buildElement('i');
+        return $this->buildElement('i', $this->content);
     }
 }
diff --git a/src/Label.php b/src/Label.php
@@ -11,11 +11,12 @@
  */
 final class Label extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
     use Attribute\Input\HasForm;
     use Attribute\Tag\HasFor;
 
     protected function run(): string
     {
-        return $this->buildElement('label');
+        return $this->buildElement('label', $this->content);
     }
 }
diff --git a/src/Span.php b/src/Span.php
@@ -16,8 +16,10 @@
  */
 final class Span extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
+
     protected function run(): string
     {
-        return $this->buildElement('span');
+        return $this->buildElement('span', $this->content);
     }
 }
diff --git a/src/Tag.php b/src/Tag.php
@@ -18,6 +18,7 @@
  */
 final class Tag extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
     use Attribute\Custom\HasTagName;
     use Attribute\Custom\HasTokenValues;
     use Attribute\HasTabindex;
@@ -26,6 +27,6 @@ final class Tag extends Base\AbstractElement
 
     protected function run(): string
     {
-        return $this->buildElement($this->tagName, $this->tokenValues);
+        return $this->buildElement($this->tagName, $this->content, $this->tokenValues);
     }
 }
diff --git a/src/TextArea.php b/src/TextArea.php
@@ -20,6 +20,7 @@ final class TextArea extends Base\AbstractElement implements
     Contract\RequiredInterface
 {
     use Attribute\CanBeAutofocus;
+    use Attribute\Custom\HasContent;
     use Attribute\HasTabindex;
     use Attribute\Input\CanBeDisabled;
     use Attribute\Input\CanBeReadonly;
@@ -47,6 +48,6 @@ protected function loadDefaultDefinitions(): array
 
     protected function run(): string
     {
-        return $this->buildElement('textarea');
+        return $this->buildElement('textarea', $this->content);
     }
 }