HeaderLines Layout

HeaderLines is for document-style screens with a header (sections with fields) and an editable grid of line items — like sales orders, purchase orders, or invoices.

Setup

class SalesOrderResource extends Resource
{
    protected static string $model = \App\Models\SalesOrder::class;
    protected static string $label = 'Sales Order';

    public static function layout(): string
    {
        return 'HeaderLines';
    }

    public static function linesRelation(): ?string
    {
        return 'lines';   // Eloquent relationship name
    }

    public static function linesOverlayPct(): int
    {
        return 65;   // Grid overlay size (0-100)
    }

    public static function form(): array
    {
        return [
            Section::make('General')
                ->column(0)->rowGroup(0)
                ->fields([
                    Text::make('no')->label('No.')->width(20)->uppercase()->disabled(),
                    Text::make('customer_no')->label('Customer No.')->width(20)
                        ->uppercase()
                        ->lookup('customer_no', 'customer_name', validate: true),
                    Text::make('customer_name')->label('Customer Name')
                        ->width(30)->disabled(),
                ]),
        ];
    }

    public static function table(): array
    {
        return [
            TextColumn::make('no')->label('No.')->width(10),
            TextColumn::make('customer_name')->label('Customer')->width('fill'),
            DecimalColumn::make('total')->label('Total')->decimals(2)->width(15)->align('right'),
        ];
    }

    public static function lineColumns(): array
    {
        return [
            OptionColumn::make('type')->label('Type')
                ->options(['Item', 'Resource', 'Text'])
                ->editable()->width(10),
            TextColumn::make('no')->label('No.')
                ->editable()->width(15)
                ->lookup('line_item', 'no')
                ->autofill(['description']),
            TextColumn::make('description')->label('Description')
                ->editable()->width('fill'),
            DecimalColumn::make('quantity')->label('Qty')
                ->editable()->decimals(2)->width(10)->align('right'),
            DecimalColumn::make('unit_price')->label('Unit Price')
                ->editable()->decimals(2)->width(12)->align('right'),
            DecimalColumn::make('discount_pct')->label('Disc. %')
                ->editable()->decimals(1)->width(8)->align('right'),
            DecimalColumn::make('amount')->label('Amount')
                ->decimals(2)->width(15)->align('right'),
        ];
    }

    public static function totals(?\Illuminate\Database\Eloquent\Model $model = null): array
    {
        $total = $model?->lines?->sum('amount') ?? 0;

        return [
            ['label' => 'Total', 'value' => number_format($total, 2, '.', ''), 'source_column' => 'amount'],
        ];
    }
}

Overlay

The linesOverlayPct() method controls how much of the screen the grid takes. The default is 50. Override it when you want a different split:

public static function linesOverlayPct(): int
{
    return 65; // grid takes 65% of the screen
}

• 0 = grid hidden, full header view
• 50 = split view (default — omit the method to use this)
• 100 = grid fills entire screen

The user toggles the overlay with Ctrl+L.

By default the overlay starts closed. Override linesOpen() to open it automatically when the screen loads:

public static function linesOpen(): bool
{
    return true;
}

Empty Trailing Row

The server always includes at least one empty trailing row in the grid, allowing the user to add new line items.

Saving

The client sends both changes (header fields) and lines (2D grid data) in the SaveChangeset. The server:

1. Updates the header model with changes
2. Deletes all existing line items
3. Creates new line items from lines (skipping empty rows)
4. Returns the refreshed ScreenContract