README

Adds a Guide button to Filament pages. It opens a full-width modal that shows a Blade view explaining the page: what it is for, what each part means and how to use it.

• Filament 5, Laravel 12 or 13, PHP 8.3+.
• Guides are plain Blade views, so they live with your application and can use any HTML.
• Nothing is shown when a page has no guide, or when its view does not exist.

Installation

composer require atendwa/filament-page-guide

Register the plugin on each panel that shows guides (it adds the modal's styles):

use Atendwa\PageGuide\Filament\PageGuidePlugin;

$panel->plugins([
    PageGuidePlugin::make(),
]);

Then run php artisan filament:assets so the stylesheet is published.

Adding a guide to a page

Use the trait on any Filament page (list, view, custom pages) and name the guide view:

use Atendwa\PageGuide\Concerns\HasPageGuide;

class ListOrders extends ListRecords
{
    use HasPageGuide;

    public function getPageGuide(): ?string
    {
        return 'guides.orders';
    }
}

The trait adds the button through the page's actions(). If your page builds its own header actions, include $this->pageGuideAction() where you want the button.

Write the guide with the component the package provides:

{{-- resources/views/guides/orders.blade.php --}}
<x-pageguide::partials.guide title="Working with orders">
    <p>Orders appear here as soon as they are paid.</p>
    <ul>
        <li><strong>Status:</strong> where the order is in fulfilment.</li>
    </ul>
</x-pageguide::partials.guide>

Optional customisation

Footer and decoration

Both are off by default. Set them on the plugin:

PageGuidePlugin::make()
    ->footer(['Kind regards,', 'The support team', 'support@example.com'])
    ->decoration('components.guide-artwork');

• footer() takes lines shown at the bottom of every guide (empty lines are skipped). The first line is emphasised.
• decoration() takes the name of a Blade component rendered beside the guide on large screens (for example an illustration). It receives a class attribute to fill the space.

Testing

composer install
composer quality   # Pint, Rector, PHPStan (max), Pest

License

MIT. See LICENSE.md.