Docs / Inlay / Settings

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.

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.

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.

Discovery Call

One call.
We'll both know.

20 minutes to walk through your project, ask the hard questions, and work out honestly if we're the right team for it.

  • One call per day - it gets our full attention
  • Australia's only Laravel Premier Partner
  • Trusted by Chemist Warehouse, HelloFresh and Youfoodz
  • Senior engineers only - no juniors on your project
  • Brisbane-based, onshore team

Press Esc to close  ·  B to reopen