Components

Fragment

Basics

Fragment allows you to wrap a specific area of your page and update only that area by triggering events. The component uses @fragment Laravel Blade directive for this.

make(iterable $components = [])
make(iterable $components = [])
 namespaces
use MoonShine\Crud\Components\Fragment;
use MoonShine\UI\Fields\Text;
 
protected function components(): iterable
{
    return [
        Fragment::make([
            Text::make('Name', 'first_name')
        ])->name('fragment-name')
    ];
}
 namespaces
use MoonShine\Crud\Components\Fragment;
use MoonShine\UI\Fields\Text;
 
protected function components(): iterable
{
    return [
        Fragment::make([
            Text::make('Name', 'first_name')
        ])->name('fragment-name')
    ];
}

Asynchronous Interaction

Update via Events

Fragment::make($components)->name('fragment-name'),
Fragment::make($components)->name('fragment-name'),

For example, let's trigger an event upon successful form submission:

FormBuilder::make()
    ->async(events: AlpineJs::event(JsEvent::FRAGMENT_UPDATED, 'fragment-name'))
FormBuilder::make()
    ->async(events: AlpineJs::event(JsEvent::FRAGMENT_UPDATED, 'fragment-name'))

You can also pass additional parameters with the request via an array:

Fragment::make($components)
    ->name('fragment-name')
    ->updateWith(params: ['resourceItem' => request('resourceItem')]),
Fragment::make($components)
    ->name('fragment-name')
    ->updateWith(params: ['resourceItem' => request('resourceItem')]),

Passing Parameters

The method withSelectorsParams() allows you to pass field values with the request using element selectors.

Fragment::make($components)
    ->withSelectorsParams([
        'start_date' => '#start_date',
        'end_date' => '#end_date'
    ])
    ->name('fragment-name'),
Fragment::make($components)
    ->withSelectorsParams([
        'start_date' => '#start_date',
        'end_date' => '#end_date'
    ])
    ->name('fragment-name'),

Triggering Events

Upon successful update, Fragment can also trigger additional events. Consider an example of updating fragments sequentially when clicking a button:

Fragment::make([
    FlexibleRender::make('<p> Step 1: ' . time() . '</p>')
])
    ->updateWith(
        events: [
            AlpineJs::event(JsEvent::FRAGMENT_UPDATED, 'fg-step-2'),
        ],
    )
    ->name('fg-step-1'),
 
Fragment::make([
    FlexibleRender::make('<p> Step 2: ' . time() . '</p>')
])
    ->name('fg-step-2'),
 
// ...
 
ActionButton::make('Start')
    ->dispatchEvent([AlpineJs::event(JsEvent::FRAGMENT_UPDATED, 'fg-step-1')]),
Fragment::make([
    FlexibleRender::make('<p> Step 1: ' . time() . '</p>')
])
    ->updateWith(
        events: [
            AlpineJs::event(JsEvent::FRAGMENT_UPDATED, 'fg-step-2'),
        ],
    )
    ->name('fg-step-1'),
 
Fragment::make([
    FlexibleRender::make('<p> Step 2: ' . time() . '</p>')
])
    ->name('fg-step-2'),
 
// ...
 
ActionButton::make('Start')
    ->dispatchEvent([AlpineJs::event(JsEvent::FRAGMENT_UPDATED, 'fg-step-1')]),

Response Handling

Details in the Js section

Fragment::make($components)
    ->updateWith(
        callback: AsyncCallback::with(afterResponse: 'afterResponseFunction')
    )
    ->name('fragment-name'),
Fragment::make($components)
    ->updateWith(
        callback: AsyncCallback::with(afterResponse: 'afterResponseFunction')
    )
    ->name('fragment-name'),

URL Query Parameters

You can include parameters of the current URL request (e.g., ?param=value) in the fragment request:

This will preserve all parameters from the current request URL when loading the fragment.

Fragment::make($components)
    ->name('fragment-name')
    ->withQueryParams(),
Fragment::make($components)
    ->name('fragment-name')
    ->withQueryParams(),

Update on Page Load

The updateOnLoad() method sends a single asynchronous request to update the fragment after the page's DOMContentLoaded event. It works independently of autoUpdate() and does not enable periodic updates.

updateOnLoad(Closure|bool $condition = true): static
updateOnLoad(Closure|bool $condition = true): static

Pass false to disable the initial update, or a closure that receives the current Fragment and returns bool. The closure is evaluated when the component is rendered.

 namespaces
use MoonShine\Crud\Components\Fragment;
use MoonShine\UI\Components\Metrics\Wrapped\ValueMetric;
 
Fragment::make([
    ValueMetric::make('Metric')
        ->value(random_int(1, 1000)),
])
    ->name('fragment-metric')
    ->updateOnLoad(),
 namespaces
use MoonShine\Crud\Components\Fragment;
use MoonShine\UI\Components\Metrics\Wrapped\ValueMetric;
 
Fragment::make([
    ValueMetric::make('Metric')
        ->value(random_int(1, 1000)),
])
    ->name('fragment-metric')
    ->updateOnLoad(),

To enable the initial update conditionally:

 namespaces
use MoonShine\Crud\Components\Fragment;
 
Fragment::make($components)
    ->name('fragment-metric')
    ->updateOnLoad(fn (Fragment $fragment): bool => $fragment->getName() === 'fragment-metric'),
 namespaces
use MoonShine\Crud\Components\Fragment;
 
Fragment::make($components)
    ->name('fragment-metric')
    ->updateOnLoad(fn (Fragment $fragment): bool => $fragment->getName() === 'fragment-metric'),

Combine updateOnLoad() with autoUpdate() to update the fragment once after the page loads and then at the specified interval. Subsequent asynchronous fragment responses do not trigger another initial update.

Auto-update

The autoUpdate() method allows you to automatically update the fragment content at a specified interval.

autoUpdate(int $ms)
autoUpdate(int $ms)
  • $ms — update interval in milliseconds (must be greater than 0).
 namespaces
use MoonShine\Crud\Components\Fragment;
use MoonShine\UI\Components\Metrics\Wrapped\ValueMetric;
 
Fragment::make([
    ValueMetric::make('Metric')
        ->value(random_int(1, 1000))
        ->columnSpan(6),
])
    ->name('fragment-metric')
    ->withQueryParams()
    ->autoUpdate(5000),
 namespaces
use MoonShine\Crud\Components\Fragment;
use MoonShine\UI\Components\Metrics\Wrapped\ValueMetric;
 
Fragment::make([
    ValueMetric::make('Metric')
        ->value(random_int(1, 1000))
        ->columnSpan(6),
])
    ->name('fragment-metric')
    ->withQueryParams()
    ->autoUpdate(5000),

In this example, the fragment with the metric will automatically update every 5 seconds.