Docs extended; added withAttribute[s]; the menu() helper; and the \Menus alias

Author: fulopattila122

Changelog.md

@@ -8,6 +8,10 @@
 - Dropped PHP 8.1 Support
 - Dropped Laravel 10 Support
 - Added Laravel 12 Support
+- Added the `menu('name')` helper for views which is equivalent to `\Menu:get('name')`
+- Added the `\Menus` alias to the facade
+- Added the `withAttribute` and `withAttributes` methods to the `Item` and `Link` classes
+- BC: Renamed the Facade class from `Menu` to `Menus` (the `\Menu` alias is still available!)
 
 ---
 

composer.json

@@ -30,7 +30,10 @@
     "autoload": {
         "psr-4": {
             "Konekt\\Menu\\": "src/"
-        }
+        },
+        "files": [
+            "src/helpers.php"
+        ]
     },
     "require-dev": {
         "ext-sqlite3": "*",
@@ -52,10 +55,11 @@
         },
         "laravel": {
             "providers": [
-                "Konekt\\Menu\\MenuServiceProvider"
+                "MenuServiceProvider"
             ],
             "aliases": {
-                "Menu": "Menus"
+                "Menu": "Konekt\\Menu\\Facades\\Menus",
+                "Menus": "Konekt\\Menu\\Facades\\Menus"
             }
         }
     }

docs/authorization.md

@@ -1 +1,65 @@
 # Authorizing Menu Items
+
+You may want to show or hide menu items depending on the authenticated user's permission.
+
+To achieve that, menu items can be authorized for users in two ways:
+
+## 1. Checking Via Actions
+
+Based on [Laravel's built-in](https://laravel.com/docs/11.x/authorization#authorizing-actions-using-policies)
+authorization, you can pass action names (strings) that will be tested against the current user with
+the `can()` method:
+
+```php
+$menu = Menus::create('nav', []);
+$menu->addItem('users', __('Users'), ['route' => 'app.user.index'])
+    ->allowIfUserCan('list users');
+
+$menu->addItem('settings', __('Settings'), ['route' => 'app.settings.index'])
+    ->allowIfUserCan('list settings');
+```
+
+## 2. Checking Via Callbacks
+
+You can also pass callbacks to authorize menu items for users:
+
+```php
+$menu = Menus::create('nav', []);
+$menu->addItem('users', __('Users'), ['route' => 'app.user.index'])
+    ->allowIf(function($user) {
+        return $user->id > 500; // Add your arbitrary condition
+    });
+```
+
+The callback will receive the user as the first parameter.
+
+> You can add multiple `allowIf` and/or `allowIfUserCan` conditions to an item.
+> The item will be allowed if **ALL** the conditions will be met.
+
+### Checking Authorization
+
+> By default, items without any condition are allowed.
+
+**To check if an item is allowed:**
+
+```php
+$menu->getItem('users')->isAllowed(); // Checks if is allowed for the current user
+$menu->getItem('settings')->isAllowed(User::find(501)); // Check if allowed for user 501 
+```
+
+**To get the list of allowed children:**
+
+```php
+$item->childrenAllowed(); // The allowed child items for the current user
+$item->childrenAllowed(\App\User::find(123)); // The allowed children for user 123
+```
+
+**In Blade templates:**
+
+```blade
+@foreach(menu('nav')->items() as $item)
+    @if($item->isAllowed())
+       <a href="{!! $item->url() !!}">{{ $item->title }}</a>
+    @endif
+@endforeach
+```

docs/items.md

@@ -1 +1,95 @@
 # Menu Items
+
+## Adding Items
+
+To add a menu item, use the `addItem` method.
+
+**Simple Links:**
+
+```php
+$navbar = Menus::create('navbar');
+
+// Simple link; to '/' via the URL helper
+$navbar->addItem('home', 'Home', '/');
+
+// External link, being used as-is
+$navbar->addItem('duckduckgo', 'Search', 'https://duckduckgo.com/');
+```
+
+**Laravel Routes:**
+
+```php
+// Named route
+$navbar->addItem('clients', 'Clients', ['route' => 'client.index']);
+// Named route with parameter
+$navbar->addItem('my-profile', 'My Profile', ['route' => ['user.show', 'id' => Auth::user()->id]]);
+```
+
+**Links to Controller Actions:**
+
+```php
+// Refer to an action
+$navbar->addItem('projects', 'Projects', ['action' => 'ProjectController@index']);
+// Action with parameter
+$navbar->addItem('issue7', 'Issue 7', ['action' => ['IssueController@edit', 'id' => 7]]);
+```
+
+The `addItem()` method receives 3 parameters:
+- the name of the item
+- the title of the item
+- and options
+
+*options* can be a simple string representing a URL or an associative array of options and HTML attributes which is described below.
+
+### Adding Sub-items
+
+Multi-level menus can be created by adding sub-items to menu items:
+
+```php
+$menu = Menus::create('main');
+
+$crm = $menu->addItem('crm', 'CRM')
+$crm->addSubItem('prospects', 'Prospects', ['url' => '/crm/prospects']);
+$crm->addSubItem('deals', 'Deals', ['url' => '/crm/deals']);
+```
+
+In the example above, the `crm` item _doesn't have a link_, and it _has children_, which means that it will **act like a group**.
+These conditions need to be taken into account at rendering:
+
+```blade
+<div class="menu">
+@foreach($menu->items as $item)
+    <div class="menu-item">
+        @if($item->hasLink)
+            <a href="{!! $item->url() !!}">{{ $item->title }}</a>
+        @else
+            {{ $item->title }}
+            @if($item->hasChildren()
+                <div class="submenu">
+                    @foreach($item->children() as $child)
+                         <a href="{!! $child->url() !!}" class="submenu-item">{{ $child->title }}</a>
+                    @endforeach
+                </div>
+            @endif
+        @endif
+    </div>
+@endforeach
+</div>
+```
+
+
+## Removing Items
+
+```php
+$menu = Menus::create('main');
+
+$menu->addItem('home', 'Home', '/');
+$menu->addItem('about', 'About', '/about');
+$menu->getItem('about')->addSubItem('about-us', 'About Us', ['url' => '/about/us']);
+
+// This will remove both about and about-us
+$menu->removeItem('about');
+
+// To keep children, set the second parameter `$removeChildren` to false:
+$menu->removeItem('about', false); // about-us will remain
+```

docs/menus.md

@@ -1 +1,54 @@
 # Menus
+
+## Creating Menus
+
+Applications can have one or more menus, either global ones, which are available on every page, or scoped ones, that
+are only available in certain areas.
+
+Menus that are available on every page of the application/website are best to be created in the
+`AppServiceProvider::boot()` method, so any request hits your application, the menu will be available.
+
+Menus that are available only to certain pages of an app/website can also be created within a controller, in
+[view composers](https://laravel.com/docs/11.x/views#view-composers), or anywhere else according to your preference.
+
+**Every menu is uniquely identified by its name** like `topmenu`, `sidebar`, or `products-submenu`, etc.
+
+Regardless of the scope and location, menus should be created using the `Menus` facade:
+
+**Example:**
+
+```php
+use Konekt\Menu\Facades\Menus;
+
+$sidebar = Menus::create('topmenu');
+$sidebar->addItem('customers', 'Customers',  '/customers');
+$sidebar->addItem('contracts', 'Contracts', '/contracts');
+$sidebar->addItem('invoices', 'Invoices', '/invoices');
+```
+
+## Rendering
+
+The easiest way to access the menu in a blade view is to use the `menu()` helper.
+
+**Using a built-in renderer:**
+
+```blade
+{{-- Render with the built in 'ul' renderer --}}
+{!! menu('sidebar')?->render('ul') !!}
+```
+
+**Rendering items manually:**
+
+```blade
+@if($sidebar = menu('sidebar'))
+  <ul class="sidebar">
+  @foreach($sidebar->items as $item)
+    <li class="sidebar-item"><a href="{!! $item->url() !!}">{{ $item->title }}</a></li>    
+  @endforeach
+  </ul>
+@endif
+```
+
+> Read the [Rendering Page](rendering.md) of this Documentation to learn all the rendering features available.
+
+

docs/quick-start.md

@@ -22,9 +22,9 @@ class AppServiceProvider extends ServiceProvider
 {
     public function boot(): void
     {
-        $sidebar = Menus::create('sidebar');
-        $sidebar->addItem('home', 'Home',  '/');
-        $sidebar->addItem('about', 'About', '/about');
+        $topmenu = Menus::create('topmenu');
+        $topmenu->addItem('home', 'Home',  '/');
+        $topmenu->addItem('about', 'About', '/about');
     }
 }
 ```