Wire Elements Modal

https://github.com/wire-elements/modal
Admin
Wire Elements Modal is a Livewire component that provides a modal with support for multiple child...
Tokens:3,655
Snippets:33
Trust Score:7.2
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Wire Elements Modal via Composer

Source: https://github.com/wire-elements/modal/blob/main/README.md

The Composer command to install the wire-elements/modal package. Specifies version 2.0 or higher for installation.

```shell
composer require wire-elements/modal:^2.0
```

--------------------------------

### Open Wire Elements Modal with Parameters (HTML)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Demonstrates how to open a Livewire modal ('edit-user') and pass parameters like user ID or advanced mode settings directly from HTML. It shows examples for both outside and inside existing Livewire components.

```html
<!-- Outside of any Livewire component -->
<button onclick="Livewire.dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->id }} }})">Edit User</button>

<!-- Inside existing Livewire component -->
<button wire:click="$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->id }} }})">Edit User</button>

<!-- If you use a different primaryKey (e.g. email), adjust accordingly -->
<button wire:click="$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->email }} }})">Edit User</button>

<!-- Example of passing multiple arguments -->
<button wire:click="$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->id }}, advancedMode: true }})">Edit User</button>
```

--------------------------------

### Dispatch OpenModal Event (Inside Livewire)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Example of dispatching the `openModal` event from within an existing Livewire component using `$dispatch`. This is the standard way to open modals programmatically in Livewire.

```html
<!-- Inside existing Livewire component -->
<button wire:click="$dispatch('openModal', { component: 'edit-user' })">Edit User</button>
```

--------------------------------

### Dispatch OpenModal Event (Outside Livewire)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Example of dispatching the `openModal` event using JavaScript when not inside an existing Livewire component. This is used to trigger the display of a modal from plain HTML.

```html
<!-- Outside of any Livewire component -->
<button onclick="Livewire.dispatch('openModal', { component: 'edit-user' })">Edit User</button>
```

--------------------------------

### Extend ModalComponent in Livewire Class

Source: https://github.com/wire-elements/modal/blob/main/README.md

PHP code example showing a Livewire component class that extends `ModalComponent`. This is required for the component to function as a modal within the Wire Elements Modal system.

```php
<?php

namespace App\Http\Livewire;

use LivewireUI\Modal\ModalComponent;

class EditUser extends ModalComponent
{
    public function render()
    {
        return view('livewire.edit-user');
    }
}
```

--------------------------------

### Close Modal to Previous State (HTML)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Provides an example of how to close the current modal and revert to the previous modal state by dispatching the 'closeModal' event from an HTML button. This is useful for canceling operations or returning to a prior view.

```html
<button wire:click="$dispatch('closeModal')">No, do not delete</button>
```

--------------------------------

### Publish Wire Elements Modal Config

Source: https://github.com/wire-elements/modal/blob/main/README.md

Command to publish the configuration file for wire-elements-modal. This allows customization of the modal's behavior and appearance. Requires re-publishing after upgrading to v3.

```shell
php artisan vendor:publish --tag=wire-elements-modal-config
```

--------------------------------

### Receive Parameters in Wire Elements Modal Component (PHP)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Shows how a Livewire modal component ('EditUser') can receive and utilize passed parameters. It illustrates automatic database fetching when a typed property matches the parameter name and how parameters are available in the 'mount' method.

```php
<?php

namespace App\Http\Livewire;

use App\Models\User;
use LivewireUI\Modal\ModalComponent;

class EditUser extends ModalComponent
{
    // This will inject just the ID
    // public int $user;

    public User $user;

    public function mount()
    {
        Gate::authorize('update', $this->user);
    }

    public function render()
    {
        return view('livewire.edit-user');
    }
}

```

--------------------------------

### Create Livewire Modal Component

Source: https://github.com/wire-elements/modal/blob/main/README.md

Artisan command to generate a new Livewire component that can be used as a modal. The generated component must extend `ModalComponent` from the LivewireUIModal package.

```shell
php artisan make:livewire EditUser
```

--------------------------------

### Upgrade Livewire v2 to v3 Command

Source: https://github.com/wire-elements/modal/blob/main/README.md

This command automates the upgrade process for wire-elements-modal from Livewire v2 to v3. It targets specific upgrade routines for the modal component.

```shell
php artisan livewire:upgrade --run-only wire-elements-modal-upgrade
```

--------------------------------

### Publish Modal Views for Customization

Source: https://github.com/wire-elements/modal/blob/main/README.md

Command to publish the modal's Blade view files. This allows developers to customize the modal's markup and integrate it with different CSS frameworks like TailwindCSS.

```shell
php artisan vendor:publish --tag=wire-elements-modal-views
```

--------------------------------

### Dispatch OpenModal with Namespaced Component

Source: https://github.com/wire-elements/modal/blob/main/README.md

Demonstrates how to open a modal when the component resides within a specific namespace. The `component` property in the dispatch event includes the full namespaced path.

```html
<!-- Taking namespace into account for component Admin/Actions/EditUser -->
<button wire:click="$dispatch('openModal', { component: 'admin.actions.edit-user' })">Edit User</button>
```

--------------------------------

### Livewire v2 vs v3 Event Emission for Modals

Source: https://github.com/wire-elements/modal/blob/main/README.md

Demonstrates the syntax change for emitting modal events between Livewire v2 and v3. Livewire v3 uses `$dispatch` with an object for component and arguments, replacing v2's `$emit`.

```html
<-- Before -->
<button wire:click="$emit('openModal', 'users')">Show Users</button>
<!-- After -->
<button wire:click="$dispatch('openModal', {component: 'users'})">Show Users</button>

<-- Before -->
<button wire:click="$emit('openModal', 'edit-user', {user: 5})">Edit User</button>
<!-- After -->
<button wire:click="$dispatch('openModal', {component: 'edit-user', arguments: {user: 5}})">Edit User</button>
```

--------------------------------

### Add Livewire Directive to Template

Source: https://github.com/wire-elements/modal/blob/main/README.md

Instructs how to include the main Livewire modal directive within an HTML template. This directive initializes the modal functionality for the application.

```html
<html>
<body>
    <!-- content -->

    @livewire('wire-elements-modal')
</body>
</html>
```

--------------------------------

### Wire Elements Modal Configuration File

Source: https://github.com/wire-elements/modal/blob/main/README.md

This PHP array defines the default settings for the Wire Elements Modal. It includes options for including CSS and JavaScript, as well as default properties for modal components like width and closing behavior.

```php
<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Include CSS
    |--------------------------------------------------------------------------
    |
    | The modal uses TailwindCSS, if you don't use TailwindCSS you will need
    | to set this parameter to true. This includes the modern-normalize css.
    |
    */
    'include_css' => false,


    /*
    |--------------------------------------------------------------------------
    | Include JS
    |--------------------------------------------------------------------------
    |
    | Livewire UI will inject the required Javascript in your blade template.
    | If you want to bundle the required Javascript you can set this to false
    | and add `require('vendor/wire-elements/modal/resources/js/modal');`
    | to your script bundler like webpack.
    |
    */
    'include_js' => true,


    /*
    |--------------------------------------------------------------------------
    | Modal Component Defaults
    |--------------------------------------------------------------------------
    |
    | Configure the default properties for a modal component.
    |
    | Supported modal_max_width
    | 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl'
    */
    'component_defaults' => [
        'modal_max_width' => '2xl',

        '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,
    ],
];

```

--------------------------------

### Close Modal with Events and Parameters (PHP)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Details how to close a modal and trigger events on other Livewire components, passing additional parameters to those events. This allows for fine-grained control over cross-component communication after modal actions.

```php
public function update()
{
    $this->user->update($data);

    $this->closeModalWithEvents([
        UserOverview::class => ['userModified', [$this->user->id]],
    ]);
}

```

--------------------------------

### Close Modal with Events from Component Class (PHP)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Shows how to close the current modal and simultaneously trigger other Livewire components with specific events. This is useful for updating related parts of the UI after a modal action is completed.

```php
public function update()
{
    Gate::authorize('update', $this->user);

    $this->user->update($data);

    $this->closeModalWithEvents([
        UserOverview::class => 'userModified',
    ]);
}

```

--------------------------------

### Open Child Modal from Parent Modal (HTML)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Illustrates how to open a nested modal (a child modal) from within an existing modal. This is achieved by using the same 'openModal' dispatch event from a button within the parent modal's template.

```html
<!-- Edit User Modal -->

<!-- Edit Form -->
<button wire:click="$dispatch('openModal', { component: 'delete-user', arguments: { user: {{ $user->id }} }})">Delete User</button>
```

--------------------------------

### Configure Tailwind CSS Safelist for Wire Elements Modal (v3+)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Configuration for Tailwind CSS v3+ to ensure modal-related classes are not purged. This includes specifying file paths and a safelist for modal width classes.

```javascript
export default {
  content: [
    './vendor/wire-elements/modal/resources/views/*.blade.php',
    './storage/framework/views/*.php',
    './resources/views/**/*.blade.php',
  ],
  safelist: [
    {
      pattern: /max-w-(sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl)/,
      variants: ['sm', 'md', 'lg', 'xl', '2xl']
    }
  ],
  // other options
}
```

--------------------------------

### Clear View Cache Artisan Command

Source: https://github.com/wire-elements/modal/blob/main/README.md

Artisan command to clear the application's view cache. This is a necessary step after upgrading the wire-elements-modal package to ensure changes are reflected.

```shell
php artisan view:clear
```

--------------------------------

### Force Close Modal from Component Class (PHP)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Explains how to completely close the current modal component without reverting to a previous state. This is achieved by chaining 'forceClose()' and 'closeModal()' methods in the component's logic.

```php
public function update()
{
    Gate::authorize('update', $this->user);

    $this->user->update($data);

    $this->forceClose()->closeModal();
}

```

--------------------------------

### Configure Tailwind CSS Purge for Wire Elements Modal

Source: https://github.com/wire-elements/modal/blob/main/README.md

This snippet shows how to update your `tailwind.config.js` file to correctly purge unused CSS classes when using the Wire Elements Modal. It includes paths to modal view files and a safelist pattern for dynamic classes.

```javascript
module.exports = {
  purge: {
    content: [
      './vendor/wire-elements/modal/resources/views/*.blade.php',
      './storage/framework/views/*.php',
      './resources/views/**/*.blade.php',
    ],
    options: {
      safelist: {
            pattern: /max-w-(sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl)/,
            variants: ['sm', 'md', 'lg', 'xl', '2xl']
        }
    }
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}
```

--------------------------------

### Skip Previous Modals

Source: https://github.com/wire-elements/modal/blob/main/README.md

Skip one or more previous modals when closing the current one. Use `skipPreviousModal()` to skip one, or `skipPreviousModals(n)` to skip 'n' modals. This is useful for navigating complex modal flows.

```php
public function delete()
{
    Gate::authorize('delete', $this->team);

    $this->team->delete();

    $this->skipPreviousModal()->closeModalWithEvents([
        TeamOverview::class => 'teamDeleted'
    ]);
}
```

--------------------------------

### Close Modal from Component Class (PHP)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Demonstrates closing the current modal from within the Livewire component class using the 'closeModal()' method. This is typically called after an action is completed or needs to be canceled.

```php
<?php

namespace App\Http\Livewire;

use App\Models\User;
use LivewireUI\Modal\ModalComponent;

class EditUser extends ModalComponent
{
    public User $user;

    public function mount()
    {
        Gate::authorize('update', $this->user);
    }

    public function update()
    {
        Gate::authorize('update', $this->user);

        $this->user->update($data);

        $this->closeModal();
    }

    public function render()
    {
        return view('livewire.edit-user');
    }
}

```

--------------------------------

### Enable Closing Event Dispatch

Source: https://github.com/wire-elements/modal/blob/main/README.md

Enable a `modalClosed` event to be fired when a modal is closed. Override the static `dispatchCloseEvent` method and return `true`. The name of the closed component is provided as a parameter.

```php
public static function dispatchCloseEvent(): bool
{
    return true;
}
```

--------------------------------

### Set Modal Width

Source: https://github.com/wire-elements/modal/blob/main/README.md

Override the static `modalMaxWidth` method in your modal component to change the modal's width. The default is '2xl'. Supported values include 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl'.

```php
public static function modalMaxWidth(): string
{
    return 'xl';
}
```

--------------------------------

### Destroy Skipped Modals

Source: https://github.com/wire-elements/modal/blob/main/README.md

Optionally destroy skipped modals using `destroySkippedModals()` to reset their state when they are opened again. This is typically called after `skipPreviousModal()` or `skipPreviousModals()`.

```php
$this->skipPreviousModal()->destroySkippedModals()->closeModalWithEvents([
    TeamOverview::class => 'teamDeleted'
]);
```

--------------------------------

### Destroy Modal Component on Close

Source: https://github.com/wire-elements/modal/blob/main/README.md

Override the static `destroyOnClose` method and return `true` to destroy the modal component when it is closed. This resets the component's state when it's opened again.

```php
public static function destroyOnClose(): bool
{
    return true;
}
```

--------------------------------

### Control Forceful Closing on Escape

Source: https://github.com/wire-elements/modal/blob/main/README.md

Control whether pressing the escape key forcefully closes all modals. Override the static `closeModalOnEscapeIsForceful` method and return `false` to disable forceful closing, allowing for actions like showing a previous modal.

```php
public static function closeModalOnEscapeIsForceful(): bool
{
    return false;
}
```

--------------------------------

### Prevent Closing Modal Based on State (JavaScript)

Source: https://github.com/wire-elements/modal/blob/main/README.md

Prevent a modal from closing on Escape or click away if there are uncommitted changes. Listen for `closingModalOnEscape` and `closingModalOnClickAway` events and set `data.closing = false` if `isDirty` is true and the user cancels the confirmation.

```javascript
$wire.on('closingModalOnEscape', data => {
    if ($wire.isDirty && !confirm('{{ __('You have unsaved changes. Are you sure you want to close this dialog?') }}')) {
        data.closing = false;
    }
});
$wire.on('closingModalOnClickAway', data => {
    if ($wire.isDirty && !confirm('{{ __('You have unsaved changes. Are you sure you want to close this dialog?') }}')) {
        data.closing = false;
    }
});
```

--------------------------------

### Disable Closing Modal on Click Away

Source: https://github.com/wire-elements/modal/blob/main/README.md

Disable the default behavior of closing the modal when clicking outside of it by overriding the static `closeModalOnClickAway` method and returning `false`.

```php
public static function closeModalOnClickAway(): bool
{
    return false;
}
```

--------------------------------

### Disable Closing Modal on Escape

Source: https://github.com/wire-elements/modal/blob/main/README.md

Disable the default behavior of closing the modal when the escape key is pressed by overriding the static `closeModalOnEscape` method and returning `false`.

```php
public static function closeModalOnEscape(): bool
{
    return false;
}
```
Tokens:
Raw