webkernel/platform-schemas

03-sections

Sur cette page

title: Sections

Introduction

You may want to separate your fields into sections, each with a heading and description. To do this, you can use a section component:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])

<UtilityInjection set="schemaComponents">As well as allowing static values, the make() and description() methods also accept functions to dynamically calculate them. You can inject various utilities into the function as parameters.</UtilityInjection>

You can also use a section without a header, which just wraps the components in a simple card:

use Webkernel\Platform\Schemas\Components\Section;

Section::make()
    ->schema([
        // ...
    ])

Adding an icon to the section's header

You may add an icon to the section's header using the icon() method:

use Webkernel\Platform\Schemas\Components\Section;
use Webkernel\Platform\Support\Icons\Heroicon;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->icon(Heroicon::ShoppingBag)
    ->schema([
        // ...
    ])

<UtilityInjection set="schemaComponents">As well as allowing a static value, the icon() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>

Positioning the heading and description aside

You may use the aside() to align heading & description on the left, and the components inside a card on the right:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->aside()
    ->schema([
        // ...
    ])

Optionally, you may pass a boolean value to control if the section should be aside or not:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->aside(FeatureFlag::active())
    ->schema([
        // ...
    ])

<UtilityInjection set="schemaComponents">As well as allowing a static value, the aside() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>

Collapsing sections

Sections may be collapsible() to optionally hide long content:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()

Your sections may be collapsed() by default:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsed()

Optionally, the collapsible() and collapsed() methods accept a boolean value to control if the section should be collapsible and collapsed or not:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible(FeatureFlag::active())
    ->collapsed(FeatureFlag::active())

<UtilityInjection set="schemaComponents">As well as allowing static values, the collapsible() and collapsed() methods also accept functions to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>

If a collapsed section contains components that are expensive to render, you can defer the loading of its content until the section is expanded.

Persisting collapsed sections in the user's session

You can persist whether a section is collapsed in local storage using the persistCollapsed() method, so it will remain collapsed when the user refreshes the page:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()
    ->persistCollapsed()

To persist the collapse state, the local storage needs a unique ID to store the state. This ID is generated based on the heading of the section. If your section does not have a heading, or if you have multiple sections with the same heading that you do not want to collapse together, you can manually specify the id() of that section to prevent an ID conflict:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()
    ->persistCollapsed()
    ->id('order-cart')

Optionally, the persistCollapsed() method accepts a boolean value to control if the section should persist its collapsed state or not:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()
    ->persistCollapsed(FeatureFlag::active())

<UtilityInjection set="schemaComponents">As well as allowing static values, the persistCollapsed() and id() methods also accept functions to dynamically calculate them. You can inject various utilities into the function as parameters.</UtilityInjection>

Compact section styling

When nesting sections, you can use a more compact styling:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])
    ->compact()

Optionally, the compact() method accepts a boolean value to control if the section should be compact or not:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])
    ->compact(FeatureFlag::active())

<UtilityInjection set="schemaComponents">As well as allowing a static value, the compact() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>

Secondary section styling

By default, sections have a contrasting background color, which makes them stand out against a gray background. Secondary styling gives the section a less contrasting background, so it is usually slightly darker. This is a better styling when the background color behind the section is the same color as the default section background color, for example when a section is nested inside another section. Secondary sections can be created using the secondary() method:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Notes')
    ->schema([
        // ...
    ])
    ->secondary()
    ->compact()

Optionally, the secondary() method accepts a boolean value to control if the section should be secondary or not:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Notes')
    ->schema([
        // ...
    ])
    ->secondary(FeatureFlag::active())

Inserting actions and other components in the header of a section

You may insert actions and any other schema component (usually prime components) into the header of a section by passing an array of components to the afterHeader() method:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->afterHeader([
        Action::make('test'),
    ])
    ->schema([
        // ...
    ])

<UtilityInjection set="schemaComponents">As well as allowing a static value, the afterHeader() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>

Inserting actions and other components in the footer of a section

You may insert actions and any other schema component (usually prime components) into the footer of a section by passing an array of components to the footer() method:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])
    ->footer([
        Action::make('test'),
    ])

<UtilityInjection set="schemaComponents">As well as allowing a static value, the footer() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>

Using grid columns within a section

You may use the columns() method to easily create a grid within the section:

use Webkernel\Platform\Schemas\Components\Section;

Section::make('Heading')
    ->schema([
        // ...
    ])
    ->columns(2)

<UtilityInjection set="schemaComponents">As well as allowing a static value, the columns() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>

Deferring the loading of section content

If the content of a section is expensive to render, you can pass a Schema object to schema() and use deferLoading(). This is particularly useful for a section that is collapsed by default. The section and its header will render immediately, while its content will not be loaded until the section is expanded and the content enters the viewport:

use Webkernel\Platform\Forms\Components\TextInput;
use Webkernel\Platform\Schemas\Components\Section;
use Webkernel\Platform\Schemas\Schema;

Section::make('Customer details')
    ->key('customerDetails')
    ->schema(
        Schema::make()
            ->components([
                TextInput::make('name'),
                TextInput::make('email')
                    ->email(),
            ])
            ->deferLoading(),
    )
    ->collapsed()

Every deferred schema must have a unique key. In this example, the child schema inherits its key from the section. You can learn more in the schema overview.