Datatable Bundle Laravel Package

Getting Started

This package gives you themed, server-rendered tables with typed cells, partials and a client-side Stimulus layer (search builder, dynamic controls, confirmation dialogs). v2.0.0-beta.1 is a major-with-breaking-changes beta — if you're on 1.x, read docs/migration-2.0.md before touching code.

Minimal path on a fresh app:

1. Require the package and publish its config + assets (php artisan vendor:publish for the package tag, then build via your asset pipeline).
2. Confirm which theme is selected. BootstrapTheme remains the default maintained theme; if you have no explicit theme config, you're on it.
3. Render one table with a couple of typed cells (text, date, action buttons) and click through the search builder and any confirm-destroy action. This exercises the three areas the release changed: template resolution, theme-supplied control classes, and the <dialog> confirmation flow.

Where to look first:

• The theme registry — it's now the public entry point for "what does this theme provide?" Metadata is immutable and declares capabilities and asset ownership, so it answers "does this theme give me assets, or do I supply them?" faster than reading templates.
• BootstrapTheme — default cell presentation moved here. If a cell looks different after upgrading, this is where the markup went.
• docs/migration-2.0.md — the three upgrade axes: template overrides, assets, confirmation dialog.

First use case to validate: a resource index page with a searchable column, one custom partial, and a destructive action. If that renders and the dialog behaves, the rest is variation.

Implementation Patterns

Theme selection and custom themes. Treat the registry as the contract. Register your theme with explicit capabilities (assets: owned or host-supplied) and its own template namespace. Because metadata is immutable, don't reach in and mutate a registered theme at runtime — register a variant or a thin subclass of BootstrapTheme that only overrides what differs. This keeps capability checks honest.

Template override. Every shell, partial and typed-cell template now resolves through the selected theme. Practical pattern: create your own theme that extends BootstrapTheme, override the two or three templates you actually need, and let the rest fall through. Avoid copying whole template trees into resources/views/vendor/… — that's the 1.x habit the migration guide is steering you away from, and it will silently pin you to old markup.

External theme packages. If you ship a theme as a Composer package, the fresh-host validation is your integration test. Add a CI job that installs the package into a clean Laravel app, registers the theme, and renders a table — this catches missing asset declarations and template namespace typos that pass locally when your dev machine has stale published assets.

Typed cells. Put presentation logic in the theme, not in the cell class. A cell should hand over a value and a type; the theme decides markup and classes. If you find yourself emitting Bootstrap classes from application code, you've leaked the theme and will fight it on the next theme swap.

Stimulus controllers. The vanilla controller is now decoupled from Bootstrap imports and generated classes. Pattern: keep your own controllers free of framework CSS classes, and read control classes from the theme-supplied attributes/data the controller renders rather than hardcoding them. If you have a 1.x controller that imported Bootstrap JS directly, replace those imports with the theme's supplied behaviour.

Search builder. Dynamic rule rows are built with DOM nodes and textContent. If you extended the builder with custom rule types, follow that pattern: document.createElement + textContent, never string concatenation with user input. Custom renderers that still interpolate HTML will work but reintroduce exactly the injection risk this release closed.

Confirmation dialogs. Confirmation now uses the native <dialog> element. Pattern: let the theme own the dialog markup, and wire your destructive actions to the shared confirmation helper rather than confirm(). If you had a Bootstrap modal override, port it to <dialog> — showModal(), close, and the cancel event — instead of restoring the modal.

Gotchas and Tips

• Template overrides are the main break. Every shell, partial and typed cell now resolves through the theme. Published-view overrides from 1.x may no longer be hit, or may be hit at a different path. Verify by intentionally breaking a template and confirming you see the change.
• Cell presentation moved into BootstrapTheme. If your app published cell partials, they may now be shadowed or bypassed. Diff your cell output before and after the upgrade rather than assuming your override still wins.
• Custom themes must supply control classes. With the Stimulus controller decoupled from Bootstrap, dynamic controls rely on theme-supplied classes. A half-migrated custom theme will render controls that look unstyled or lose state styling — not an error, just wrong output, which is harder to spot.
• Asset ownership is declared, not assumed. A theme that claims to own assets but doesn't publish them fails quietly on a fresh host. This is precisely what the new validation targets — run it in CI, not on your already-warm local install.
• Immutable metadata means no runtime patching. Registering a second theme with the same name, or mutating metadata after registration, is a bug shaped like a feature. Use a distinct name.
• <dialog> has real behavioural differences: focus trapping, ::backdrop, ESC handling and form integration. If you have JS asserting on modal DOM or Bootstrap events (shown.bs.modal), it will break silently. Search your JS for those event names during the upgrade.
• Beta caveat. Pin 2.0.0-beta.1 exactly and keep a 1.x branch. Do not use a ^2.0@beta constraint in a project you'll be away from; beta APIs around the registry may still shift before stable.
• Debugging tip. When a template "doesn't apply", dump the resolved theme name and the resolved view path before reading any template code — resolution, not markup, is the usual culprit in this release.
• Extension points to prefer: theme subclassing, registry capabilities, and theme-supplied classes/attribute data. Extension points to avoid: published vendor view copies, mutating registry metadata, and HTML-string interpolation in the search builder.