awcodes / pounce
A global modal/dialog plugin for Filament.
Fund package maintenance!
awcodes
Requires
- php: ^8.1
- filament/filament: ^3.0
- illuminate/contracts: ^10.0
- spatie/laravel-package-tools: ^1.15.0
Requires (Dev)
- laravel/pint: ^1.0
- nunomaduro/collision: ^7.9
- orchestra/testbench: ^8.0
- pestphp/pest: ^2.0
- pestphp/pest-plugin-arch: ^2.0
- pestphp/pest-plugin-laravel: ^2.0
- spatie/laravel-ray: ^1.26
README
This plugin adds a global modal for usage in Filament and is a port of Wire Elements Modal.
Please star the original repo if you like this plugin.
Installation
You can install the package via composer:
composer require awcodes/pounce
Important
If you have not set up a custom theme and are using Filament Panels follow the instructions in the Filament Docs for creating a custom theme first.
After setting up your theme, add the plugin's views to your tailwind.config.js
file and run npm run dev
or npm run build
to add the plugin styles to your theme.
content: [ ... './vendor/awcodes/pounce/resources/**/*.blade.php', ]
For Panels
If you are using Filament Panels you need to add the plugin to the panels you wish to use the plugin with. This will add the necessary livewire component to the panel's layout.
public function panel(Panel $panel): Panel { return $panel ->plugins([ PouncePlugin::make(), ]); }
Stand-alone usage
If you are using stand-alone Filament packages you will need to manually add the plugin to any layouts where you intend to use it. This should go before the closing body
tag, and you should only have one instance per page.
@livewire('pounce')
You can publish the config file with:
php artisan vendor:publish --tag="pounce-config"
Optionally (not recommended), you can publish the views using
php artisan vendor:publish --tag="pounce-views"
This is the contents of the published config file:
return [ 'modal_max_width' => \Awcodes\Pounce\Enums\MaxWidth::Medium, 'modal_alignment' => \Awcodes\Pounce\Enums\Alignment::MiddleCenter, 'modal_slide_over' => \Awcodes\Pounce\Enums\SlideDirection::None, 'close_modal_on_click_away' => true, 'close_modal_on_escape' => true, 'close_modal_on_escape_is_forceful' => true, 'dispatch_close_event' => false, 'destroy_on_close' => false, ];
Usage
Creating a modal
With the command line
For convince, the plugin offers a scaffolding command to create new modals. This will create a class file in App\Livewire
or your configured Livewire directory. It will also create a view at resources/views/livewire
.
The --form
flag will scaffold the modal with some defaults for making a modal that uses Filament's form methods.
php artisan make:pounce {name?} {--form} {--F|force}
Manually
To manually create a modal you simply need to run the Livewire make command and extend the PounceComponent
class.
php artisan make:livewire CustomModal
namespace App\Http\Livewire; use Awcodes\Pounce\PounceComponent; class CustomModal extends PounceComponent { public function render() { return view('livewire.custom-modal'); } }
Opening and Closing Modals
Note
Pounce uses all the same conventions and usage as Wire Elements Modal, the only thing to be aware of is to open a modal Pounce uses the pounce
event and to close a modal it uses the unPounce
event.
See Wire Elements Modal on GitHub for complete usage instructions.
Modal Alignment
Modals can be aligned to the top, center, or bottom of the screen and to the start, center, or end of the screen. The default alignment is MiddleCenter
. See the alignment enum for all available options. This can also be set globally in the config file.
use Awcodes\Pounce\Enums\Alignment; public static function getAlignment(): Alignment { return Alignment::MiddleCenter; }
Modal Width
Modal widths can be set using the enum cases found in Filament's MaxWidth
enum. See the MaxWidth enum for all available options. This can also be set globally in the config file.
use Awcodes\Pounce\Enums\MaxWidth; public static function getMaxWidth(): MaxWidth { return MaxWidth::Medium; }
Slide Overs
By default, all modals are standard pop-up modals. If you wish to use a slide over modal you can set the getSlideDirection
method to one of the SlideDirection
enum cases. See the SlideDirection enum for all available options. This can also be set globally in the config file.
use Awcodes\Pounce\Enums\SlideDirection; public static function getSlideDirection(): SlideDirection { return SlideDirection::Left; }
To open a normal modal with the slide features you will need to explicitly set the isSlideOver
method to return false
.
public static function isSlideOver(): bool { return false; }
Blade Views
While you are free to use any blade view you wish, the plugin comes with a few pre-made views to get you started. These views have predefined padding and margins to match Filament's UI.
<div> <x-pounce::header> {{-- Modal Header --}} </x-pounce::header> <x-pounce::close-button icon-color="white" /> // defaults to 'gray' <x-pounce::heading> {{-- Modal Heading --}} </x-pounce::heading> <x-pounce::description> {{-- Modal Description --}} </x-pounce::description> <x-pounce::content> {{-- Modal Content --}} </x-pounce::content> <x-pounce::footer align="start"> // accepts start, center, end {{-- Modal Footer --}} </x-pounce::footer> </div>
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.