Getting Started

Minimal Setup

Installation
```
composer require contao-components/simplemodal
```
Ensure your Laravel project is using a frontend asset pipeline (e.g., Laravel Mix, Vite, or Webpack) to compile the required CSS/JS.

Basic Usage Include the package’s assets in your layout file (e.g., resources/views/layouts/app.blade.php):

<!DOCTYPE html>
<html>
<head>
    <!-- Other head elements -->
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @simplemodalStyles
</head>
<body>
    <!-- Your content -->
    @simplemodalScripts
</body>
</html>

First Modal Trigger Use the package’s Blade directive to trigger a modal:

@simplemodal(
    title: 'Welcome',
    content: 'This is a simple modal dialog.',
    buttons: [
        ['text' => 'Close', 'class' => 'btn btn-primary', 'action' => 'close']
    ]
)

Trigger it via JavaScript or a button click:

SimpleModal.open({
    title: 'Welcome',
    content: 'This is a simple modal dialog.',
    buttons: [
        { text: 'Close', class: 'btn btn-primary', action: 'close' }
    ]
});

Implementation Patterns

Common Workflows

Dynamic Content Modals Fetch content dynamically (e.g., from an API or Laravel route) and pass it to the modal:

fetch('/api/user-profile')
    .then(response => response.json())
    .then(data => {
        SimpleModal.open({
            title: 'User Profile',
            content: `
                <h3>${data.name}</h3>
                <p>${data.bio}</p>
            `,
            buttons: [
                { text: 'Edit', class: 'btn btn-warning', action: 'editProfile' },
                { text: 'Cancel', class: 'btn btn-secondary', action: 'close' }
            ]
        });
    });

Form Submission Modals Use modals for multi-step forms or confirmation dialogs:

@simplemodal(
    id: 'confirm-delete',
    title: 'Delete Item',
    content: 'Are you sure you want to delete this item?',
    buttons: [
        ['text' => 'Delete', 'class' => 'btn btn-danger', 'action' => 'confirmDelete'],
        ['text' => 'Cancel', 'class' => 'btn btn-secondary', 'action' => 'close']
    ]
)

Attach event listeners in your JavaScript:

document.querySelector('#confirm-delete').addEventListener('confirmDelete', function() {
    axios.delete('/items/123').then(() => {
        window.location.reload();
    });
});

Reusable Modal Components Create a Blade component for reusable modals (e.g., resources/views/components/modal.blade.php):

@props([
    'id' => null,
    'title' => 'Modal Title',
    'content' => '',
    'buttons' => [],
])

<div id="{{ $id }}" class="hidden">
    <div class="modal-content">
        <h2>{{ $title }}</h2>
        <div class="modal-body">
            {!! $content !!}
        </div>
        <div class="modal-footer">
            @foreach($buttons as $button)
                <button class="btn {{ $button['class'] ?? '' }}" data-action="{{ $button['action'] ?? 'close' }}">
                    {{ $button['text'] }}
                </button>
            @endforeach
        </div>
    </div>
</div>

@once
    @simplemodalScripts
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            SimpleModal.init();
        });
    </script>
@endonce

Use it in your views:

@include('components.modal', [
    'id' => 'login-modal',
    'title' => 'Login',
    'content' => '<form>...</form>',
    'buttons' => [
        ['text' => 'Login', 'class' => 'btn btn-primary', 'action' => 'submitForm'],
        ['text' => 'Cancel', 'class' => 'btn btn-secondary', 'action' => 'close']
    ]
])

Integration with Laravel Blade Directives Extend the package’s Blade directives for custom logic:

// In AppServiceProvider.php
use ContaoComponents\SimpleModal\Facades\SimpleModal;

public function boot()
{
    SimpleModal::extend(function ($view) {
        $view->with('customData', [
            'apiToken' => auth()->user()?->api_token,
        ]);
    });
}

Access custom data in your modal:

SimpleModal.open({
    title: 'API Access',
    content: `Your API token: {{ json_encode($customData['apiToken']) }}`,
    buttons: [...]
});

Gotchas and Tips

Pitfalls

Asset Loading Conflicts

Ensure @simplemodalStyles and @simplemodalScripts are placed after other CSS/JS dependencies but before closing </head> and </body> tags, respectively.

If using Laravel Mix/Vite, manually include the package’s assets in your entry files to avoid duplication:

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
    optimizeDeps: {
        include: ['contao-components/simplemodal'],
    },
});

Z-Index Issues
- SimpleModal uses a default z-index of 1000. Override it globally in your CSS if other elements (e.g., dropdowns) interfere:
```
.simplemodal-container {
    z-index: 9999 !important;
}
```

Event Binding Quirks

Custom actions (e.g., data-action="submitForm") require explicit JavaScript event listeners. The package does not auto-bind events by default:

// Correct:
document.querySelector('#my-modal').addEventListener('submitForm', handler);

// Incorrect (won't work):
SimpleModal.open({ ... }); // No auto-binding

Blade Directive Scope
- The @simplemodal directive must be placed inside a Blade template (e.g., .blade.php). It won’t work in raw Blade components without proper setup.

Debugging Tips

Check Console for Errors SimpleModal logs errors to the console. Look for:
- Missing dependencies (e.g., jQuery if required).
- Syntax errors in modal configuration.
Verify Initialization Ensure SimpleModal.init() is called after the DOM is loaded:
```
document.addEventListener('DOMContentLoaded', SimpleModal.init);
```

Inspect Modal Structure Use browser dev tools to verify the modal HTML structure. Example:

<!-- Expected structure -->
<div class="simplemodal-container">
    <div class="simplemodal-content">
        <h2>Title</h2>
        <div class="simplemodal-body">Content</div>
        <div class="simplemodal-footer">Buttons</div>
    </div>
</div>

Disable Animations for Testing Temporarily disable animations to rule out rendering issues:
```
SimpleModal.setOptions({ animate: false });
```

Extension Points

Custom Templates Override the default modal template by extending the package’s JavaScript:

SimpleModal.templates.content = function(title, content, footer) {
    return `
        <div class="custom-modal">
            <div class="custom-header">${title}</div>
            <div class="custom-body">${content}</div>
            <div class="custom-footer">${footer}</div>
        </div>
    `;
};

Add Global Options Set default options in your JavaScript entry file:

SimpleModal.setOptions({
    overlayOpacity: 0.5,
    animate: true,
    closeOnOutsideClick: true,
});

Laravel Facade Integration Use the facade to dynamically generate modal configurations:

$modalConfig = \ContaoComponents\SimpleModal\Facades\SimpleModal::make()
    ->title('Dynamic Title')
    ->content('<p>Generated at: ' . now() . '</p>')
    ->button('Save', 'saveAction', 'btn btn-success')
    ->button('Cancel', 'close', 'btn btn-secondary')
    ->toArray();

// Pass to Blade or JavaScript

Server-Side Rendering For SPAs or SSR, pre-render modals on the server and hydrate them client-side:

Simplemodal Laravel Package