⬡ Lacelium
⌘K
Version 2.x ▾
Core UI System

Modal Architecture

Lacelium features an AJAX-driven modal architecture that enables you to load any application route into an accessible, animated dialog without writing bespoke JavaScript event handlers or managing DOM lifecycle states.

Declarative Trigger Attributes

Attach data-lacelium-modal-* attributes to any button or link to transform it into an asynchronous dialog trigger:

Data Attribute Accepted Values Description
data-lacelium-modal-url /route/path The target URL to asynchronously fetch into the dialog container.
data-lacelium-modal-title string The header title rendered at the top of the modal window.
data-lacelium-modal-class modal-sm | modal-lg | modal-xl Optional dialog width sizing class.
data-lacelium-modal-fragment selector (optional) Extracts a specific sub-element instead of the default #lacelium-main.
data-lacelium-modal-close boolean Clicking any element with this attribute immediately dismisses the active modal.

Live Sandbox Demonstration

Experience how declarative triggers asynchronously fetch content into the global modal overlay:

Launch Test Dialogs

Click any trigger below to test asynchronous modal hydration in real-time.

Modal Form Submissions & Lifecycle

Forms submitted inside a modal dialog are automatically intercepted. The framework handles two standard controller response patterns:

1. Validation Error Handling (HTML Response)

When form validation fails, returning a rendered HTML fragment replaces only the modal body, displaying inline validation error alerts while preserving input states.

// Controller returns form view with errors
return $response->render('modals/task-form.twig', [
    'errors' => $validator->errors(),
    'values' => $request->all(),
]);
2. Success Redirection (JSON Response)

When an operation succeeds, return a JSON response with a redirect parameter. The client automatically dismisses the modal and navigates to the destination via SPA transition.

// Controller returns successful redirect instruction
return $response->json([
    'success'  => true,
    'message'  => 'Task saved successfully',
    'redirect' => '/tasks',
]);

JavaScript Programmatic API

Open or close modals programmatically from custom frontend scripts using the LaceliumModal helper:

// Programmatically launch modal
LaceliumModal.open({
    url: '/users/create',
    title: 'Create New Account',
    size: 'modal-lg',
    onLoaded: function(modalElement) {
        console.log('Modal content rendered successfully.');
    }
});

// Programmatically close active modal
LaceliumModal.close();

ArgusKit Maintenance Modals API

For administrative schema and table management, Lacelium provides the high-level MaintenanceModal suite:

// Pre-built administrative dialog actions
MaintenanceModal.add('tasks');        // Opens creation dialog
MaintenanceModal.edit('tasks', 42);   // Opens edit dialog for ID 42
MaintenanceModal.view('tasks', 42);   // Opens read-only inspect dialog
MaintenanceModal.remove('tasks', 42); // Prompts confirmation dialog

Modal Guidelines & Accessibility

  • Focus Trapping: Lacelium automatically locks background page scrolling and confines keyboard Tab focus to the modal dialog.
  • Escape Key Dismissal: Pressing Esc automatically closes the dialog unless data-lacelium-modal-static="true" is applied.
  • Fragment Isolation: Use data-lacelium-modal-fragment to exclude navigation headers or sidebars when reusing full pages inside dialogs.

Next Steps