Компоненты

CardsBuilder

Основы

С помощью CardsBuilder вы можете отображать список элементов в виде карточек. Вы также можете использовать CardsBuilder на своих собственных страницах или даже за пределами MoonShine.

use MoonShine\UI\Components\CardsBuilder;
 
CardsBuilder::make(iterable $items = [], FieldsContract|iterable $fields = [])
use MoonShine\UI\Components\CardsBuilder;
 
CardsBuilder::make(iterable $items = [], FieldsContract|iterable $fields = [])
<x-moonshine::layout.grid>
    <x-moonshine::layout.column colSpan="4" adaptiveColSpan="12">
        <x-moonshine::card
            url="#"
            thumbnail="/images/image_1.jpg"
            :title="fake()->sentence(3)"
            :subtitle="date('d.m.Y')"
            :values="['ID' => 1, 'Author' => fake()->name()]"
        >
            <x-slot:header>
                <x-moonshine::badge color="green">new</x-moonshine::badge>
            </x-slot:header>
 
            {{ fake()->text() }}
 
            <x-slot:actions>
                <x-moonshine::link-button href="#">Read more</x-moonshine::link-button>
            </x-slot:actions>
        </x-moonshine::card>
    </x-moonshine::layout.column>
</x-moonshine::layout.grid>
<x-moonshine::layout.grid>
    <x-moonshine::layout.column colSpan="4" adaptiveColSpan="12">
        <x-moonshine::card
            url="#"
            thumbnail="/images/image_1.jpg"
            :title="fake()->sentence(3)"
            :subtitle="date('d.m.Y')"
            :values="['ID' => 1, 'Author' => fake()->name()]"
        >
            <x-slot:header>
                <x-moonshine::badge color="green">new</x-moonshine::badge>
            </x-slot:header>
 
            {{ fake()->text() }}
 
            <x-slot:actions>
                <x-moonshine::link-button href="#">Read more</x-moonshine::link-button>
            </x-slot:actions>
        </x-moonshine::card>
    </x-moonshine::layout.column>
</x-moonshine::layout.grid>
  • $fields - поля,
  • $items - значения полей.

Основное использование

Пример использования CardsBuilder:

CardsBuilder::make(
    [
        ['id' => 1, 'title' => 'Заголовок 1'],
        ['id' => 2, 'title' => 'Заголовок 2'],
    ],
    [
        ID::make(),
        Text::make('title')
    ]
)
CardsBuilder::make(
    [
        ['id' => 1, 'title' => 'Заголовок 1'],
        ['id' => 2, 'title' => 'Заголовок 2'],
    ],
    [
        ID::make(),
        Text::make('title')
    ]
)

Элементы и поля для CardsBuilder можно указать с помощью соответствующих методов.

Основные методы

Элементы и поля

Метод items() позволяет передать CardsBuilder данные для заполнения карточек.

items(iterable $items = [])
items(iterable $items = [])

Метод fields() позволяет передать CardsBuilder список полей для построения карточки.

fields(FieldsContract|Closure|iterable $fields)
fields(FieldsContract|Closure|iterable $fields)
CardsBuilder::make()
    ->fields([Text::make('Text')])
    ->items([['text' => 'Value']])
CardsBuilder::make()
    ->fields([Text::make('Text')])
    ->items([['text' => 'Value']])

Пагинация

Метод paginator устанавливает пагинатор. Необходимо передать объект, реализующий интерфейс MoonShine\Contracts\Core\Paginator\PaginatorContract.

Если необходимо указать пагинатор для QueryBuilder, можно воспользоваться встроенным ModelCaster, как в примере ниже.

->paginator(
  (new ModelCaster(Article::class))
    ->paginatorCast(
        Article::query()->paginate()
    )
)
->paginator(
  (new ModelCaster(Article::class))
    ->paginatorCast(
        Article::query()->paginate()
    )
)

Пагинатор также можно указать через метод или параметр items.

Отображение

Содержимое

Методы content() используются для добавления произвольного содержимого в карточку.

content(Closure|string $value)
content(Closure|string $value)
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->content('Custom content')
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->content('Custom content')

Название

Метод title() позволяет установить название карточки.

title(Closure|string $value)
title(Closure|string $value)
  • $value - column или замыкание, возвращающее название.
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')

Ссылка

С помощью метода url() можно установить ссылку на заголовок.

url(Closure|string $value)
url(Closure|string $value)
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')
    ->url(fn($data) => $this->getFormPageUrl($data))
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')
    ->url(fn($data) => $this->getFormPageUrl($data))

Подзаголовок

Метод subtitle() позволяет установить подзаголовок карточки.

subtitle(Closure|string $value)
subtitle(Closure|string $value)
  • $value - column или замыкание, возвращающее подзаголовок.
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->title('title')
    ->subtitle(static fn() => 'Subtitle')
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->title('title')
    ->subtitle(static fn() => 'Subtitle')

Миниатюра

Чтобы добавить изображение в карточку, можно использовать метод thumbnail(). В качестве аргумента методы принимают значение поля колонки или замыкание, возвращающее url изображения.

thumbnail(Closure|string $value)
thumbnail(Closure|string $value)
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->thumbnail('thumbnail')
    // or by url
    // ->thumbnail(fn() => 'https://example.com/image.png')
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->thumbnail('thumbnail')
    // or by url
    // ->thumbnail(fn() => 'https://example.com/image.png')

Режим наложения

Режим overlay позволяет разместить заголовок и названия поверх изображения карточки. Этот режим активируется одноименным методом overlay().

CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Text::make('Text')])
    ->cast(new ModelCaster(Article::class))
    ->thumbnail('thumbnail')
    ->header(static fn() => Badge::make('new', 'success'))
    ->title('title')
    ->subtitle(static fn() => 'Subtitle')
    ->overlay()
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Text::make('Text')])
    ->cast(new ModelCaster(Article::class))
    ->thumbnail('thumbnail')
    ->header(static fn() => Badge::make('new', 'success'))
    ->title('title')
    ->subtitle(static fn() => 'Subtitle')
    ->overlay()

Метод header() позволяет установить заголовок для карточек.

Работает только при наличии thumbnail и в режиме overlay.

header(Closure|string $value)
header(Closure|string $value)
  • $value - column или замыкание, возвращающее html код.
CardsBuilder::make()
    ->items(Article::paginate())
    ->thumbnail('image')
    ->overlay()
    ->fields([Text::make('Text')])
    ->header(static fn() => Badge::make('new', 'success'))
    // or by column
    // ->header('title')
CardsBuilder::make()
    ->items(Article::paginate())
    ->thumbnail('image')
    ->overlay()
    ->fields([Text::make('Text')])
    ->header(static fn() => Badge::make('new', 'success'))
    // or by column
    // ->header('title')

Кнопки

Для добавления кнопок на основе ActionButton используйте метод buttons().

CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->cast(new ModelCaster(Article::class))
    ->buttons([
        ActionButton::make('Delete', route('name.delete')),
        ActionButton::make('Edit', route('name.edit'))->showInDropdown(),
        ActionButton::make('Go to Home', route('home'))->blank()->canSee(fn($data) => $data->active),
    ])
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->cast(new ModelCaster(Article::class))
    ->buttons([
        ActionButton::make('Delete', route('name.delete')),
        ActionButton::make('Edit', route('name.edit'))->showInDropdown(),
        ActionButton::make('Go to Home', route('home'))->blank()->canSee(fn($data) => $data->active),
    ])

Колонки

Метод columnSpan() позволяет задать ширину карточек в Grid.

columnSpan(
    int $columnSpan,
    int $adaptiveColumnSpan = 12
)
columnSpan(
    int $columnSpan,
    int $adaptiveColumnSpan = 12
)
  • $columnSpan - значение для десктопной версии,
  • $adaptiveColumnSpan - значение для мобильной версии.
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->columnSpan(3)
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->columnSpan(3)

В админ-панели MoonShine используется 12-колоночная сетка.

Пользовательский компонент

Компонент CardsBuilder позволяет переопределить компонент для построения списка элемента. Для этого нужно воспользоваться методом customComponent().

CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->customComponent(function (Article $article, int $index, CardsBuilder $builder) {
        return Badge::make($index + 1 . "." . $article->title, 'green');
    })
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->customComponent(function (Article $article, int $index, CardsBuilder $builder) {
        return Badge::make($index + 1 . "." . $article->title, 'green');
    })

Асинхронный режим

Если вам нужно получать данные асинхронно (например, при пагинации), то используйте метод async().

Метод async должен быть после метода name

->async(
  Closure|string|null $url = null,
  string|array|null $events = null,
  ?AsyncCallback $callback = null,
)
->async(
  Closure|string|null $url = null,
  string|array|null $events = null,
  ?AsyncCallback $callback = null,
)
  • $url - URL асинхронного запроса (в ответе необходимо вернуть TableBuilder),
  • $events - события, которые будут вызваны после успешного ответа,
  • $callback - JS callback, который можно добавить как обертку ответа.
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->name('my-cards')
    ->async()
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->name('my-cards')
    ->async()

После успешного запроса вы можете вызывать события, добавив параметр events.

CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->name('crud')
    ->async(events: [AlpineJs::event(JsEvent::CARDS_UPDATED, 'crud')])
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->name('crud')
    ->async(events: [AlpineJs::event(JsEvent::CARDS_UPDATED, 'crud')])

Для получения дополнительной информации о js событиях обратитесь к разделу Events.

Для срабатывания события необходимо указать уникальное имя компонента!

Приведение к типу

Метод cast() служит для приведения значений к определенному типу. Так как по умолчанию поля работают с примитивными типами:

use MoonShine\Laravel\TypeCasts\ModelCaster;
 
CardsBuilder::make()
    ->cast(new ModelCaster(User::class))
use MoonShine\Laravel\TypeCasts\ModelCaster;
 
CardsBuilder::make()
    ->cast(new ModelCaster(User::class))

В этом примере мы привели данные к формату модели User с использованием ModelCaster.

За более подробной информацией обратитесь к разделу TypeCasts.

Использование в blade

Основы

<x-moonshine::layout.grid>
    <x-moonshine::layout.column colSpan="4" adaptiveColSpan="12">
        <x-moonshine::card
            url="#"
            thumbnail="/images/image_1.jpg"
            :title="fake()->sentence(3)"
            :subtitle="date('d.m.Y')"
            :values="['ID' => 1, 'Author' => fake()->name()]"
        >
            <x-slot:header>
                <x-moonshine::badge color="green">new</x-moonshine::badge>
            </x-slot:header>
 
            {{ fake()->text() }}
 
            <x-slot:actions>
                <x-moonshine::link-button href="#">Read more</x-moonshine::link-button>
            </x-slot:actions>
        </x-moonshine::card>
    </x-moonshine::layout.column>
</x-moonshine::layout.grid>
<x-moonshine::layout.grid>
    <x-moonshine::layout.column colSpan="4" adaptiveColSpan="12">
        <x-moonshine::card
            url="#"
            thumbnail="/images/image_1.jpg"
            :title="fake()->sentence(3)"
            :subtitle="date('d.m.Y')"
            :values="['ID' => 1, 'Author' => fake()->name()]"
        >
            <x-slot:header>
                <x-moonshine::badge color="green">new</x-moonshine::badge>
            </x-slot:header>
 
            {{ fake()->text() }}
 
            <x-slot:actions>
                <x-moonshine::link-button href="#">Read more</x-moonshine::link-button>
            </x-slot:actions>
        </x-moonshine::card>
    </x-moonshine::layout.column>
</x-moonshine::layout.grid>

Реализуется на основе нескольких компонентов, подробнее в разделах: Card, Grid, Column.