Skip to content
stencil / 1

Custom fields

Last updated:

On this page

A field type is three things: a PHP class, a Blade view and a React component. Packages and apps add their own.

Generate one

php artisan make:stencil-field Rating

It writes:

File What
app/Stencil/Fields/Rating.php The class: its type (rating), its view, a max() option, rules and props
resources/views/stencil/fields/rating.blade.php The Blade view
resources/js/stencil/fields/Rating.tsx The React component

Pass --force to overwrite files that exist.

The class

namespace App\Stencil\Fields;

use Closure;
use Javaabu\Stencil\Fields\Field;

class Rating extends Field
{
    protected string $type = 'rating';

    protected ?string $view = 'stencil.fields.rating';

    protected int|Closure $max = 5;

    public function max(int|Closure $max): static
    {
        $this->max = $max;

        return $this;
    }

    protected function getTypeRules(): array
    {
        return ['integer', 'min:1', "max:{$this->evaluate($this->max)}"];
    }

    protected function getFieldProps(): array
    {
        return ['max' => $this->evaluate($this->max)];
    }
}
Rating::make('stars')->label(__('Stars'))->max(10)->required();

Everything from Field works: labels, help, required(), closures, conditions, live, validation and saving. Override what your type needs:

Method For
setUp() Defaults, called by make()
getFieldProps() Props for the view and the component; null values are left out
getTypeRules() Rules that come with the type
getAllValidationRules() Rules for other keys, such as name.*
readFromRecord(), normalizeState() Reading the value from the record
castDehydratedState() The value returned from validate()
getInputName(), getSelector() The submitted name (tags[]), and the selector conditions watch
savesToAttribute() + SavesRelationships Saving somewhere other than an attribute, after the model is saved

A field that renders as a javaabu/forms component sets protected ?string $component = 'text' instead of a view, and both drivers render that component with its props.

The Blade view

The view gets $node (the resolved field: name, key, props, prop()) and $stencil (the Blade renderer):

<x-forms::form-group :name="$node->name" :label="$node->prop('label', '')" :required="(bool) $node->prop('required')">
    <input type="number" id="{{ $node->name }}" name="{{ $node->name }}" value="{{ $stencil->value($node) }}" max="{{ $node->prop('max') }}">
    <x-forms::errors :name="$node->name" />
</x-forms::form-group>
Helper What
$stencil->value($node) The field's value: old input, then the form's state
$stencil->component('text', [...props]) A javaabu/forms component with props
$stencil->field($node, [...override]) The field's own component
$stencil->children($nodes, $columns) Child nodes, for container types

Instead of $view in the class, register the view for the type, for example in a package:

Stencil::view('rating', 'my-package::stencil.rating');

The React component

import { FormGroup, useFieldValue } from "@javaabu/forms"
import type { StencilComponentProps } from "@javaabu/stencil"

export function Rating({ node }: StencilComponentProps) {
  const name = node.name ?? node.key
  const value = useFieldValue(name, undefined, undefined)
  return (
    <FormGroup name={name} label={node.props?.label as string} required={node.props?.required as boolean}>
      <input type="number" id={name} name={name} defaultValue={String(value ?? "")} max={node.props?.max as number} />
    </FormGroup>
  )
}

Register it by type with StencilProvider components={{ rating: Rating }} (see React). A package that ships React components exports them from its own resources/js through javaabu/manifest, and tells apps to register them.

Documentation
All packages

javaabu/stencil

Source on GitHub