Skip to content
stencil / 1

Layout

Last updated:

On this page

Layout components hold other components. Each takes schema([...]) (or its components as the last argument of make()), and null entries are skipped, so $condition ? TextInput::make('x') : null works.

use Javaabu\Stencil\Components\Fieldset;
use Javaabu\Stencil\Components\Grid;
use Javaabu\Stencil\Components\Group;
use Javaabu\Stencil\Components\Section;
use Javaabu\Stencil\Components\Step;
use Javaabu\Stencil\Components\Tab;
use Javaabu\Stencil\Components\Tabs;
use Javaabu\Stencil\Components\Wizard;
Component Renders as Takes
Section::make(heading) <x-forms::card> / Card with the heading as title description(), columns()
Grid::make(columns) a grid, no other markup columns()
Group::make([...]) nothing of its own columns(); use it to show, hide or span components together
Fieldset::make(label) <fieldset> with a <legend> columns()
Tabs::make([Tab::make(label)->schema([...])]) <x-forms::tabs> / Tabs activeTab(key); tabs take icon() and columns()
Wizard::make([Step::make(label)->schema([...])]) steps with Back and Next startOnStep(int); steps take description() and columns()

Two components show things rather than take input:

use Javaabu\Stencil\Components\Alert;
use Javaabu\Stencil\Components\TextEntry;

Alert::make(__('Published articles are visible to everyone.'))->color('warning')->heading(__('Note'));
TextEntry::make('created_at')->label(__('Created'));
TextEntry::make('author')->value(fn (Article $record) => $record->author->name);

TextEntry shows the field's state, or the record's attribute, or value(). Enums show their getLabel().

Nesting state

statePath() nests the state of the fields inside a component under a key, to put a group of fields someone else defined into your form:

Group::make()->statePath('meta')->schema([
    TextInput::make('subtitle')->maxLength(255),
    Checkbox::make('featured'),
]);

The fields get the state path meta.subtitle, the input name meta[subtitle] and the id meta-subtitle. They're filled from data_get($record, 'meta.subtitle'), validated as meta.subtitle, and returned from validate() as ['meta' => ['subtitle' => …, 'featured' => …]], which fillModel() and save() pass to the model's meta attribute. Paths nest: a section with statePath('seo') inside the group gives meta.seo.title. Find nested fields by their full path ($form->getField('meta.subtitle')), and use it in conditions (visibleWhen('meta.featured', true)).

On a field, statePath() replaces the path its name gives: TextInput::make('subtitle')->statePath('sub_title').

Columns

columns(2) lays the components inside out in two columns from the md breakpoint (768px), one below it. Pass breakpoints for more control: default, sm (640px), md, lg (1024px), xl (1280px).

Section::make(__('Address'))->columns(['sm' => 2, 'xl' => 4])->schema([
    TextInput::make('address.line')->columnSpanFull(),
    TextInput::make('address.island'),
    TextInput::make('address.postcode'),
]);

columnSpan(2) takes two columns from md up, columnSpan(['md' => 2, 'xl' => 1]) per breakpoint, columnSpanFull() the whole row. The form itself takes columns() too.

Grids are CSS grid with logical properties, in stencil's stylesheet (stencil::styles), so they work with Onu and Bootstrap 6, left to right and right to left.

Tabs

Tabs::make([
    Tab::make(__('Details'))->schema([...]),
    Tab::make(__('Address'))->columns(2)->schema([...]),
])->activeTab('tab-address');

A tab's key is tab- and its label in snake case (tab-address), or key(). Every tab is rendered, so all the fields submit. Hidden tabs (->hidden(), ->visibleOn()) are left out.

Wizards

Wizard::make([
    Step::make(__('Account'))->description(__('How you sign in'))->schema([
        TextInput::make('email')->email()->required(),
        TextInput::make('password')->password()->required(),
    ]),
    Step::make(__('Profile'))->schema([
        TextInput::make('name')->thaana(),
    ]),
]);

One step shows at a time. Next checks the step's fields with the browser's validation first; the submit button shows on the last step. Every step is in the form, so the server validates them all when it's submitted, and the first step with an error opens when the page comes back. The buttons are "Next" and "Back" (stencil::strings.next, stencil::strings.previous).

Documentation
All packages

javaabu/stencil

Source on GitHub