Creating bricks

A brick is a class with an associated Blade view that is rendered in the editor with its data. They follow the same conventions as Filament's RichEditor custom blocks.

Scaffolding one

php artisan make:mason-brick Section

This writes the class into the namespace from generator.namespace (default App\Mason) and its Blade templates into generator.views_path under resources/views (default mason). Pass --force to overwrite an existing brick.

Anatomy

use Awcodes\Mason\Brick;
use Filament\Actions\Action;
use Filament\Forms\Components\FileUpload;
use Filament\Forms\Components\Radio;
use Filament\Forms\Components\RichEditor;
use Filament\Support\Icons\Heroicon;
use Illuminate\Contracts\Support\Htmlable;
use Illuminate\Support\HtmlString;

class Section extends Brick
{
    public static function getId(): string
    {
        return 'section';
    }

    public static function getLabel(): string
    {
        return parent::getLabel();
    }

    public static function getIcon(): string | Heroicon | Htmlable | null
    {
        return Heroicon::OutlinedSquares2x2;
    }

    public static function getTags(): array
    {
        return ['section', 'content', 'layout'];
    }

    public static function toHtml(array $config, ?array $data = null): ?string
    {
        return view('mason.section', [
            'background_color' => $config['background_color'] ?? 'white',
            'image' => $config['image'] ?? null,
            'text' => $config['text'] ?? null,
        ])->render();
    }

    public static function configureBrickAction(Action $action): Action
    {
        return $action
            ->slideOver()
            ->schema([
                Radio::make('background_color'),
                FileUpload::make('image'),
                RichEditor::make('text'),
            ]);
    }
}

Method	Purpose
`getId()`	Required. The identifier stored in the JSON. The only abstract method.
`getLabel()`	Sidebar label. Derived from the class name unless overridden.
`getIcon()`	Sidebar icon. A `Heroicon` case, an icon name, or an `Htmlable` for inline SVG.
`getTags()`	Search terms. Empty by default.
`toHtml()`	Renders the brick from its saved `$config`, plus any `$data` passed by the renderer.
`configureBrickAction()`	Builds the form shown when inserting or editing.

getId() is what ties stored content to a class, so changing it on a brick that is already in use orphans the existing content.

Outline labels

When a field has the outline enabled, each brick is listed by its label, so a page with several Sections shows several identical rows. getOutlineLabel() gives each one its own name, worked out from its saved config. The outline shows it with the brick's label underneath:

public static function getOutlineLabel(array $config): ?string
{
    return $config['heading'] ?? null;
}

Returning null or an empty string falls back to the brick's label. It is only called when the outline is enabled, and the result is never saved with the content. The built-in Section brick uses the first 60 characters of its text.

Rendering from the record

toHtml() takes a second argument holding whatever context the renderer was given — most usefully the record the content belongs to. It is empty unless something passes it, so guard the keys you read:

public static function toHtml(array $config, ?array $data = null): ?string
{
    $record = $data['record'] ?? null;

    return view('mason.byline', [
        'heading' => $config['heading'] ?? null,
        'author' => $record?->author?->name,
        'published' => $record?->published_at,
    ])->render();
}

See Rendering for how to supply it.

Warning

The editor preview does not supply $data. It renders in an iframe that has no record in scope, so a record-dependent brick renders its fallback there. Write the fallback so the brick still reads sensibly while it is being edited.

Bricks without a form

For a brick that needs no configuration — a divider, a fixed callout — return the view from toHtml() and hide the modal, so inserting it adds it immediately:

public static function toHtml(array $config, ?array $data = null): ?string
{
    return view('mason.static-brick');
}

public static function configureBrickAction(Action $action): Action
{
    return $action->modalHidden();
}