README

A powerful Filament plugin for managing announcements in your Laravel application. Create, manage, and display announcements with customizable scopes, colors, and navigation controls.

Installation

You can install the package via composer:

composer require backstage/announcements

Important

If you have not set up a custom theme and are using Filament Panels follow the instructions in the Filament Docs first.

After setting up a custom theme add the plugin's views to your theme css file or your app's css file if using the standalone packages.

@source '../../../../vendor/backstage/announcements/resources/**/*.blade.php';

You can publish and run the migrations with:

php artisan vendor:publish --tag="backstage-announcements-migrations"
php artisan migrate

Note

Existing installs must publish and run the new add_display_to_announcements_table migration to use popup announcements. Existing announcements stay banners.

Optionally, you can publish the views using

php artisan vendor:publish --tag="backstage-announcements-views"

This is the contents of the published config file:

return [
];

Usage

Add the plugin to your Filament panel provider:

use Backstage\Announcements\AnnouncementsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            AnnouncementsPlugin::make(),
        ]);
}

Navigation Control

Control whether the announcements resource appears in the navigation menu:

AnnouncementsPlugin::make()
    ->canRegisterNavigation(false) // Hide from navigation

AnnouncementsPlugin::make()
    ->canRegisterNavigation(true) // Show in navigation (default)

Forced Scopes

Limit which scopes (resources/pages) are available when creating announcements. You can specify the full class names of resources or pages:

AnnouncementsPlugin::make()
    ->forceScopes([
        'App\\Filament\\Resources\\Users\\UserResource',
        'App\\Filament\\Resources\\Products\\ProductResource',
        'App\\Filament\\Pages\\Dashboard',
    ])

The plugin will automatically match these class names to the formatted scope names that appear in the dropdown, so users will see friendly names like "Users (list)" instead of the full class names. The form automatically converts between class names (stored in database) and formatted names (displayed in UI) using the formatStateUsing() method.

Creating Announcements

Once configured, you can create announcements through the Filament interface:

Title: The announcement title
Content: The announcement content (supports HTML)
Scopes: Select which resources/pages the announcement should appear on
Color: Choose a color theme for the announcement
Display as: Banner (default) or Popup with confirmation required

Popup announcements

Choosing Popup with confirmation required shows the announcement as a modal that blocks the page until the user clicks "I've read this". It has no close button, Esc does nothing and clicking the overlay does nothing.

Popups are mounted on the panel's BODY_END hook, one component per page, and use the package's own .ba-popup-* CSS shipped in the dist CSS.
Login, registration, password reset and any other SimplePage scope always show a banner instead of a popup.
The popup option is disabled in the form unless at least one page other than login or registration is selected.
When several popups apply to a page they are shown one after another, oldest first, with an "N of M" counter.
Each confirmation is stored per user. Use the Reset dismissals action to make everyone confirm the announcement again.
Guests never see popups.

Displaying Announcements

Announcements are automatically displayed on the selected scopes using the included Livewire component. The component handles:

Dismissal tracking per user
Color theming
Responsive design
Accessibility features

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

backstage / announcements

Package info

Security

Fund package maintenance!

Statistics