https://github.com/awes-io/navigator
🧿 Build navigation or menu for Laravel and Awes.io. Unlimited complexity and depth, with permissions and sorting support.
https://github.com/awes-io/navigator
awes-io laravel laravel-menu laravel-navigation menu navigation
Last synced: 4 months ago
JSON representation
🧿 Build navigation or menu for Laravel and Awes.io. Unlimited complexity and depth, with permissions and sorting support.
- Host: GitHub
- URL: https://github.com/awes-io/navigator
- Owner: awes-io
- License: mit
- Created: 2019-07-31T08:00:10.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2019-08-03T06:20:50.000Z (almost 6 years ago)
- Last Synced: 2024-02-23T22:43:07.745Z (over 1 year ago)
- Topics: awes-io, laravel, laravel-menu, laravel-navigation, menu, navigation
- Language: PHP
- Homepage: https://www.awes.io/
- Size: 54.7 KB
- Stars: 48
- Watchers: 6
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- Contributing: contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
Navigator
Laravel package that can easily create navigation menus of any complexity. With support for routing, permissions, sorting, rendering depth, active items marking and element searching.
##
## Table of Contents
- Installation
- Quickstart
- Configuration
- Usage
- Permissions
- Testing
## Installation
Via Composer
``` bash
$ composer require awes-io/navigator
```
The package will automatically register itself.
## Quickstart
Let's firstly create basic navigation, which covers most of the use cases.
Create navigation configuration file:
```php
// config/navigation.php
return [
[
'name' => 'Projects',
'route' => 'projects.index', // route must exist or item will be hidden
'children' =>
[
[
'name' => 'New projects',
'link' => '/projects/new', // you can use direct links
]
]
],
[
'name' => 'Packages',
'route' => 'packages.index',
]
];
```
Next, let's build our menu somewhere in the controller and pass it to a view:
```php
$menu = buildMenu(config('navigation'));
return view('menu', compact('menu'));
```
And finally implement basic rendering logic:
```php
// menu.blade.php
@foreach($menu as $item)
-
@if($item->link())
@if($item->isActive()) ACTIVE @endif {{$item->name}}
@else
{{$item->name}}
@endif
@if($item->hasChildren())
@include('menu', ['menu' => $item->children()])
@endif
@endforeach
```
That's all that simple!
## Configuration
You can publish the config file:
```bash
php artisan vendor:publish --provider="AwesIO\Navigator\NavigatorServiceProvider" --tag="config"
```
And rename any options keys, which are used to get respective data from the menu config:
```php
// navigator.php config
'keys' => [
'depth' => 'depth', // rendering depth
'order' => 'order', // ordering by parameter
'children' => 'children', // sub menu items
'route' => 'route', // route name
'link' => 'link', // item link url
'title' => 'name', // item title
'attr' => 'attr', // additional item attributes
],
```
As well as use alternative menu settings for parsing and rendering:
```php
// navigator.php config
'keys' => [
...
'children' => 'other-children', // alternative sub menu items
...
],
// navigation.php
'menu' => [
[
...
'children' => [
...
'other-children' => [
...
]
Navigator::buildMenu(config('navigation.menu')); // will now parse menu using 'other-children'
```
You can achieve the same effect dynamically, via mappings mentioned above:
```php
$menu = buildMenu(config('navigation.menu'), [], ['children' => 'other-children']);
```
Note that we now use the global helper method `buildMenu()`.
## Usage
```php
use AwesIO\Navigator\Facades\Navigator;
$menu = Navigator::buildMenu(config('navigation.menu'), ['depth' => 2], [], function ($item) {
$item->put('meta', $item->get('title') . ' / ' . $item->get('link'));
});
// using helper, rendering depth set via config as a second parameter
$menu = buildMenu(config('navigation.menu'), ['depth' => 2], [], function ($item) {});
```
The first parameter is the menu config in the form of an array:
```php
// navigation.php
return [
'menu' => [
[
'title' => 'Products', // menu item's title
'route' => 'products.index', // route name for URL generation
'order' => 1, // parameter to determine the order
'depth' => 1, // depth for the recursive generation of descendants
'children' =>
[
[
'id' => 1, // custom id which overwrites auto-generated one
'title' => 'Catalog',
'link' => 'products/catalog', // explicit relative path for link URL
],
[
'title' => 'Support',
'route' => 'products.support'
]
]
],
[
'title' => 'Contact us',
'route' => 'contacts',
'order' => 2,
],
]
];
```
Second is config, the third one is mappings for configuration parameters (described above), last is a callback, which will be applied to each menu item.
### Some helpful methods
Determine if the node has any children and retrieve them:
```php
$menu->hasChildren();
$menu->children();
```
Get a link URL for a node:
```php
$menu->link();
```
Determine if a node is currently selected and active:
```php
$menu->isActive();
```
Get a currently active node and its id:
```php
$menu->getActive();
$menu->getActiveId();
```
Find a node by its id:
```php
$menu->findById($id);
```
## Menu rendering example
```php
// somewhere in a controller
$menu = Navigator::buildMenu(config('navigation.menu'));
return view('view', compact('menu'));
// view.blade.php
@extends('main')
@section('content')
@include('menu', ['menu' => $menu])
@endsection
// menu.blade.php
@foreach($menu as $item)
-
@if($item->link())
{{$item->title}}
@else
{{$item->title}}
@endif
@if($item->hasChildren())
@include('menu', ['menu' => $item->children()])
@endif
@endforeach
```
## Permissions
If the user is not authorized to access some of the menu routes, they'll be automatically hidden based on existing permissions:
```php
Route::group(['middleware' => ['can:manage users']], function () {
Route::get('/', 'RoleController@index')->name('admin.roles.index');
});
// will be excluded from the menu for non-admin users
[
'name' => __('navigation.security'),
'icon' => 'twousers',
'route' => 'admin.roles.index',
],
```
## Testing
The coverage of the package is .
You can run the tests with:
```bash
composer test
```
## Contributing
Please see [contributing.md](contributing.md) for details and a todolist.
## Credits
- [Alexander Osokin](https://thealex.ru)
- [Galymzhan Begimov](https://github.com/begimov)
- [All Contributors][link-contributors]
## License
[MIT](http://opensource.org/licenses/MIT)