Rename method, fix docblocks and order methods (#42)

yiisoft · Jul 28, 2021 · 2908312 · 2908312
1 parent 6d0312c
commit 2908312
Show file tree

Hide file tree

Showing 17 changed files with 475 additions and 454 deletions.
diff --git a/docs/menu.md b/docs/menu.md
@@ -101,7 +101,7 @@ Method | Description | Default
 -------|-------------|---------
 `id(string $value)` | Widget ID. | `''`
 `autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w`
-`withoutActivateItems()` | Disable activate items according to whether their currentPath. | `false`
+`deactivateItems()` | Disable active items according to their current path. | `false`
 `activateParents()` | Whether to activate parent menu items when one of the corresponding child menu items is active. | `true`
 `activeCssClass(string $value)` | The CSS class to be appended to the active menu item. | `is-active`
 `brand(string $value)` | Custom brand content. | `''`

diff --git a/docs/tabs.md b/docs/tabs.md
@@ -103,7 +103,7 @@ Method | Description | Default
 `options(array $value)` | HTML attributes for the widget container tag. | [`class` => `tabs`]
 `items(array $value)` | List of tab items. | `[]`
 `currentPath(string $value)` | Allows you to assign the current path of the URL from request controller. | ``
-`withoutActivateItems()` | Disable activate items according to whether their currentPath. | `false`
+`deactivateItems()` | Disable active items according to their current path. | `false`
 `withoutEncodeLabels()` | When tags Labels HTML should not be encoded. | `false`       |
 `size(string $value)` | Size of the tabs list. | `is-small`, `is-medium`, `is-large`
 `alignment(string $value)` | Alignment of the tabs list. | `''`

diff --git a/src/Breadcrumbs.php b/src/Breadcrumbs.php
@@ -37,24 +37,8 @@ final class Breadcrumbs extends Widget
     private array $options = [];
     private array $itemsOptions = [];
 
-    protected function run(): string
-    {
-        if (empty($this->items)) {
-            return '';
-        }
-
-        $this->buildOptions();
-
-        return
-            Html::openTag('nav', $this->options) . "\n" .
-                Html::openTag('ul', $this->itemsOptions) . "\n" .
-                    implode('', $this->renderItems()) .
-                Html::closeTag('ul') . "\n" .
-            Html::closeTag('nav');
-    }
-
     /**
-     * Disables encoding for labels.
+     * Disables encoding for labels and returns a new instance.
      *
      * @return self
      */
@@ -90,10 +74,10 @@ public function homeItem(?array $value): self
     }
 
     /**
-     * The template used to render each inactive item in the breadcrumbs. The token `{link}` will be replaced with the
-     * actual HTML link for each inactive item.
+     * Returns a new instance with the specified item template.
      *
-     * @param string $value
+     * @param string $value The template used to render each inactive item in the breadcrumbs.
+     * The token `{link}` will be replaced with the actual HTML link for each inactive item.
      *
      * @return self
      */
@@ -105,10 +89,10 @@ public function itemTemplate(string $value): self
     }
 
     /**
-     * The template used to render each active item in the breadcrumbs. The token `{link}` will be replaced with the
-     * actual HTML link for each active item.
+     * Returns a new instance with the specified active item template.
      *
-     * @param string $value
+     * @param string $value The template used to render each active item in the breadcrumbs.
+     * The token `{link}` will be replaced with the actual HTML link for each active item.
      *
      * @return self
      */
@@ -120,8 +104,10 @@ public function activeItemTemplate(string $value): self
     }
 
     /**
-     * List of items to appear in the breadcrumb. If this property is empty, the widget will not render anything. Each
-     * array element represents a single link in the breadcrumb with the following structure:
+     * Returns a new instance with the specified list of items.
+     *
+     * @param array $value List of items to appear in the breadcrumbs. If this property is empty, the widget will not
+     * render anything. Each array element represents a single item in the breadcrumbs with the following structure:
      *
      * ```php
      * [
@@ -131,8 +117,6 @@ public function activeItemTemplate(string $value): self
      * ]
      * ```
      *
-     * @param array $value
-     *
      * @return self
      */
     public function items(array $value): self
@@ -143,9 +127,9 @@ public function items(array $value): self
     }
 
     /**
-     * The HTML attributes for the widget container nav tag.
+     * Returns a new instance with the specified options.
      *
-     * @param array $value
+     * @param array $value The HTML attributes for the widget container nav tag.
      *
      * @return self
      *
@@ -159,9 +143,9 @@ public function options(array $value): self
     }
 
     /**
-     * The HTML attributes for the items widget.
+     * Returns a new instance with the specified item template.
      *
-     * @param array $value
+     * @param array $value The HTML attributes for the items widget.
      *
      * @return self
      *
@@ -174,6 +158,22 @@ public function itemsOptions(array $value): self
         return $new;
     }
 
+    protected function run(): string
+    {
+        if (empty($this->items)) {
+            return '';
+        }
+
+        $this->buildOptions();
+
+        return
+            Html::openTag('nav', $this->options) . "\n" .
+            Html::openTag('ul', $this->itemsOptions) . "\n" .
+            implode('', $this->renderItems()) .
+            Html::closeTag('ul') . "\n" .
+            Html::closeTag('nav');
+    }
+
     private function buildOptions(): void
     {
         if (!isset($this->options['id'])) {

diff --git a/src/Dropdown.php b/src/Dropdown.php
@@ -37,17 +37,10 @@ final class Dropdown extends Widget
     private array $linkOptions = ['aria-haspopup' => 'true', 'aria-expanded' => 'false'];
     private array $triggerOptions = [];
 
-    protected function run(): string
-    {
-        $this->buildOptions();
-
-        return $this->buildDropdown();
-    }
-
     /**
-     * Sets label for the dropdown button.
+     * Returns a new instance with the specified label for the dropdown button.
      *
-     * @param string $value
+     * @param string $value The label for the dropdown button.
      *
      * @return self
      */
@@ -59,9 +52,9 @@ public function buttonLabel(string $value): self
     }
 
     /**
-     * The HTML attributes for the dropdown button.
+     * Returns a new instance with the specified HTML attributes for the dropdown button.
      *
-     * @param array $value
+     * @param array $value The HTML attributes for the dropdown button.
      *
      * @return self
      *
@@ -75,9 +68,9 @@ public function buttonLabelOptions(array $value): self
     }
 
     /**
-     * Sets CSS class for dropdown divider.
+     * Returns a new instance with the specified CSS class for dropdown divider.
      *
-     * @param string $value
+     * @param string $value The CSS class for dropdown divider.
      *
      * @return self
      */
@@ -89,9 +82,9 @@ public function dividerClass(string $value): self
     }
 
     /**
-     * Sets CSS class for dropdown item.
+     * Returns a new instance with the specified CSS class for dropdown item.
      *
-     * @param string $value
+     * @param string $value The CSS class for dropdown item.
      *
      * @return self
      */
@@ -103,9 +96,9 @@ public function itemClass(string $value): self
     }
 
     /**
-     * Sets CSS class for dropdown items container.
+     * Returns a new instance with the specified CSS class for dropdown items container.
      *
-     * @param string $value
+     * @param string $value The CSS class for dropdown items container.
      *
      * @return self
      */
@@ -117,7 +110,7 @@ public function itemsClass(string $value): self
     }
 
     /**
-     * Disables encoding for labels.
+     * Disables encoding for labels and returns a new instance.
      *
      * @return self
      */
@@ -129,7 +122,7 @@ public function withoutEncodeLabels(): self
     }
 
     /**
-     * Disables enclosed by container dropdown.
+     * Disables enclosed by container dropdown and returns a new instance.
      *
      * @return self
      */
@@ -141,8 +134,10 @@ public function withoutEncloseByContainer(): self
     }
 
     /**
-     * List of menu items in the dropdown. Each array element can be either an HTML string, or an array representing a
-     * single menu with the following structure:
+     * Returns a new instance with the specified list of items.
+     *
+     * @param array $value List of menu items in the dropdown. Each array element can be either an HTML string,
+     * or an array representing a single menu with the following structure:
      *
      * - label: string, required, the label of the item link.
      * - encode: bool, optional, whether to HTML-encode item label.
@@ -155,8 +150,6 @@ public function withoutEncloseByContainer(): self
      *
      * To insert divider use `-`.
      *
-     * @param array $value
-     *
      * @return self
      */
     public function items(array $value): self
@@ -167,9 +160,9 @@ public function items(array $value): self
     }
 
     /**
-     * The HTML attributes for the widget container tag.
+     * Returns a new instance with the specified HTML attributes for the widget container tag.
      *
-     * @param array $value
+     * @param array $value The HTML attributes for the widget container tag.
      *
      * @return self
      *
@@ -183,9 +176,9 @@ public function options(array $value): self
     }
 
     /**
-     * The HTML attributes for the widget button tag.
+     * Returns a new instance with the specified HTML attributes for the widget button tag.
      *
-     * @param array $value
+     * @param array $value The HTML attributes for the widget button tag.
      *
      * @return self
      *
@@ -199,9 +192,9 @@ public function buttonOptions(array $value): self
     }
 
     /**
-     * The HTML attributes for the widget items.
+     * Returns a new instance with the specified HTML attributes for the widget items.
      *
-     * @param array $value
+     * @param array $value The HTML attributes for the widget items.
      *
      * @return self
      *
@@ -215,9 +208,9 @@ public function itemsOptions(array $value): self
     }
 
     /**
-     * The HTML attributes for the widget container trigger.
+     * Returns a new instance with the specified HTML attributes for the widget container trigger.
      *
-     * @param array $value
+     * @param array $value The HTML attributes for the widget container trigger.
      *
      * @return self
      *
@@ -230,6 +223,13 @@ public function triggerOptions(array $value): self
         return $new;
     }
 
+    protected function run(): string
+    {
+        $this->buildOptions();
+
+        return $this->buildDropdown();
+    }
+
     private function buildDropdown(): string
     {
         if ($this->encloseByContainer) {