Update docs (#54)

yiisoft · Dec 24, 2021 · 0d8993f · 0d8993f
1 parent ceaf36e
commit 0d8993f
Show file tree

Hide file tree

Showing 8 changed files with 284 additions and 182 deletions.
diff --git a/docs/breadcrumbs.md b/docs/breadcrumbs.md
@@ -57,10 +57,14 @@ The code above generates the following HTML:
 </nav>
 ```
 
+## Setters
+
+All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Breadcrumbs` class with the specified value.
+
 Method | Description | Default
 -------|-------------|---------
-`activeItemTemplate(string $value)`| Template used to render each active item in the breadcrumbs. | `<li class=\"is-active\"><a aria-current=\"page\">{icon}{label}</li>\n`
-`aria-label` | Defines a string value that labels the current element. | `breadcrumbs`
+`activeItemTemplate(string $value)`| Template used to render each active item in the breadcrumbs. | `<li class=\"is-active\"><a aria-current=\"page\">{link}</a></li>\n`
+`ariaLabel` | Defines a string value that labels the current element. | `breadcrumbs`
 `attributes(array $value)` | HTML attributes for the widget container nav tag. | `[]`
 `autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w`
 `encode()` | Enable/Disable encoding for labels. | `false`
@@ -70,7 +74,7 @@ Method | Description | Default
 `itemsAttributes(array $value)` | HTML attributes for the items widget. | `[]`
 `itemTemplate(string $value)` | Template used to render each inactive item in the breadcrumbs. | `<li>{icon}{link}</li>\n`
 
-Items structure is an array of the following structure:
+### Items structure is an array of the following structure:
 
 ```php
 [

diff --git a/docs/dropdown.md b/docs/dropdown.md
@@ -48,41 +48,71 @@ $this->setJsFiles($assetManager->getJsFiles());
 ?>
 ```
 
-HTML produced is like the following:
+The code above generates the following HTML:
 
 ```html
-<div id="w1-dropdown" class="dropdown">
+<div class="dropdown">
     <div class="dropdown-trigger">
-        <button class="button" aria-haspopup="true" aria-controls="dropdown-menu">
+        <button class="button" aria-haspopup="true" aria-controls="w1-dropdown">
             <span>Russian cities</span>
-            <span class="icon is-small">
-                <i class="fas fa-angle-down" aria-hidden="true"></i>
-            </span>
+            <span class="icon is-small"><i class>&#8595;</i></span>
         </button>
     </div>
-    <div class="dropdown-menu">
-        <a class="dropdown-item" href="#">San petesburgo</a>
-        <a class="dropdown-item" href="#">Moscu</a>
-        <a class="dropdown-item" href="#">Novosibirsk</a>
-        <div class="dropdown-divider"></div>
-        <a class="dropdown-item" href="#">Ekaterinburgo</a>
+    <div id="w1-dropdown" class="dropdown-menu">
+        <div class="dropdown-content">
+            <a class="dropdown-item" href="#">San petesburgo</a>
+            <a class="dropdown-item" href="#">Moscu</a>
+            <a class="dropdown-item" href="#">Novosibirsk</a>
+            <hr class="dropdown-divider">
+            <a class="dropdown-item" href="#">Ekaterinburgo</a>
+        </div>
     </div>
 </div>
 ```
 
+## Setters
+
+All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Dropdown` class with the specified value.
+
 Method | Description | Default
 -------|-------------|---------
-`id(string $value)` | Widget ID. | `''`
+`attributes(array $value)` | Sets the HTML attributes for the dropdown container. | `[]`
 `autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w`
-`buttonLabel(string $value)` | Set label button dropdown. | `''`
-`buttonLabelOptions(array $value)`| The HTML attributes for the button dropdown. | `[]`
-`buttonOptions(array $value)` | The HTML attributes for the widget button tag. | `[]`
-`dividerClass(string $value)` | Divider CSS class. | `dropdown-divider` 
-`itemClass(string $value)` | Item CSS class. | `dropdown-item`
-`itemsClass(string $value)` | Item container CSS class. | `dropdown-menu`
-`itemsOptions(array $value)` | HTML attributes for the widget items. | `[]`
-`withoutEncodeLabels()` | Disable encoding for labels. | `false`
-`withoutEncloseByContainer()` | Disable enclosed by container tag dropdown. | `false`
-`items(array $value)` | List of menu items in the dropdown. | `[]`
-`options(array $value)` | HTML attributes for the widget container tag. | `[]`
-`triggerOptions(array $value)` | HTML attributes for the widget container trigger. | `[]`
+`buttonAttributes(array $values)` | The HTML attributes for the dropdown button. | `[]`
+`buttonIconAttributes(array $values)` | The HTML attributes for the dropdown button icon. | `['class' => 'icon is-small']`
+`buttonIconCssClass(string $value)` | Set icon CSS class for the dropdown button. | `''`
+`buttonIconText(string $value)` | Set icon text for the dropdown button. | `'&#8595;'`
+`buttonLabel(string $value)` | Set label for the dropdown button. | `'Click Me'`
+`buttonLabelAttributes(array $values)` | The HTML attributes for the dropdown button label. | `[]`
+`dividerCssClass(string $value)` | Set CSS class for horizontal line separating dropdown items. | `'dropdown-divider'`
+`dropdownCssClass(string $value)` | Set CSS class for the dropdown container. | `'dropdown'`
+`dropdownContentCssClass(string $value)` | Set CSS class for dropdown content. | `'dropdown-content'`
+`dropdownItemActiveCssClass(string $value)` | Set CSS class for active dropdown item. | `'is-active'`
+`dropdownItemCssClass(string $value)` | Set CSS class for dropdown item. | `'dropdown-item'`
+`dropdownItemDisabledStyleCss(string $value)` | Set Style attributes for disabled dropdown item. | `'opacity:.65;pointer-events:none;'`
+`dropdownItemHeaderCssClass(string $value)` | Set CSS class for dropdown item header. | `'dropdown-header'`
+`dropdownMenuCssClass(string $value)` | Set CSS class for dropdown menu. | `'dropdown-menu'`
+`dropdownTriggerCssClass(string $value)` | Set CSS class for dropdown trigger. | `'dropdown-trigger'`
+`id(string $value)` | Set the ID of the dropdown. | `''`
+`items(array $value)` | Set the dropdown items. | `[]`
+`submenu(bool $value)` | Set whether the dropdown is a submenu. | `false`
+`submenuAttributes(array $values)` | The HTML attributes for the dropdown submenu. | `[]`
+`enclosedByContainer(bool $value = false)` | Whether the widget should be enclosed by a container. | `true`
+
+### Items structure is an array of the following structure:
+
+```php
+[
+    [
+        'label' => '',
+        'url' => '',
+        'urlAttributes' => [],
+        'iconText' => '',
+        'iconCssClass' => '',
+        'iconAttributes' => [],
+        'active' => false,
+        'disabled' => false,
+        'enclose' => false,
+        'submenu' => false,
+    ],
+]
diff --git a/docs/navbar.md b/docs/navbar.md
@@ -59,15 +59,15 @@ $this->setJsFiles($assetManager->getJsFiles());
 <script defer src="https://use.fontawesome.com/releases/v5.3.1/js/all.js"></script>
 
 <?= NavBar::widget()
-    ->brandLabel('My Project')
+    ->attributes(['class' => 'is-black', 'data-sticky' => '', 'data-sticky-shadow' => ''])
     ->brandImage('yii-logo.jpg')
+    ->brandText('My Project')
     ->brandUrl('/')
-    ->options(['class' => 'is-black', 'data-sticky' => '', 'data-sticky-shadow' => ''])
-    ->itemsOptions(['class' => 'navbar-end'])
     ->begin()
 ?>
 
 <?= Nav::widget()
+    ->enclosedByEndMenu()
     ->items([
         [
             'label' => 'Setting Account',
@@ -98,25 +98,25 @@ $this->setJsFiles($assetManager->getJsFiles());
 <?= NavBar::end() ?>
 ```
 
-HTML produced is like the following:
+The code above generates the following HTML:
 
 ```html
-<nav id="w1-navbar" class="navbar is-black" data-sticky="" data-sticky-shadow="">
+<nav id="w1-navbar" class="is-black navbar" data-sticky data-sticky-shadow aria-label="main navigation" role="navigation">
     <div class="navbar-brand">
-        <span class="navbar-item">
-            <img src="yii-logo.jpg" alt="">
-        </span>
-        <a class="navbar-item" href="/">My Project</a>
+        <a class="navbar-item" href="/"><img src="yii-logo.jpg">My Project</a>
         <a class="navbar-burger" aria-expanded="false" aria-label="menu" role="button">
-            <span aria-hidden="true"></span><span aria-hidden="true"></span><span aria-hidden="true"></span>
+            <span aria-hidden="true"></span>
+            <span aria-hidden="true"></span>
+            <span aria-hidden="true"></span>
         </a>
     </div>
-    <div id="w1-navbar-Menu" class="navbar-menu">
-        <div class="navbar-end"><a class="navbar-item" href="/setting/account"><span class="icon"><i class="fas fa-user-cog"></i></span><span>Setting Account</span></a>
-            <a class="navbar-item" href="/profile"><span class="icon"><i class="fas fa-users"></i></span><span>Profile</span></a>
-            <div class="navbar-item has-dropdown">
-                <a class="navbar-link" href="#">Admin<img class="img-rounded" src="../../docs/images/icon-avatar.png" alt="" aria-expanded="false"></a>
-                <div id="w2-dropdown" class="navbar-dropdown is-hoverable">
+    <div class="navbar-menu">
+        <div class="navbar-end">
+            <a class="navbar-item" href="/setting/account">Setting Account</a>
+            <a class="navbar-item" href="/profile">Profile</a>
+            <div class="navbar-item has-dropdown is-hoverable">
+                <a class="navbar-link" href="#">Admin<img src="../../docs/images/icon-avatar.png" alt></a>
+                <div class="navbar-dropdown">
                     <a class="navbar-item" href="/auth/logout">Logout</a>
                 </div>
             </div>
@@ -125,22 +125,61 @@ HTML produced is like the following:
 </nav>
 ```
 
-## Reference
+## Setters
 
+All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\NavBar` class with the specified value.
 
 Method | Description | Default
 -------|-------------|---------
-`id(string $value)` | Widget ID. | `''`
+`attributes(array $values)` | HTML attributes for the widget container nav. | `[]`
 `autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w`
-`brand(string $value)` | Custom brand HTML. Overrides `brandLabel` and `brandImage`. | ''
-`brandLabel(string $value)` | Text of the brand label. | ''
-`brandImage(string $value)` | Image of the brand. | ''
-`brandUrl(string $value)` | "href" of the brand's link. | `/`
-`toggleIcon(string $value)` | Toggle icon. | `<span aria-hidden='true'></span>`
-`options(array $value)` | HTML attributes for the nav tag. | [`class` => `navbar`]
-`brandOptions(array $value)` | HTML attributes of the brand tag. | [`class` => `navbar-brand`]
-`brandLabelOptions` | HTML attributes of the brand label tag. | [`class` => `navbar-item`]
-`brandImageOptions` | HTML attributes of the brand link tag.           | [`class` => `navbar-item`]
-`itemsOptions(array $value)` | HTML attributes of the nav items tag. | [`class` => `navbar-start`] or [`class` => `navbar-end`]
-`menuOptions(array $value)` | HTML attributes of the nav menu tag. | [`class` => `navbar-menu`]
-`toggleOptions(array $value)`| HTML attributes of the navbar toggle button tag. | [`aria-expanded` => `false`, `aria-label` => `menu`, `class` => `navbar-burger`, `role` => `button`]
+`brandAttributes(array $values)` | HTML attributes for the navbar brand. | `[]`
+`brandImage(string $value)` | Image for the navbar brand. | `''`
+`brandText(string $value)` | Text for the navbar brand. | `''`
+`brandTextAttributes(array $values)` | HTML attributes for the navbar brand text. | `[]`
+`brandUrl(string $value)` | URL for the navbar brand. | `''`
+`buttonLinkAriaExpanded(string $value)` | The ARIA expanded attribute of the button link. | `'false'`
+`buttonLinkAriaLabelText(string $value)` | The ARIA label text of the button link. | `'menu'`
+`buttonLinkContent(string $value)` | The content of the button link. | `''`
+`buttonLinkRole(string $value)` | The role of the button link. | `'button'`
+`id(string $value)` | Set the ID of the navbar. | `''`
+`navBarAriaLabel(string $value)` | The ARIA label of the navbar. | `'main navigation'`
+`navBarBrandCssClass(string $value)` | CSS class for the navbar brand. | `'navbar-brand'`
+`navBarBurgerAttributes(array $values)` | HTML attributes for the navbar burger. | `[]`
+`navBarBurgerCssClass(string $value)` | CSS class for the navbar burger. | `'navbar-burger'`
+`navBarCssClass(string $value)` | CSS class for the navbar. | `'navbar'`
+`navBarItemCssClass(string $value)` | CSS class for the navbar item. | `'navbar-item'`
+`navBarRole(string $value)` | The role of the navbar. | `'navigation'`
+
+All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Nav` class with the specified value.
+
+Method | Description | Default
+-------|-------------|---------
+`activateParents()` | Activate parent menu items when the current menu item is activated. | `false`
+`attributes(array $values)` | HTML attributes for the widget container | `[]`
+`currentPath(string $value)` | Allows you to assign the current path of the url from request controller. | `''`
+`enclosedByEndMenu()` | Align the menu items to the right. | `false`
+`enclosedByStartMenu()` | Align the menu items to the left. | `false`
+`id(string $value)` | Set the ID of the navbar. | `''`
+`items(array $value)` | The menu items. | `[]`
+`withoutActivateItems()` |  Disable activate items according to whether their currentPath. | `false`
+
+### Items structure is an array of the following structure:
+
+```php
+[
+    [
+        'label' => '',
+        'url' => '',
+        'urlAttributes' => [],
+        'dropdownAttributes' => [],
+        'iconText' => '',
+        'iconCssClass' => '',
+        'iconAttributes' => [],
+        'items' => [],
+        'active' => false,
+        'disable' => false,
+        'visible' => false,
+        'encode' => false,
+    ],
+]
diff --git a/src/Breadcrumbs.php b/src/Breadcrumbs.php
@@ -59,8 +59,8 @@ public function ariaLabel(string $value): self
     /**
      * Returns a new instance with the specified active item template.
      *
-     * @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.
+     * @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
      */
@@ -72,18 +72,18 @@ public function activeItemTemplate(string $value): self
     }
 
     /**
-     * Returns a new instance with the specified attributes.
+     * The HTML attributes. The following special options are recognized.
      *
-     * @param array $value The HTML attributes for the widget container nav tag.
+     * @param array $values Attribute values indexed by attribute names.
      *
      * @return self
      *
-     * {@see Html::renderTagAttributes()} for details on how attributes are being rendered.
+     * See {@see \Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
      */
-    public function attributes(array $value): self
+    public function attributes(array $values): self
     {
         $new = clone $this;
-        $new->attributes = $value;
+        $new->attributes = $values;
         return $new;
     }
 
@@ -197,8 +197,8 @@ public function itemsAttributes(array $value): self
     /**
      * Returns a new instance with the specified item template.
      *
-     * @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.
+     * @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
      */