Add support for null value, add docs for Date widget (#116)

yiisoft · Oct 26, 2021 · 7674c64 · 7674c64
1 parent 9bf095b
commit 7674c64
Show file tree

Hide file tree

Showing 5 changed files with 108 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -129,6 +129,7 @@ The following documentation describes how to use widgets with PHP:
 
 - [Checkbox](docs/checkbox.md)
 - [CheckboxList](docs/checkboxlist.md)
+- [Date](docs/date.md)
 - [DateTime](docs/datetime.md)
 - [DateTimeLocal](docs/datetimelocal.md)
 - [Radio](docs/radio.md)

diff --git a/docs/date.md b/docs/date.md
@@ -0,0 +1,74 @@
+# Date widget
+
+[Date](https://www.w3.org/TR/2012/WD-html-markup-20120329/input.date.html#input.date) an input element for setting the element’s value to a string representing a date.
+
+## Usage
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Form;
+
+use Yiisoft\Form\FormModel;
+
+final class TestForm extends FormModel
+{
+    public string $dateOfBirth = '';
+}
+```
+
+Widget view:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Yiisoft\Form\FormModelInterface;
+use Yiisoft\Form\Widget\Date;
+use Yiisoft\Form\Widget\Field;
+use Yiisoft\Form\Widget\Form;
+
+/**
+ * @var FormModelInterface $data
+ * @var object $csrf
+ */
+?>
+
+<?= Form::widget()->action('widgets')->csrf($csrf)->begin(); ?>
+    <?= Date::widget()->config($data, 'dateOfBirth')->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" _csrf="-6rn3MlbGj1vvxDof0sbRjowkrdEAkIbjCzsLYUp77WU5pWe-wxdfBvWZ9oaeCwiWHHc3xJ1KS-7a9xB7ECl-Q==">
+    <input type="hidden" name="_csrf" value="-6rn3MlbGj1vvxDof0sbRjowkrdEAkIbjCzsLYUp77WU5pWe-wxdfBvWZ9oaeCwiWHHc3xJ1KS-7a9xB7ECl-Q==">
+    <input type="date" id="testform-dateofbirth" name="TestForm[dateOfBirth]">
+    <hr class="mt-3">
+    <div>
+        <input type="submit" id="submit-88924893586001" class="button is-block is-info is-fullwidth" name="submit-88924893586001" value="Save">
+    </div>
+</form>
+```
+
+### `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 | `''`
+`min(?string $value)` | The earliest acceptable date | `''`
+`max(?string $value)` | The latest acceptable date | `''`
+`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/Date.php b/src/Widget/Date.php
@@ -36,16 +36,16 @@ protected function run(): string
         /** @link https://www.w3.org/TR/2012/WD-html-markup-20120329/input.date.html#input.date.attrs.value */
         $value = HtmlForm::getAttributeValue($new->getFormModel(), $new->attribute);
 
-        if (!is_string($value)) {
-            throw new InvalidArgumentException('Date widget requires a string value.');
+        if (!is_string($value) && null !== $value) {
+            throw new InvalidArgumentException('Date widget requires a string or null value.');
         }
 
         return Input::tag()
             ->type('date')
             ->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/DateTest.php b/tests/Widget/DateTest.php
@@ -18,26 +18,33 @@ final class DateTest extends TestCase
     public function testRender(): void
     {
         $this->assertSame(
-            '<input type="date" id="typeform-string" name="TypeForm[string]" value>',
-            Date::widget()->config($this->formModel, 'string')->render(),
+            '<input type="date" id="typeform-todate" name="TypeForm[toDate]">',
+            Date::widget()->config($this->formModel, 'toDate')->render(),
         );
     }
 
     public function testValue(): void
     {
         // string '2021-09-18'
-        $this->formModel->setAttribute('string', '2021-09-18');
+        $this->formModel->setAttribute('toDate', '2021-09-18');
         $this->assertSame(
-            '<input type="date" id="typeform-string" name="TypeForm[string]" value="2021-09-18">',
-            Date::widget()->config($this->formModel, 'string')->render(),
+            '<input type="date" id="typeform-todate" name="TypeForm[toDate]" value="2021-09-18">',
+            Date::widget()->config($this->formModel, 'toDate')->render(),
+        );
+
+        // value null
+        $this->formModel->setAttribute('toDate', null);
+        $this->assertSame(
+            '<input type="date" id="typeform-todate" name="TypeForm[toDate]">',
+            Date::widget()->config($this->formModel, 'toDate')->render(),
         );
     }
 
     public function testValueException(): void
     {
         $this->formModel->setAttribute('array', []);
         $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('Date widget requires a string value.');
+        $this->expectExceptionMessage('Date widget requires a string or null value.');
         Date::widget()->config($this->formModel, 'array')->render();
     }
 

diff --git a/tests/Widget/FieldDateTest.php b/tests/Widget/FieldDateTest.php
@@ -23,7 +23,7 @@ public function testRender(): void
         $expected = <<<HTML
         <div>
         <label for="typeform-todate">To Date</label>
-        <input type="date" id="typeform-todate" name="TypeForm[toDate]" value>
+        <input type="date" id="typeform-todate" name="TypeForm[toDate]">
         </div>
         HTML;
         $this->assertEqualsWithoutLE(
@@ -35,13 +35,26 @@ public function testRender(): void
     public function testValue(): void
     {
         // string '2021-09-18'
+        $this->formModel->setAttribute('toDate', '2021-09-18');
         $expected = <<<HTML
         <div>
         <label for="typeform-todate">To Date</label>
-        <input type="date" id="typeform-todate" name="TypeForm[toDate]" value>
+        <input type="date" id="typeform-todate" name="TypeForm[toDate]" value="2021-09-18">
+        </div>
+        HTML;
+        $this->assertEqualsWithoutLE(
+            $expected,
+            Field::widget()->config($this->formModel, 'toDate')->date()->render(),
+        );
+
+        // value null
+        $this->formModel->setAttribute('toDate', null);
+        $expected = <<<HTML
+        <div>
+        <label for="typeform-todate">To Date</label>
+        <input type="date" id="typeform-todate" name="TypeForm[toDate]">
         </div>
         HTML;
-        $this->formModel->setAttribute('string', '2021-09-18');
         $this->assertEqualsWithoutLE(
             $expected,
             Field::widget()->config($this->formModel, 'toDate')->date()->render(),
@@ -51,7 +64,7 @@ public function testValue(): void
     public function testValueException(): void
     {
         $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('Date widget requires a string value.');
+        $this->expectExceptionMessage('Date widget requires a string or null value.');
         Field::widget()->config($this->formModel, 'array')->date()->render();
     }