Form Management
Forms describe the fields that a page shows and the values that it accepts. Unicorn builds each form from a form class, where each method adds fields to the form. The same form class supplies the fields for the page, filters the submitted data, and validates it before it is saved. This page covers how to add fields, group them, and render them in the layouts.
Adding Fields and Filling Values
Each method marked with #[FormDefine] adds fields to the form. Use #[NS] to set the data namespace of the fields:
use Windwalker\Form\Attributes\FormDefine;
use Windwalker\Form\Attributes\NS;
use Windwalker\Form\Field\TextField;
use Windwalker\Form\Form;
class ProductEditForm
{
#[FormDefine]
#[NS('item')]
public function main(Form $form): void
{
$form->add('title', TextField::class)
->label('Title')
->required(true);
}
}Fill the form with data before you render it. The generated edit view fills the item namespace from the record, then from the state that holds the last failed input:
$form = $this->createForm(ProductEditForm::class)
->fillTo('item', $this->orm->extractEntity($item))
->fillTo(
'item',
$this->repository->getState()->getAndForget('edit.data')
);fill() fills the whole form from an array. fillTo() fills only the given namespace path.
Fieldsets and Layouts
A fieldset groups fields for the layout. Add #[Fieldset] to the method to place its fields in a named group:
use Windwalker\Form\Attributes\Fieldset;
#[FormDefine]
#[Fieldset('meta')]
#[NS('item')]
public function meta(Form $form): void
{
$form->add('state', SwitcherField::class)
->label('Published');
}Print each fieldset in the blade template with <x-fieldset>:
<x-fieldset name="basic" :form="$form" is="card"></x-fieldset>
<x-fieldset name="meta" :form="$form" is="card"></x-fieldset>To print a single field, pass the field object to <x-field>:
<x-field :field="$form->getField('item/title')"></x-field>Nested Data with Namespaces
Fieldsets are flat. Each fieldset is a named group at the form level, so a fieldset cannot contain another fieldset. To nest the submitted data, use a namespace path with /:
#[FormDefine]
#[Fieldset('seo')]
#[NS('item/params')]
public function seo(Form $form): void
{
$form->add('meta_title', TextField::class)
->label('Meta title');
$form->add('meta_description', TextareaField::class)
->label('Meta description');
}The fields in this method submit their values under item, then params. The layout still prints the group with <x-fieldset name="seo">. Keep the fieldset name and the namespace separate: the name controls where the field appears, and the namespace controls the shape of the data.
Generating Fields from a Table
The build:form command adds fields for the columns of a table to an existing form class. Create the edit form first, so that the class exists:
php windwalker build:form Admin/Product/ProductEditForm productThe command reads the class in App\Module, and then adds one field for each column that the class does not define yet. Existing fields are kept. The field type follows the column type:
- Auto-increment columns use
HiddenField. stateandtinyint(1)columns useSwitcherField.datetimeandtimestampcolumns useCalendarField.- Integer, float, and decimal columns use
NumberField. text,mediumtext, andlongtextcolumns useTextareaField.- Other columns use
TextField, with thetrimfilter.
Pass a language key prefix with --use-lang to translate the labels:
php windwalker build:form Admin/Product/ProductEditForm product \
--use-lang jojo.product.fieldColumns with a shared Unicorn key, such as state and created_by, use that key. Other columns use jojo.product.field.{column}.
WARNING
The command writes the form class in place. Run it with --dry-run to check the result without writing the file, and keep the file under version control before you run it.
To change the generated code for one column, listen to Unicorn\Form\Event\BuildFormFieldEvent and set its code property.
Filters and Validation
Filters change a value before it is validated and saved. Validators check the value and fail the save when a rule is broken. Add both to the field:
$form->add('title', TextField::class)
->addFilter('trim')
->addValidator('required');
$form->add('contact', TextField::class)
->addValidator('email');The required(true) method is a shortcut for the required rule. For the rules that the edit page uses on save, see Edit Management.
How the Form Filters Submitted Data
Form::filter() returns the part of the submitted data that the form defines. The save uses this filter first, so a key that no field defines never reaches the entity. The second argument changes what is kept:
// Keep only the keys that the form defines (the default).
$clean = $form->filter($data);
// Keep every submitted key, including undefined ones.
$all = $form->filter($data, Form::FILTER_KEEP_DATA);
// Fill a missing or empty value with the field's default.
$withDefaults = $form->filter($data, Form::FILTER_USE_DEFAULT_VALUE);Without FILTER_USE_DEFAULT_VALUE, a missing key is skipped and an empty value stays empty. The generated save does not use the default-value option, so defaultValue() does not fill a value on save. See Edit Management for how to store a default.
Options from Enums
Fill a list field from an enum with registerFromEnums(). The labels go through the language service. The generated grid filter uses this method for the state field:
use Unicorn\Enum\BasicState;
use Windwalker\Form\Field\ListField;
$form->add('state', ListField::class)
->label($this->trans('unicorn.field.state'))
->option($this->trans('unicorn.select.placeholder'), '')
->registerFromEnums(BasicState::class, $this->lang);Add a leading option with option() for an empty choice, such as a placeholder. The enum cases follow it.
Custom Field Layouts
Use LayoutField to render a field with your own template. Extend the class, and return the template name from getDefaultLayout():
use Unicorn\Field\LayoutField;
class ColorSwatchField extends LayoutField
{
public function getDefaultLayout(): string
{
return 'fields.color-swatch';
}
}The template name is a renderer template that your project provides. The template receives $input, $field, and $options:
{{-- fields/color-swatch.blade.php --}}
<div class="color-swatch">
{!! $input !!}
</div>To use a different template for one field, call layout():
$form->add('color', ColorSwatchField::class)
->layout('fields.color-swatch-large');Grid Filters and Batch Fields
The grid form has three namespaces. The generated form defines search[*], filter[...], and batch[...]. Add a filter by adding a field to the filter namespace:
#[FormDefine]
#[NS('filter')]
public function category(Form $form): void
{
$form->add('product.category_id', ListField::class)
->label('Category')
->option('- Select category -', '')
->option('Books', '1')
->option('Music', '2')
->onchange('this.form.submit()');
}The filter name uses the table column, product.category_id. The list selector allows it because it is a column of the query. See List Management for how filter values reach the query.
Fields in the batch namespace use entity property names, not table aliases. The batch modal shows when the form has batch fields. See Advanced Grid Features for batch examples.
Adding a Create Modal
A grid form can also define a group for another purpose, such as a dialog that creates a record. This example adds a create fieldset in the item namespace, so the dialog can post to the edit route:
#[FormDefine]
#[Fieldset('create')]
#[NS('item')]
public function create(Form $form): void
{
$form->add('title', TextField::class)
->label('Title')
->addFilter('trim')
->required(true);
}Place the button and the dialog after the admin-form form in the list blade. The dialog must not be inside the grid form, because nested forms are not valid HTML:
<button type="button" class="btn btn-success"
data-bs-toggle="modal" data-bs-target="#create-modal">
New Product
</button>
<div class="modal fade" id="create-modal" tabindex="-1">
<div class="modal-dialog">
<form method="post" action="{{ $nav->to('product_edit') }}">
<div class="modal-body">
<x-fieldset name="create" :form="$form"></x-fieldset>
</div>
<div class="modal-footer">
<x-csrf></x-csrf>
<button type="submit" class="btn btn-primary">
Create
</button>
</div>
</form>
</div>
</div>The form posts to the edit route. The controller saves the new record and redirects to its edit page, where the user can continue editing.