Settings
Settings are the fields an editor fills in for a section, block or site settings group. They're declared with the fluent Settings builder, or - on a class-based section or block - with attributes on constructor parameters.
Field types
| Fluent | Attribute | Value in your view |
|---|---|---|
text() |
#[Text] |
string |
textarea() |
#[Textarea] |
string |
richtext() |
#[Richtext] |
sanitised HTML string |
number() |
#[Number] |
int or float |
toggle() |
#[Toggle] |
bool |
select() |
#[Select] |
a backed enum case, or the option's key |
image() |
#[Image] |
ImageValue |
link() |
#[Link] |
LinkValue |
repeater() |
- | array of items |
group() |
- | array |
blocks() |
- | BlockList - see Blocks |
Fluent settings
use WeArePixel\Inlay\Schema\Settings;
Settings::make()
->text('heading')->label('Heading')->maxLength(80)->required()->default('Welcome')
->textarea('intro')->label('Intro')->help('Shown under the heading.')->default('')
->toggle('showCta')->label('Show call to action')->default(false)
->select('alignment')->label('Alignment')->options(['left' => 'Left', 'center' => 'Centred'])->default('left');
Each field method (text(), textarea(), richtext(), number(), toggle(), select(), image(), link(), repeater(), group(), blocks()) starts a new field. The modifiers that follow - label(), help(), required(), maxLength(), visibleWhen(), hiddenWhen(), options(), default(), badge() - apply to the most recent field.
On a class-based section, return the builder from a static settings() method:
public function __construct(
public array $items = [],
) {}
public static function settings(): Settings
{
return Settings::make()->repeater('items', Settings::make()
->text('question')->label('Question')->required()
->textarea('answer')->label('Answer'))->label('FAQ items');
}
Attribute settings
On a class-based section or block, declare a setting on the constructor parameter it maps to:
use WeArePixel\Inlay\Attributes\Number;
use WeArePixel\Inlay\Attributes\Select;
use WeArePixel\Inlay\Attributes\Text;
use WeArePixel\Inlay\Attributes\Toggle;
public function __construct(
#[Text(label: 'Heading', maxLength: 80, required: true)]
public string $heading = 'Welcome',
#[Toggle(label: 'Show call to action')]
public bool $showCta = false,
#[Number(label: 'Columns')]
public int $columns = 2,
#[Select(label: 'Image size')]
public ImageSize $imageSize = ImageSize::Large,
) {}
Every attribute accepts label, help, required and visibleWhen (a [field, value] pair). Text also accepts maxLength; Select accepts options when the parameter isn't a backed enum. There are no repeater, group or blocks attributes - those have no single parameter to attach to, so declare them fluently.
A section can mix both. When both declare the same name, the fluent declaration wins.
Defaults
- Single-file sections and blocks:
->default()is required on every top-level field. - Class-based: the constructor parameter's default and nullability are the source of truth for top-level fields.
->default()is only meaningful for fields nested in a repeater or group.
Repeaters and groups
repeater() is a list of items sharing one schema; group() is a single nested object:
Settings::make()
->repeater('items', Settings::make()
->text('question')->label('Question')
->textarea('answer')->label('Answer'))->label('Questions')->default([])
->group('address', Settings::make()
->text('street')->label('Street')
->text('city')->label('City'))->label('Address')->default([]);
Editors add and remove repeater items in the inspector. A repeater or group can't contain a blocks() field.
Settings carry references, not copies of your data. Store an ID and query for the record in your view or component, so the page always reflects your database.
Enums
A select field backed by a PHP backed enum gets its options from the enum. The stored value is the case's scalar value; the case is hydrated back before rendering.
->select('imageSize')->label('Image size')->options(ImageSize::class)->default(ImageSize::Large)
Option labels default to Str::headline($case->name). Implement WeArePixel\Inlay\Support\SettingOptions for your own, and WeArePixel\Inlay\Support\DescribesSettingOptions to show a description under the field when an option is selected:
use WeArePixel\Inlay\Support\DescribesSettingOptions;
use WeArePixel\Inlay\Support\SettingOptions;
enum ImageSize: string implements SettingOptions, DescribesSettingOptions
{
case Small = 'small';
case Large = 'large';
public function label(): string
{
return match ($this) {
self::Small => 'Small (400px)',
self::Large => 'Large (1200px)',
};
}
public function optionDescription(): ?string
{
return $this === self::Large ? 'Full width, best for a strong first impression.' : null;
}
}
A stored value whose case has since been removed falls back to the default and logs a warning.
Links
link() hydrates to WeArePixel\Inlay\Support\LinkValue, with label, url and openInNewTab:
@if ($cta->url !== '')
<a href="{{ $cta->url }}" @if ($cta->openInNewTab) target="_blank" rel="noopener" @endif>{{ $cta->label }}</a>
@endif
Only http://, https://, mailto: and relative URLs are stored. Anything else, such as javascript:, is rejected when it's saved, so $cta->url is safe to put in an href.
A single-file default is a LinkValue: ->link('cta')->default(new LinkValue('Find out more', '#')).
Images
image() hydrates to WeArePixel\Inlay\Support\ImageValue. Echoing it gives the URL, resolved against config('inlay.disk'):
@unless ($photo->isEmpty())
<img src="{{ $photo }}" alt="">
@endunless
A root-relative path such as /images/hero.jpg is a file your app serves itself and is used as-is - that's how a section ships a default image without an upload:
->image('photo')->label('Photo')->default('/images/hero.jpg') // '' for no image
On a class-based section, type the parameter ?ImageValue $photo = null for "no image" to be null, so @if ($photo) works. A non-nullable ImageValue is always an object, so check isEmpty(). Use $photo->url() where you need the string outside a Blade echo.
Optional images and links
An image or link field that isn't required() gets a Remove button in the inspector, which clears it back to empty.
Rich text
richtext() values are sanitised before they're stored - from the editor, from site settings and from MCP tools. Allowed: p, br, strong, b, em, i, u, s, a, ul, ol, li, h2, h3, h4, blockquote, code, pre, hr and span. Scripts, event handlers, inline styles, iframes and links other than http(s) and mailto are removed. Render the value with {!! $body !!}.
The rich text field is currently an HTML textarea; a formatting toolbar is on the roadmap.