Forms
Last updated:
On this page
A form is the root of a schema. It knows what it edits (the record), where it submits, and its components.
Inline forms
Build one where you need it, usually in a controller:
use Javaabu\Stencil\Fields\TextInput;
use Javaabu\Stencil\Form;
$form = Form::make()
->model($island)
->action(route('islands.update', $island))
->schema([
TextInput::make('name')->label(__('Name'))->required()->thaana(),
TextInput::make('code')->maxLength(5),
]);
Form classes
Put forms you reuse in a class, and return the components from definition(). A class is also what live fields need, because the server rebuilds the form to re-evaluate it.
namespace App\Stencil;
use Javaabu\Stencil\Components\Section;
use Javaabu\Stencil\Fields\Select;
use Javaabu\Stencil\Fields\TextInput;
use Javaabu\Stencil\Form;
class IslandForm extends Form
{
protected function definition(): array
{
return [
Section::make(__('Island'))->columns(2)->schema([
TextInput::make('name')->label(__('Name'))->required()->thaana(),
Select::make('atoll_id')->relationship('atoll', 'name')->required(),
]),
];
}
}
$form = IslandForm::make()->model($island)->action(route('islands.update', $island));
Override setUp() to configure the form itself ($this->submit(__('Save island'))), and authorize() to check permissions on live requests.
What the form edits
model() takes:
| Value | Use |
|---|---|
| A model | Edit it: fields fill from it, and save() updates it |
| A model class | Create one: ->model(Island::class); relationship options come from a new instance |
| An array or object | Read values only, for settings, filters or search forms |
The operation is edit for an existing record and create otherwise. Set it yourself with ->operation('view') (which disables every field) or any name of your own, and show components for some operations only with visibleOn() and hiddenOn().
Values the form needs besides the record go in with(), and are kept when a live form is rebuilt. Models are kept by their key:
CourseApplicationForm::make()->model(Application::class)->with(['course' => $course]);
// in the class
protected function definition(): array
{
$course = $this->context('course');
// …
}
Submitting
| Method | Default |
|---|---|
action(string|Closure) |
none |
method(string) |
PATCH for an existing model, POST otherwise. PUT, PATCH and DELETE are spoofed with _method |
files(bool) |
on when the form has a file field |
submit(bool|string) |
a button labelled "Save" (stencil::strings.submit), or config('stencil.submit'); a string for another label; false for none |
summary() |
lists every error at the top as well as under each field |
errorBag(string) |
the error bag validation writes to and fields read from |
disabled() |
disables every field |
id(string) |
the HTML id; stencil-form for inline forms, the class name in kebab case (island-form) for classes |
Rendering
Blade
A form is Htmlable, so echo it:
<x-layouts.admin>
{{ $form }}
</x-layouts.admin>
A form is Htmlable but not Stringable: echo it with {{ $form }}, and call $form->toHtml() (or render()) for a string, not (string) $form. This lets you pass a form to a Blade component (<x-card :form="$form">) as the form: Blade casts objects with __toString() to strings when they're passed to a class component's attributes, which would render the form there and could render it inside itself.
It renders <x-forms::form> with your components inside, bound to the form's state, and the submit button. The page needs manifest's tags (@manifestStyles and @manifestScripts) or its automatic injection, as for any javaabu/forms page.
Inertia React
A form is Arrayable and JsonSerializable, so pass it as a prop:
return Inertia::render('Islands/Edit', ['form' => IslandForm::make()->model($island)->action(route('islands.update', $island))]);
import { StencilForm, type StencilSchema } from "@javaabu/stencil"
export default function Edit({ form }: { form: StencilSchema }) {
return <StencilForm schema={form} />
}
See React.
Choosing in config
Packages that render either way call Stencil::render($form), which uses config('stencil.views'): blade (HTML) or inertia (the JSON array). $form->render('blade') and $form->render('json') pick a driver.
Only the fields
embedded() renders the components without the <form>, the submit button or the live script, for putting them inside a form of your own:
<x-forms::form method="GET" :action="route('islands.index')">
{{ $filters->embedded() }}
<x-forms::submit>{{ __('Filter') }}</x-forms::submit>
</x-forms::form>
In React, <StencilFields schema={filters} /> does the same.