Skip to content

Commit 4131223

Browse files
gaetan-hexadoggaetan-hexadog
committed
First version
0 parents  commit 4131223

25 files changed

+1600
-0
lines changed

‎.gitignore

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
vendor/
2+
.idea/
3+
composer.lock
4+
.php_cs.cache
5+
build/
6+
.DS_Store
7+
*.cache

‎CONTRIBUTING.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Contributing
2+
3+
Contributions are **welcome**. We accept contributions via Pull Requests on [Github](https://github.com/hexadog/laravel-menus-manager).
4+
5+
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
6+
7+
Please note we have a code of conduct, please follow it in all your interactions with the project.
8+
9+
## Pull Request Process
10+
11+
1. **[PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)** - Check the code style with ``$ composer check-style`` and fix it with ``$ composer fix-style``.
12+
2. **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date.
13+
variables, exposed ports, useful file locations and container parameters.
14+
3. **Consider our release cycle** - We try to follow the [SemVer v2.0.0](http://semver.org/) versioning scheme.
15+
4. **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
16+
17+
**Happy coding**!
18+
19+
## Code of Conduct
20+
21+
### Our Pledge
22+
23+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
24+
25+
### Our Standards
26+
27+
Examples of behavior that contributes to creating a positive environment
28+
include:
29+
30+
* Using welcoming and inclusive language
31+
* Being respectful of differing viewpoints and experiences
32+
* Gracefully accepting constructive criticism
33+
* Focusing on what is best for the community
34+
* Showing empathy towards other community members
35+
36+
Examples of unacceptable behavior by participants include:
37+
38+
* The use of sexualized language or imagery and unwelcome sexual attention or
39+
advances
40+
* Trolling, insulting/derogatory comments, and personal or political attacks
41+
* Public or private harassment
42+
* Publishing others' private information, such as a physical or electronic
43+
address, without explicit permission
44+
* Other conduct which could reasonably be considered inappropriate in a
45+
professional setting
46+
47+
### Our Responsibilities
48+
49+
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
50+
51+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
52+
53+
### Scope
54+
55+
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
56+
57+
### Enforcement
58+
59+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at `gaetan@hexadog.com`. All
60+
complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
61+
Further details of specific enforcement policies may be posted separately.
62+
63+
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
64+
65+
### Attribution
66+
67+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
68+
69+
[homepage]: http://contributor-covenant.org
70+
[version]: http://contributor-covenant.org/version/1/4/

‎README.md

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
<p align="center"><img src="https://i.ibb.co/31yzFSw/logo.png"></p>
2+
3+
<p align="center">
4+
<a href="https://packagist.org/packages/hexadog/laravel-menus-manager">
5+
<img src="https://poser.pugx.org/hexadog/laravel-menus-manager/v" alt="Latest Stable Version">
6+
</a>
7+
<a href="https://packagist.org/packages/hexadog/laravel-menus-manager">
8+
<img src="https://poser.pugx.org/hexadog/laravel-menus-manager/downloads" alt="Total Downloads">
9+
</a>
10+
<a href="https://packagist.org/packages/hexadog/laravel-themes-manager">
11+
<img src="https://poser.pugx.org/hexadog/laravel-menus-manager/license" alt="License">
12+
</a>
13+
</p>
14+
15+
<!-- omit in toc -->
16+
## Introduction
17+
<code>hexadog/laravel-menus-manager</code> is a Laravel package to ease dynamic menus management.
18+
19+
<!-- omit in toc -->
20+
## Installation
21+
This package requires PHP 7.3 and Laravel 7.0 or higher.
22+
23+
To get started, install Menus Manager using Composer:
24+
```shell
25+
composer require hexadog/laravel-menus-manager
26+
```
27+
28+
The package will automatically register its service provider.
29+
30+
<!-- omit in toc -->
31+
## Usage
32+
Menus Manager has many features to help you working with dynamic menus
33+
34+
- [Create Menu](#create-menu)
35+
- [Menu hierarchy](#menu-hierarchy)
36+
- [Menu Item](#menu-item)
37+
- [Item Types](#item-types)
38+
- [Route item](#route-item)
39+
- [Url item](#url-item)
40+
- [Divider item](#divider-item)
41+
- [Header item](#header-item)
42+
- [Item Icon](#item-icon)
43+
- [Item Order](#item-order)
44+
- [Item Visibility](#item-visibility)
45+
- [Active state](#active-state)
46+
- [Search for item](#search-for-item)
47+
- [Menu Tree](#menu-tree)
48+
- [Blade components](#blade-components)
49+
50+
### Create Menu
51+
Use the provided `Menus` facade with `register` method to create a new menu.
52+
_**notice:** if menu with given name already exists it will be returned - this way you can access to any existing menu anywhere in your application_
53+
```php
54+
// Create new "main" Menu
55+
$menu = Menus::register('main');
56+
```
57+
58+
You can now access to the menu any time using:
59+
```php
60+
// Retreive "main" Menu
61+
$menu = Menus::get('main');
62+
```
63+
64+
And get all items for the Menu
65+
```php
66+
// Get all items from Menu
67+
$items = $menu->items();
68+
```
69+
You can get a specific item by using search methods. See [Search an item](#search-an-item).
70+
71+
### Menu hierarchy
72+
Menus Manager lets you create multi-level menus. Each Menu item can have as many children as you want. See [Menu Item](#menu-item) to find out how to create a new Menu Item.
73+
74+
You can easily retreive declared children using:
75+
```php
76+
// Check if item has children
77+
if ($menuItem->hasChildren()) {
78+
// Get all item children as Collection
79+
$items = $menuItem->children();
80+
81+
// Loop into items
82+
foreach($items as $item) {
83+
// Get item parent
84+
$parent = $item->parent();
85+
86+
// ...
87+
}
88+
}
89+
```
90+
91+
### Menu Item
92+
An item can be added at any level: the menu itself or any child item.
93+
```php
94+
// Create a new menu
95+
$menu = Menus::register('main');
96+
97+
// Add a first-level item
98+
$menu->route('index', 'Home');
99+
100+
// Create a first-level item with children
101+
$menuItem = $menu->header('Our packages');
102+
$menuItem->url('https://github.com/hexadog/laravel-menus-manager', 'Laravel Menus Manager')->order(1);
103+
$menuItem->url('https://github.com/hexadog/laravel-themes-manager', 'Laravel Themes Manager')->order(3);
104+
$menuItem->url('https://github.com/hexadog/laravel-theme-installer', 'Laravel Theme Installer')->order(2);
105+
106+
// Create first-level items with visibility condition
107+
$menu->route('profile.show', __('Profile'))->if(Auth()->check());
108+
$menu->route('login', __('Login'))->if(!Auth()->check());
109+
```
110+
111+
You can access to the generated item url with `getUrl()` method on any item.
112+
```php
113+
$menuItem->getUrl();
114+
```
115+
116+
#### Item Types
117+
Menus Manager handle multiple item types: Route item, URL item, Header item and Divider item
118+
119+
##### Route item
120+
Add a menu item for a route by passing the route name and a title
121+
```php
122+
$menuItem = $menu->route('index', 'Home');
123+
```
124+
125+
You can pass parameters to the route by passing an array instead of a string as first parameter
126+
```php
127+
$menuItem = $menu->route(['index', ['type' => 'anonymous']], 'Home');
128+
```
129+
130+
##### Url item
131+
Add a menu item for an URL with the given title
132+
```php
133+
$menuItem = $menu->url('https://hexadog.com', 'hexadog');
134+
```
135+
136+
##### Divider item
137+
A simple divider: no action available. No title required for this type of item.
138+
```php
139+
$menuItem = $menu->divider();
140+
```
141+
142+
##### Header item
143+
Add header item: no action available. Mainly used to visually group sub-menus
144+
```php
145+
$menuItem = $menu->header('General');
146+
```
147+
148+
#### Item Icon
149+
You can add an icon to your menu item by calling `icon()` method with the icon classes as parameter.
150+
```php
151+
$menu->route('index', 'Home')->icon('fas fa-home');
152+
```
153+
154+
#### Item Order
155+
By default items are displayed in order they are created. You can specify item order to organize your menu entries:
156+
```php
157+
$menu->route('index', 'Home')->order(1);
158+
$menu->route('contact', 'Contact')->order(2);
159+
```
160+
161+
#### Item Visibility
162+
```php
163+
$menuItem->isVisible();
164+
```
165+
166+
You can condition item visibility by using `if()` method.
167+
You can chain conditions. This way each condition must be filled to make the item visible.
168+
```php
169+
$menu->route('profile.show', __('Profile'))->if(Auth()->check());
170+
$menu->route('login', __('Login'))->if(!Auth()->check());
171+
172+
$menu->route('post.create', __('New Post'))->if(Auth()->check())->if(Auth()->user()->can('create.post'));
173+
```
174+
175+
#### Active state
176+
Check if current item is active or has an active child.
177+
Depending on the item type, active state is determined using `Request::is()` or `Route::is()` Laravel methods.
178+
```php
179+
$menuItem->isActive();
180+
```
181+
182+
### Search for item
183+
Search an item recursively (in all hierarchy).
184+
```php
185+
$menu->search('title', 'Home'); // Return the found item or null
186+
```
187+
188+
or search in first level item children
189+
```php
190+
$menu->findBy('title', 'Home');
191+
```
192+
193+
You can search an item by title and add it if not found in one line with `findByTitleOrAdd()` helper method.
194+
```php
195+
$menu->findByTitleOrAdd('title');
196+
```
197+
198+
### Menu Tree
199+
Menu and Item implement `Illuminate\Contracts\Support\Arrayable` interface. Calling `toArray()` method on the follwing menu:
200+
```php
201+
// Create a new menu
202+
$menu = Menus::register('main');
203+
204+
// Add a first-level item
205+
$menu->route('index', 'Home');
206+
207+
// Create a first-level item with children
208+
$menuItem = $menu->header('Our packages');
209+
$menuItem->url('https://github.com/hexadog/laravel-menus-manager', 'Laravel Menus Manager')->order(1);
210+
$menuItem->url('https://github.com/hexadog/laravel-themes-manager', 'Laravel Themes Manager')->order(3);
211+
$menuItem->url('https://github.com/hexadog/laravel-theme-installer', 'Laravel Theme Installer')->order(2);
212+
213+
// Create first-level items with visibility condition
214+
$menu->route('profile.show', __('Profile'))->if(Auth()->check());
215+
$menu->route('login', __('Login'))->if(!Auth()->check());
216+
217+
// Get Menu Tree
218+
$menu->toArray();
219+
```
220+
221+
Returns an array of menu content
222+
```php
223+
[
224+
"name" => "main",
225+
"items" => [
226+
0 => [
227+
"attributes" => [
228+
"id" => "id-5f8c4a3d803dd817648152"
229+
],
230+
"active" => true,
231+
"children" => [],
232+
"icon" => null,
233+
"order" => 0,
234+
"title" => "Home",
235+
"type" => "link",
236+
"url" => "http://127.0.0.1:8000",
237+
],
238+
1 => [
239+
"attributes" => [
240+
"id" => "id-5f8c4a3d8045f366812051"
241+
],
242+
"active" => false,
243+
"children" => [
244+
0 => [
245+
"attributes" => [
246+
"id" => "id-5f8c4a3d80476901878768"
247+
],
248+
"active" => false,
249+
"children" => [],
250+
"icon" => null,
251+
"order" => 1,
252+
"title" => "Laravel Menus Manager",
253+
"type" => "link",
254+
"url" => "https://github.com/hexadog/laravel-menus-manager",
255+
],
256+
2 => [
257+
"attributes" => [
258+
"id" => "id-5f8c4a3d80496954609369"
259+
],
260+
"active" => false,
261+
"children" => [],
262+
"icon" => null,
263+
"order" => 2,
264+
"title" => "Laravel Theme Installer",
265+
"type" => "link",
266+
"url" => "https://github.com/hexadog/laravel-theme-installer",
267+
],
268+
1 => [
269+
"attributes" => [
270+
"id" => "id-5f8c4a3d8048e808061014"
271+
],
272+
"active" => false,
273+
"children" => [],
274+
"icon" => null,
275+
"order" => 3,
276+
"title" => "Laravel Themes Manager",
277+
"type" => "link",
278+
"url" => "https://github.com/hexadog/laravel-themes-manager",
279+
]
280+
],
281+
"icon" => null,
282+
"order" => 0,
283+
"title" => "Our packages",
284+
"type" => "header",
285+
"url" => "",
286+
]
287+
]
288+
]
289+
```
290+
291+
### Blade components
292+
Menus Manager provides blade components to ease integration in your designs.
293+
294+
You just have to pass your Menu name to get full render.
295+
```php
296+
<x-menus-menu name="main" />
297+
```
298+
It uses `x-menus-children`, `x-menus-divider`, `x-menus-header`, `x-menus-icon` and `x-menus-item` dedicated components. By default Menus Manager will scaffold your application's integration with the [Tailwind CSS](https://tailwindcss.com/) and [Alpine.js](https://github.com/alpinejs/alpine).
299+
300+
You can customize component's views to fit to your need by publishing them into your application resources:
301+
```shell
302+
php artisan vendor:publish --provider="Hexadog\MenusManager\Providers\PackageServiceProvider"
303+
```
304+
305+
<!-- omit in toc -->
306+
## Credits
307+
- Logo made by [DesignEvo free logo creator](https://www.designevo.com/logo-maker/)
308+
309+
<!-- omit in toc -->
310+
## License
311+
Laravel Menus Manager is open-sourced software licensed under the [MIT license](LICENSE).

0 commit comments

Comments
 (0)