Skip to content

Commit

Permalink
Merge pull request #5 from bezhanSalleh/feature/bunchofthings
Browse files Browse the repository at this point in the history
Feature/bunchofthings
  • Loading branch information
bezhanSalleh authored Sep 19, 2023
2 parents 7f57283 + 807ba9e commit 691a1f6
Show file tree
Hide file tree
Showing 8 changed files with 384 additions and 95 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/run-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ name: run-tests

on:
push:
branches: [main]
branches: [3.x]
pull_request:
branches: [main]
branches: [3.x]

jobs:
test:
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/update-changelog.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ jobs:
- name: Checkout code
uses: actions/checkout@v4
with:
ref: main
ref: 3.x

- name: Update Changelog
uses: stefanzweifel/changelog-updater-action@v1
Expand All @@ -23,6 +23,6 @@ jobs:
- name: Commit updated CHANGELOG
uses: stefanzweifel/git-auto-commit-action@v4
with:
branch: main
branch: 3.x
commit_message: Update CHANGELOG
file_pattern: CHANGELOG.md
188 changes: 151 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,23 +10,45 @@
<a href="https://packagist.org/packages/bezhansalleh/filament-panel-switch">
<img alt="Packagist" src="https://img.shields.io/packagist/v/bezhansalleh/filament-panel-switch.svg?style=for-the-badge&logo=packagist">
</a>
<a href="https://github.com/bezhansalleh/filament-panel-switch/actions?query=workflow%3Arun-tests+branch%3Amain" class="filament-hidden">
<a href="https://github.com/bezhansalleh/filament-panel-switch/actions?query=workflow%3Arun-tests+branch%3A3.x" class="filament-hidden">
<img alt="Tests Passing" src="https://img.shields.io/github/actions/workflow/status/bezhansalleh/filament-panel-switch/run-tests.yml?style=for-the-badge&logo=github&label=tests">
</a>
<a href="https://github.com/bezhansalleh/filament-panel-switch/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain" class="filament-hidden">
<a href="https://github.com/bezhansalleh/filament-panel-switch/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3A3.x" class="filament-hidden">
<img alt="Code Style Passing" src="https://img.shields.io/github/actions/workflow/status/bezhansalleh/filament-panel-switch/run-laravel-pint.yml?style=for-the-badge&logo=github&label=code%20style">
</a>

<a href="https://packagist.org/packages/bezhansalleh/filament-panel-switch">
<img alt="Downloads" src="https://img.shields.io/packagist/dt/bezhansalleh/filament-panel-switch.svg?style=for-the-badge" >
</a>
</p>
<h2>Table Of Contents</h2>

- [Panel Switch](#panel-switch)
- [Installation](#installation)
- [Configuration](#configuration)
- [Design or Style](#design-or-style)
- [Labels](#labels)
- [Icons/Images](#iconsimages)
- [Icon/Image Size](#iconimage-size)
- [Visibility](#visibility)
- [Who Can Switch Panels?](#who-can-switch-panels)
- [Panel Exclusion](#panel-exclusion)
- [Placement](#placement)
- [Usage](#usage)
- [Theming](#theming)
- [Testing](#testing)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security Vulnerabilities](#security-vulnerabilities)
- [Credits](#credits)
- [License](#license)

# Panel Switch
Easily switch between panels in Filament.
The Panel Switch Plugin for Filament offers a robust and customizable component for switching between panels in applications built with FilamentPHP.

![Demo](./art/demo.gif?raw=true "Demo")

![Demo](./art/modern-icon-demo.gif?raw=true "Modern Icon Demo")
![Demo](./art/modern-image-demo.gif?raw=true "Modern Image Demo")
![Demo](./art/demo.gif?raw=true "Simple Demo")

## Installation

Expand All @@ -35,24 +57,65 @@ You can install the package via composer:
```bash
composer require bezhansalleh/filament-panel-switch
```
That's it, no other steps are required.
Upon installation, the Plugin seamlessly integrates with Filament without any further setup.
Though the plugin works out-of-the-box, it's designed for customization. Delve into the Configuration section below for detailed customization options.

## Configuration
Right now you can configure a couple things for the plugin. By calling the `PanelSwitch` class's `configureUsing()` method inside a service provider's `boot()` method.
Start your custom configuration using the `configureUsing` method in your service provider's boot method:

```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

public function boot()
{
PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
//
});
}
PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
// Custom configurations go here
});
```

#### Labels
You have the ability to set personalized labels for your panels by utilizing the `labels()` method. This feature can also be employed for translation purposes.
### Design or Style
By default, the Plugin uses Filament's [Modal Blade component](https://filamentphp.com/docs/3.x/support/blade-components/modal) as the modern design for the panel switch menu. But you can change it to the simple design by using the `simple()` method.

- #### Modern
- ##### Modal Heading
Set a custom Modal Heading for the Panel Switcher. By default, the modal heading is set to `Switch Panels`.
```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch->modalHeading('Available Panels');
});
```
- ##### Modal Width
By default, the modal width is set to `screen` but you can use the options avaialbel for [Modal Blade component](https://filamentphp.com/docs/3.x/support/blade-components/modal#changing-the-modal-width).
```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch->modalWidth('sm');
});
```
- ##### Slide-Over
You can use the `slideOver()` method to open a `slide-over` dialog instead of the modal.
```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch->slideOver();
});
```
- #### Simple
The `simple()` method transforms the panel switch menu to a dropdown list, allowing users to switch between panels directly from the list.
```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch->simple();
});
```
### Labels
By using `labels()` method you can provide textual representation for each panel. The keys of the array should be valid panel IDs, and the values can be either regular strings or Laravel's translatable strings:

```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch
->labels([
Expand All @@ -62,11 +125,52 @@ PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
});
```

#### Visibility
### Icons/Images
Define icons/images for available panels using the `icons()` method which accepts an array. The keys of the array should be valid panel IDs. If using images instead of icons, set the `$asImage` parameter to `true` and the value of the array should be the path to the image meaning a valid url:

- **Icons**
```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch->icons([
'validPanelId1' => 'heroicon-o-square-2-stack',
'validPanelId2' => 'heroicon-o-star',
], $asImage = false);
});
```

- **Images**
```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch->icons([
'validPanelId1' => 'https://raw.githubusercontent.com/bezhanSalleh/filament-panel-switch/3.x/art/banner.jpg',
'validPanelId2' => 'https://raw.githubusercontent.com/bezhanSalleh/filament-panel-switch/3.x/art/banner.jpg',
], $asImage = true);
});
```

### Icon/Image Size
Use the `iconSize()` method to set the size of the icons/images. The default size is `128px`. The value provided will be multiplied by 4 and then used as the size of the icon/image.

```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
// This would result in an icon/image size of 128 pixels.
$panelSwitch->iconSize(32);
});
```

### Visibility
By default, the package checks whether the user can access the panel if so the switch will be visible. You can further customize whether the panel switch should be shown.

```php
PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch
->visible(fn (): bool => auth()->user()?->hasAnyRole([
'admin',
Expand All @@ -76,17 +180,19 @@ PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
});
```

#### Who Can Switch Panels?
### Who Can Switch Panels?
You might want an option in a situation where you want a group of your users to see the panel but not be able to switch panels. You can do that by using the `canSwitchPanels()` method.

```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch
->canSwitchPanels(fn (): bool => auth()->user()?->can('switch_panels'));
});
```

#### Panel Exclusion
### Panel Exclusion
By default all the panels available will be listed in the panel switch menu. But you can exclude some of them by using the `excludes()` method.

```php
Expand All @@ -97,32 +203,40 @@ PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
});
```

#### Placement
You can choose where the panel switch menu should be placed. By default panel switch menu is rendered via 'panels::topbar.start' `Hook`. But you can change it to anyone of the other available hooks.
### Placement
You can choose where the panel switch menu should be placed. By default panel switch menu is rendered via 'panels::global-search.before' `Hook`. But you can change it to anyone of the other available Filament [Render Hooks](https://filamentphp.com/docs/3.x/support/render-hooks#available-render-hooks).
```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch->renderHook('panels::global-search.before');
$panelSwitch->renderHook('panels::global-search.after');
});
```

The `PanelSwitch` has a fluent api so you can chain the methods together and configure everything in one go.
### Usage
The `Panel Switch Plugin` has a fluent api so you can chain the methods together and configure everything in one go.

```php
use BezhanSalleh\PanelSwitch\PanelSwitch;

PanelSwitch::configureUsing(function (PanelSwitch $panelSwitch) {
$panelSwitch
->visible(fn (): bool => auth()->user()?->hasAnyRole([
'admin',
'general_manager'
'super_admin',
]))
->canSwitchPanels(fn (): bool => auth()->user()?->can('switch_panels'))
->excludes([
'saas'
->heading('Available Panels')
->modalWidth('sm')
->slideOver()
->icons([
'admin' => 'heroicon-o-square-2-stack',
'app' => 'heroicon-o-star',
])
->renderHook('panels::global-search.before');
->iconSize(16)
->labels([
'admin' => 'Admin Panel',
'app' => 'SaaS Application'
]);

});
```
## Theming
### Theming
By default the plugin uses the default filament theme, but you can customize it by adding the view path into the `content` array of your `panels'` `tailwind.config.js` file:

```php
Expand All @@ -140,7 +254,7 @@ Optionally, you can publish the views using
```bash
php artisan vendor:publish --tag="filament-panel-switch-views"
```
## Testing
### Testing

```bash
composer test
Expand All @@ -157,7 +271,7 @@ If you want to contribute to this packages, you may want to test it in a real Fi
* Fork this repository to your GitHub account.
* Create a Filament app locally.
* Clone your fork in your Filament app's root directory.
* In the `/filament-panel-swtich` directory, create a branch for your fix, e.g. `fix/error-message.`
* In the `/filament-panel-switch` directory, create a branch for your fix, e.g. `fix/error-message.`

Install the packages in your app's `composer.json:`

Expand All @@ -168,7 +282,7 @@ Install the packages in your app's `composer.json:`
"repositories": [
{
"type": "path",
"url": "filament-panel-swtich"
"url": "filament-panel-switch"
}
]
```
Expand Down
Binary file added art/modern-icon-demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added art/modern-image-demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,6 @@
}
}
},
"minimum-stability": "dev",
"minimum-stability": "stable",
"prefer-stable": true
}
Loading

0 comments on commit 691a1f6

Please sign in to comment.