Add docs Url::class. (#292)

php-forge · Feb 15, 2024 · 0ad1808 · 0ad1808
1 parent 32c001a
commit 0ad1808
Show file tree

Hide file tree

Showing 6 changed files with 250 additions and 52 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -50,6 +50,7 @@ In addition to basic `HTML` tags, the repository also supports the generation of
 This is particularly useful for creating forms and other interactive elements on a webpage.
 
 - [text](/docs/form/input/Text.md)
+- [url](/docs/form/input/Url.md)
 - [week](/docs/form/input/Week.md)
 
 ## Creating Widgets

diff --git a/docs/form/input/Url.md b/docs/form/input/Url.md
@@ -0,0 +1,172 @@
+# Url
+
+The input element with a type attribute whose value is `url` represents a control for editing an absolute URL given
+in the element’s value.
+
+## Basic Usage
+
+Instantiate the `Url` class using `Url::widget()`.
+
+```php
+$url = Url::widget();
+```
+
+## Generate field id and name
+
+The `generateField` method is used to generate the field id and name for the `HTML` output.
+
+Allowed arguments are:
+
+- `modelName` - The name of the model.
+- `fieldName` - The name of the field.
+- `arrayable` - Whether the field is an array. For default, it is `false`.
+
+```php
+// generate field id and name
+$url->generateField('model', 'field');
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$url->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$url->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding value
+
+If you want to include value in the `url` element, use the `value` method.
+
+```php
+$url->value('MyValue');
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $url->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $url;
+```
+
+## Common use cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$url->class('external')->value('Myvalue');
+
+// using data attributes
+$url->dataAttributes(['analytics' => 'trackClick']);
+```
+
+Explore additional methods for setting various attributes such as `lang`, `name`, `style`, `title`, etc.
+
+## Prefix and Suffix
+
+Use `prefix` and `suffix` methods to add text before and after the `url` tag, respectively.
+
+```php
+// adding a prefix
+$html = $url->content('MyContent')->prefix('MyPrefix')->render();
+
+// adding a suffix
+$html = $url->content('MyContent')->suffix('MySuffix')->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
+$url->template('<div>{tag}</div>');
+```
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Input/Url/AttributeTest.php) for 
+comprehensive examples.
+
+The following methods are available for setting attributes:
+
+| Method             | Description                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `ariaDescribedBy()`| Set the `aria-describedby` attribute.                                                           |
+| `ariaLabel()`      | Set the `aria-label` attribute.                                                                 |
+| `attributes()`     | Set multiple `attributes` at once.                                                              |
+| `autofocus()`      | Set the `autofocus` attribute.                                                                  |
+| `class()`          | Set the `class` attribute.                                                                      |
+| `dataAttributes()` | Set multiple `data-attributes` at once.                                                         |
+| `disabled()`       | Set the `disabled` attribute.                                                                   |
+| `form()`           | Set the `form` attribute.                                                                       |
+| `hidden()`         | Set the `hidden` attribute.                                                                     |
+| `id()`             | Set the `id` attribute.                                                                         |
+| `lang()`           | Set the `lang` attribute.                                                                       |
+| `name()`           | Set the `name` attribute.                                                                       |
+| `placeholder()`    | Set the `placeholder` attribute.                                                                |
+| `readOnly()`       | Set the `readonly` attribute.                                                                   |
+| `size()`           | Set the `size` attribute.                                                                       |
+| `style()`          | Set the `style` attribute.                                                                      |
+| `tabIndex()`       | Set the `tabindex` attribute.                                                                   |
+| `title()`          | Set the `title` attribute.                                                                      |
+| `value()`          | Set the `value` attribute.                                                                      |
+
+## Custom methods
+
+Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/Input/Url/CustomMethodTest.php)
+for comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method                       | Description                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `generateField()`           | Generate the field id and name for the `HTML` output.                                  |
+| `prefix()`                   | Add text before the `textarea` 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 `label` 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 `HTML` output.                                               |
+| `widget()`                   | Instantiates the `Url::class`.                                                       |
+
+## Validate methods
+
+Refer to the [Validate Tests](https://github.com/php-forge/html/blob/main/tests/Input/Url/ValidateTest.php) for
+comprehensive examples.
+
+| Method         | Description                                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------- |
+| `maxLength()`  | Set the `maxlength` attribute.                                                                      |
+| `minLength()`  | Set the `minlength` attribute.                                                                      |
+| `pattern()`    | Set the `pattern` attribute.                                                                        |
+| `required()`   | Set the `required` attribute.                                                                       |
diff --git a/docs/form/input/Week.md b/docs/form/input/Week.md
@@ -43,7 +43,7 @@ $week->attributes(['class' => 'container', 'style' => 'background-color: #eee;']
 
 ## Adding value
 
-If you want to include value in the `text` element, use the `value` method.
+If you want to include value in the `week` element, use the `value` method.
 
 ```php
 $week->value('MyValue');
@@ -79,7 +79,7 @@ Explore additional methods for setting various attributes such as `lang`, `name`
 
 ## Prefix and Suffix
 
-Use `prefix` and `suffix` methods to add text before and after the `text` tag, respectively.
+Use `prefix` and `suffix` methods to add text before and after the `week` tag, respectively.
 
 ```php
 // adding a prefix

diff --git a/tests/Input/Url/AttributeTest.php b/tests/Input/Url/AttributeTest.php
@@ -153,26 +153,6 @@ public function testLang(): void
         );
     }
 
-    public function testMaxLength(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="url-6582f2d099e8b" type="url" maxlength="1">
-            HTML,
-            Url::widget()->id('url-6582f2d099e8b')->maxlength(1)->render()
-        );
-    }
-
-    public function testMinLength(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="url-6582f2d099e8b" type="url" minlength="1">
-            HTML,
-            Url::widget()->id('url-6582f2d099e8b')->minlength(1)->render()
-        );
-    }
-
     public function testName(): void
     {
         Assert::equalsWithoutLE(
@@ -183,16 +163,6 @@ public function testName(): void
         );
     }
 
-    public function testPattern(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="url-6582f2d099e8b" type="url" pattern="value">
-            HTML,
-            Url::widget()->id('url-6582f2d099e8b')->pattern('value')->render()
-        );
-    }
-
     public function testPlaceholder(): void
     {
         Assert::equalsWithoutLE(
@@ -213,26 +183,6 @@ public function testReadonly(): void
         );
     }
 
-    public function testRender(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="url-6582f2d099e8b" type="url">
-            HTML,
-            Url::widget()->id('url-6582f2d099e8b')->render()
-        );
-    }
-
-    public function testRequired(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="url-6582f2d099e8b" type="url" required>
-            HTML,
-            Url::widget()->id('url-6582f2d099e8b')->required()->render()
-        );
-    }
-
     public function testSize(): void
     {
         Assert::equalsWithoutLE(

diff --git a/tests/Input/Url/CustomMethodTest.php b/tests/Input/Url/CustomMethodTest.php
@@ -13,6 +13,16 @@
  */
 final class CustomMethodTest extends TestCase
 {
+    public function testGenerateField(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="modelname-fieldname" name="ModelName[fieldName]" type="url">
+            HTML,
+            Url::widget()->generateField('ModelName', 'fieldName')->render()
+        );
+    }
+
     public function testPrefix(): void
     {
         Assert::equalsWithoutLE(
@@ -91,6 +101,16 @@ public function testPrefixContainerTag(): void
         );
     }
 
+    public function testRender(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="url-6582f2d099e8b" type="url">
+            HTML,
+            Url::widget()->id('url-6582f2d099e8b')->render()
+        );
+    }
+
     public function testSuffix(): void
     {
         Assert::equalsWithoutLE(

diff --git a/tests/Input/Url/ValidateTest.php b/tests/Input/Url/ValidateTest.php
@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Input\Url;
+
+use PHPForge\Html\Input\Url;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class ValidateTest extends TestCase
+{
+    public function testMaxLength(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="url-6582f2d099e8b" type="url" maxlength="1">
+            HTML,
+            Url::widget()->id('url-6582f2d099e8b')->maxlength(1)->render()
+        );
+    }
+
+    public function testMinLength(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="url-6582f2d099e8b" type="url" minlength="1">
+            HTML,
+            Url::widget()->id('url-6582f2d099e8b')->minlength(1)->render()
+        );
+    }
+
+    public function testPattern(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="url-6582f2d099e8b" type="url" pattern="value">
+            HTML,
+            Url::widget()->id('url-6582f2d099e8b')->pattern('value')->render()
+        );
+    }
+
+    public function testRequired(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="url-6582f2d099e8b" type="url" required>
+            HTML,
+            Url::widget()->id('url-6582f2d099e8b')->required()->render()
+        );
+    }
+}