Filament Plotly Laravel Package

Getting Started

• Install the package with Composer and run the publish command for config and frontend assets:

  composer require <vendor>/<package>
  php artisan vendor:publish --tag=<package>-config
  php artisan vendor:publish --tag=<package>-assets
  

• Look first at config/<package>.php and the package’s widget base class. That is where registration, default layout options, and modal wiring are defined.
• Start with the smallest possible widget: render a dashboard widget, add a beforeContent view, and open one modal from inside the widget. That exercises the two changes in 1.2.1 and gives you a working reference implementation.
• If you are on Livewire, verify the package’s asset and script registration is present in your layout before debugging widget rendering.

Implementation Patterns

• Widget-first composition: Keep widget classes thin. Put data preparation in the widget, presentation in Blade views, and modal content in dedicated partials so beforeContent and modal payloads stay reusable.
• Calling modals from within a widget: Use the package’s modal API from the widget’s action methods rather than dispatching ad-hoc browser events. This keeps modal state scoped to the widget instance and works correctly when multiple widgets are on the same dashboard.
• beforeContent layout: Treat beforeContent as a slot rendered immediately before the widget body. Wrap it in a stable container element in your published view so the 1.2.1 layout fix is preserved and your own CSS does not fight the package defaults.
• Dashboard integration: Register widgets through the package’s dashboard/provider mechanism rather than manually including Blade partials. This ensures scripts, modal hooks, and authorization checks are loaded in the expected order.
• Authorization and visibility: Gate widget rendering and modal-opening actions separately. A user may be allowed to see a widget but not open a modal that exposes sensitive actions.
• Testing: Use Livewire’s testing helpers to assert that a widget action opens the expected modal and that beforeContent renders the expected markup. Prefer asserting component state and emitted modal identifiers over brittle HTML snapshots.

Gotchas and Tips

• Nested modals: “Modals from within the widget” can lead to stacked modals. Ensure your modal component supports a stack or close-on-success behavior, otherwise users can end up with orphaned overlays.
• Livewire component identity: If you render multiple instances of the same widget, give each modal a deterministic, unique key. Duplicate modal IDs are the usual cause of “modal opens the wrong content” bugs.
• beforeContent CSS: The 1.2.1 layout fix may change spacing or wrapper structure. Re-check custom CSS that targets direct children of the widget body, and avoid relying on sibling selectors around beforeContent.
• Asset caching: After upgrading, clear cached views and republish assets if the modal JavaScript changed:

  php artisan view:clear
  php artisan config:clear
  php artisan <package>:publish-assets --force
  

• Debugging modal calls: If a modal does not open from a widget, check the browser console for missing package scripts, confirm the widget action is actually dispatched, and verify the modal identifier matches the registered modal name.
• Extension points: Prefer overriding published Blade views and config values over subclassing internal classes. The safest extension points are the widget view, the beforeContent partial, and the modal content view.
• Upgrade discipline: Pin the package version in composer.json and review the changelog for widget/modal-related changes before upgrading across minor versions, since layout and modal behavior can shift without a major version bump.