Add support for null value, add docs for Telephone widget (#128)

yiisoft · Oct 27, 2021 · 8a4bc2a · 8a4bc2a
1 parent 7c51529
commit 8a4bc2a
Show file tree

Hide file tree

Showing 6 changed files with 147 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -134,11 +134,12 @@ The following documentation describes how to use widgets with PHP:
 - [DateTimeLocal](docs/datetimelocal.md)
 - [Email](docs/email.md)
 - [File](docs/file.md)
-- [Password](docs/password.md)
 - [Number](docs/number.md)
+- [Password](docs/password.md)
 - [Radio](docs/radio.md)
 - [RadioList](docs/radiolist.md)
 - [Range](docs/range.md)
+- [Telephone](docs/telephone.md)
 - [Url](docs/url.md)
 
 ### Unit testing

diff --git a/docs/telephone.md b/docs/telephone.md
@@ -0,0 +1,82 @@
+# Telephone widget
+
+[Telephone](https://www.w3.org/TR/2012/WD-html-markup-20120329/input.tel.html#input.tel) represents a one-line plain-text edit control for entering a telephone number.
+
+## Usage
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Form;
+
+use Yiisoft\Form\FormModel;
+
+final class TestForm extends FormModel
+{
+    private string $phoneNumber = '';
+}
+```
+
+Widget view:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Yiisoft\Form\FormModelInterface;
+use Yiisoft\Form\Widget\Field;
+use Yiisoft\Form\Widget\Form;
+use Yiisoft\Form\Widget\Telephone;
+
+/**
+ * @var FormModelInterface $data
+ * @var object $csrf
+ */
+?>
+
+<?= Form::widget()->action('widgets')->csrf($csrf)->begin(); ?>
+    <?= Telephone::widget()->config($data, 'phoneNumber')->render(); ?>
+    <hr class="mt-3">
+    <?= Field::widget()->submitButton(['class' => 'button is-block is-info is-fullwidth', 'value' => 'Save']); ?>
+<?= Form::end(); ?>
+```
+
+That would generate the following code:
+
+```html
+<form action="widgets" method="POST" novalidate="" _csrf="en29GwyIKyFYUSq5NXy1I1hicrGmoFLHnvKOYvVxyEceEMxJPuRoQGwgE_1qEcURAhEZnJ_rPrSun9oqrAKlCw==">
+    <input type="hidden" name="_csrf" value="en29GwyIKyFYUSq5NXy1I1hicrGmoFLHnvKOYvVxyEceEMxJPuRoQGwgE_1qEcURAhEZnJ_rPrSun9oqrAKlCw==">
+    <input type="tel" id="testform-phonenumber" name="TestForm[phoneNumber]">
+    <hr class="mt-3">
+    <div>
+        <input type="submit" id="submit-63977381274001" class="button is-block is-info is-fullwidth" name="submit-63977381274001" value="Save">
+    </div>
+</form>
+```
+
+### `Telephone` methods:
+
+Method | Description | Default
+-------|-------------|---------
+`maxlength(int $value)` | Sets the maximum number of characters the user can enter. | `null`
+`minlength(int $value)` | Sets the minimum number of characters the user can enter. | `null`
+`pattern(string $value)` | Sets the regular expression pattern the user's input must match. | `null`
+`placeholder(string $value)` | Sets the placeholder text to be displayed in the input. | `null`
+`size(int $value)` | Sets the height of the input. | `null`
+
+### `Common` methods:
+
+Method | Description | Default
+-------|-------------|---------
+`autofocus(bool $value = true)` | Sets the autofocus attribute | `false`
+`charset(string $value)` | Sets the charset attribute | `UTF-8`
+`config(FormModelInterface $formModel, string $attribute, array $attributes = [])` | Configures the widget. |
+`disabled(bool $value = true)` | Sets the disabled attribute | `false`
+`form(string $value)` | Sets the form attribute | `''`
+`id(string $value)` | Sets the id attribute | `''`
+`readonly()` | Sets the readonly attribute | `false`
+`required(bool $value = true)` | Sets the required attribute | `false`
+`tabIndex(int $value = 0)` | Sets the tabindex attribute | `0`
diff --git a/src/Widget/Telephone.php b/src/Widget/Telephone.php
@@ -95,7 +95,7 @@ public function placeholder(string $value): self
     }
 
     /**
-     * The height of the <select> with multiple is true.
+     * The height of the text input.
      *
      * Default value is 4.
      *
@@ -124,16 +124,16 @@ protected function run(): string
          */
         $value = HtmlForm::getAttributeValue($new->getFormModel(), $new->attribute);
 
-        if (!is_string($value)) {
-            throw new InvalidArgumentException('Telephone widget must be a string.');
+        if (!is_string($value) && null !== $value) {
+            throw new InvalidArgumentException('Telephone widget must be a string o null value.');
         }
 
         return Input::tag()
             ->type('tel')
             ->attributes($new->attributes)
             ->id($new->getId())
             ->name(HtmlForm::getInputName($new->getFormModel(), $new->attribute))
-            ->value($value)
+            ->value($value === '' ? null : $value)
             ->render();
     }
 }
diff --git a/tests/Widget/FieldTelephoneTest.php b/tests/Widget/FieldTelephoneTest.php
@@ -23,7 +23,7 @@ public function testMaxLength(): void
         $expected = <<<'HTML'
         <div>
         <label for="typeform-string">String</label>
-        <input type="tel" id="typeform-string" name="TypeForm[string]" value maxlength="10" placeholder="Typed your text string.">
+        <input type="tel" id="typeform-string" name="TypeForm[string]" maxlength="10" placeholder="Typed your text string.">
         <div>Write your text string.</div>
         </div>
         HTML;
@@ -38,7 +38,7 @@ public function testMinLength(): void
         $expected = <<<'HTML'
         <div>
         <label for="typeform-string">String</label>
-        <input type="tel" id="typeform-string" name="TypeForm[string]" value minlength="4" placeholder="Typed your text string.">
+        <input type="tel" id="typeform-string" name="TypeForm[string]" minlength="4" placeholder="Typed your text string.">
         <div>Write your text string.</div>
         </div>
         HTML;
@@ -53,7 +53,7 @@ public function testPattern(): void
         $expected = <<<'HTML'
         <div>
         <label for="typeform-string">String</label>
-        <input type="tel" id="typeform-string" name="TypeForm[string]" value pattern="[789][0-9]{9}" placeholder="Typed your text string.">
+        <input type="tel" id="typeform-string" name="TypeForm[string]" pattern="[789][0-9]{9}" placeholder="Typed your text string.">
         <div>Write your text string.</div>
         </div>
         HTML;
@@ -68,7 +68,7 @@ public function testPlaceholder(): void
         $expected = <<<'HTML'
         <div>
         <label for="typeform-string">String</label>
-        <input type="tel" id="typeform-string" name="TypeForm[string]" value placeholder="PlaceHolder Text">
+        <input type="tel" id="typeform-string" name="TypeForm[string]" placeholder="PlaceHolder Text">
         <div>Write your text string.</div>
         </div>
         HTML;
@@ -84,7 +84,36 @@ public function testRender(): void
         $expected = <<<'HTML'
         <div>
         <label for="typeform-string">String</label>
-        <input type="tel" id="typeform-string" name="TypeForm[string]" value placeholder="Typed your text string.">
+        <input type="tel" id="typeform-string" name="TypeForm[string]" placeholder="Typed your text string.">
+        <div>Write your text string.</div>
+        </div>
+        HTML;
+        $this->assertEqualsWithoutLE(
+            $expected,
+            Field::widget()->config($this->formModel, 'string')->telephone()->render(),
+        );
+    }
+
+    public function testValue(): void
+    {
+        // value null
+        $expected = <<<'HTML'
+        <div>
+        <label for="typeform-tonull">To Null</label>
+        <input type="tel" id="typeform-tonull" name="TypeForm[toNull]">
+        </div>
+        HTML;
+        $this->assertEqualsWithoutLE(
+            $expected,
+            Field::widget()->config($this->formModel, 'toNull')->telephone()->render(),
+        );
+
+        // value telephone number string '+71234567890'
+        $this->formModel->setAttribute('string', '+71234567890');
+        $expected = <<<'HTML'
+        <div>
+        <label for="typeform-string">String</label>
+        <input type="tel" id="typeform-string" name="TypeForm[string]" value="+71234567890" placeholder="Typed your text string.">
         <div>Write your text string.</div>
         </div>
         HTML;
@@ -97,7 +126,7 @@ public function testRender(): void
     public function testValueException(): void
     {
         $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('Telephone widget must be a string.');
+        $this->expectExceptionMessage('Telephone widget must be a string o null value.');
         Field::widget()->config($this->formModel, 'int')->telephone()->render();
     }
 

diff --git a/tests/Widget/FieldTest.php b/tests/Widget/FieldTest.php
@@ -310,7 +310,7 @@ public function testAddAttributesTelephoneValidator(): void
         $expected = <<<'HTML'
         <div>
         <label for="attributesvalidatorform-telephone">Telephone</label>
-        <input type="tel" id="attributesvalidatorform-telephone" class="is-invalid" name="AttributesValidatorForm[telephone]" value maxlength="16" minlength="8" required pattern="[^0-9+\(\)-]">
+        <input type="tel" id="attributesvalidatorform-telephone" class="is-invalid" name="AttributesValidatorForm[telephone]" maxlength="16" minlength="8" required pattern="[^0-9+\(\)-]">
         <div class="hasError">Value cannot be blank.</div>
         </div>
         HTML;

diff --git a/tests/Widget/TelephoneTest.php b/tests/Widget/TelephoneTest.php
@@ -28,55 +28,71 @@ public function testImmutability(): void
     public function testMaxLength(): void
     {
         $this->assertSame(
-            '<input type="tel" id="typeform-string" name="TypeForm[string]" value maxlength="10">',
+            '<input type="tel" id="typeform-string" name="TypeForm[string]" maxlength="10">',
             Telephone::widget()->config($this->formModel, 'string')->maxlength(10)->render(),
         );
     }
 
     public function testMinLength(): void
     {
         $this->assertSame(
-            '<input type="tel" id="typeform-string" name="TypeForm[string]" value minlength="4">',
+            '<input type="tel" id="typeform-string" name="TypeForm[string]" minlength="4">',
             Telephone::widget()->config($this->formModel, 'string')->minlength(4)->render(),
         );
     }
 
     public function testPattern(): void
     {
         $this->assertSame(
-            '<input type="tel" id="typeform-string" name="TypeForm[string]" value pattern="[789][0-9]{9}">',
+            '<input type="tel" id="typeform-string" name="TypeForm[string]" pattern="[789][0-9]{9}">',
             Telephone::widget()->config($this->formModel, 'string')->pattern('[789][0-9]{9}')->render(),
         );
     }
 
     public function testPlaceholder(): void
     {
         $this->assertSame(
-            '<input type="tel" id="typeform-string" name="TypeForm[string]" value placeholder="PlaceHolder Text">',
+            '<input type="tel" id="typeform-string" name="TypeForm[string]" placeholder="PlaceHolder Text">',
             Telephone::widget()->config($this->formModel, 'string')->placeholder('PlaceHolder Text')->render(),
         );
     }
 
     public function testRender(): void
     {
         $this->assertSame(
-            '<input type="tel" id="typeform-string" name="TypeForm[string]" value>',
+            '<input type="tel" id="typeform-string" name="TypeForm[string]">',
             Telephone::widget()->config($this->formModel, 'string')->render(),
         );
     }
 
     public function testSize(): void
     {
         $this->assertSame(
-            '<input type="tel" id="typeform-string" name="TypeForm[string]" value size="20">',
+            '<input type="tel" id="typeform-string" name="TypeForm[string]" size="20">',
             Telephone::widget()->config($this->formModel, 'string')->size(20)->render(),
         );
     }
 
+    public function testValue(): void
+    {
+        // value null
+        $this->assertSame(
+            '<input type="tel" id="typeform-tonull" name="TypeForm[toNull]">',
+            Telephone::widget()->config($this->formModel, 'toNull')->render(),
+        );
+
+        // value telephone number string '+71234567890'
+        $this->formModel->setAttribute('string', '+71234567890');
+        $this->assertSame(
+            '<input type="tel" id="typeform-string" name="TypeForm[string]" value="+71234567890">',
+            Telephone::widget()->config($this->formModel, 'string')->render(),
+        );
+    }
+
     public function testValueException(): void
     {
         $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('Telephone widget must be a string.');
+        $this->expectExceptionMessage('Telephone widget must be a string o null value.');
         Telephone::widget()->config($this->formModel, 'int')->render();
     }