Docs / Developer guide

Adding a home-page section

Create a new section type that appears in the Home builder, with fields, data and a Blade view.

Home-page sections are PHP classes in app/Themes/Sections that extend Section, paired with Blade views in resources/views/front/home/sections/{type}/{variant}.blade.php. The Home builder discovers them automatically and builds the edit form from their fields().

1. Create the class#

app/Themes/Sections/Highlights.php:

<?php

namespace App\Themes\Sections;

use App\Models\HomeSection;

class Highlights extends Section
{
    public function type(): string { return 'highlights'; }

    public function label(): string { return __('Highlights'); }

    public function description(): string { return __('Three short feature blurbs.'); }

    public function icon(): string { return 'award'; }

    /** Layout variants: key => label. Each needs a view file. */
    public function variants(): array
    {
        return ['default' => __('Three columns')];
    }

    /** The fields shown in the Home builder. */
    public function fields(): array
    {
        return array_merge($this->headFields([
            'anchor' => 'highlights', 'eyebrow' => 'Why us', 'title' => 'Made to last',
            'link_text' => '', 'link_url' => '',
        ]), [
            ['name' => 'items', 'type' => 'repeater', 'label' => __('Items'), 'default' => [], 'fields' => [
                ['name' => 'title', 'type' => 'text', 'label' => __('Title'), 'translatable' => true],
                ['name' => 'text', 'type' => 'textarea', 'label' => __('Text'), 'translatable' => true],
            ]],
        ]);
    }

    /** Data passed to the view. Read the saved values with $this->settings($row). */
    public function data(HomeSection $row): array
    {
        return ['items' => $this->settings($row)['items'] ?? []];
    }

    /** Return true to hide the section when it has nothing to show. */
    public function isEmpty(array $data, array $settings): bool
    {
        return empty($data['items']);
    }
}

The example uses the same helpers (headFields, settings) as the built-in Brands section; open app/Themes/Sections/Brands.php as a working reference. Field types used by the built-in sections include text, textarea, number, brands, repeater and products_source (a product source picker).

2. Register it#

Add the class name to the section_classes list in config/themes.php:

'section_classes' => [
    \App\Themes\Sections\Highlights::class,
],

Core sections are registered in App\Themes\SectionRegistry; extra classes from section_classes are merged with them.

3. Create the view#

resources/views/front/home/sections/highlights/default.blade.php (the path is front.home.sections.{type}.{variant}). The view receives the array returned by data(), plus $settings (the saved field values), $anchor, $uid and $theme. Use the kit's mk-* classes and the shared <x-front.section-head> component so the section follows the active preset.

<section @if ($anchor) id="{{ $anchor }}" @endif class="mk-section scroll-mt-32">
    <div class="container">
        <x-front.section-head :eyebrow="$settings['eyebrow'] ?? null" :title="$settings['title'] ?? ''" />
        <div class="grid gap-6 md:grid-cols-3">
            @foreach ($items as $item)
                <div>
                    <h3>{{ $item['title'] ?? '' }}</h3>
                    <p>{{ $item['text'] ?? '' }}</p>
                </div>
            @endforeach
        </div>
    </div>
</section>

Open resources/views/front/home/sections/brands/logo_strip.blade.php for the full pattern, including the section-head link arguments and accessibility attributes.

4. Use it#

Run php artisan config:clear and php artisan view:clear, open Appearance > Home builder, click Add section, pick Highlights, fill it in and save.

Tip

Sections that need data from the store (products, categories, brands, banners) should use the shared source fields so shoppers' currency, stock and flash-sale prices are handled for you. Read Concerns/ in app/Themes/Sections and the existing ProductCarousel section.